{
  "markdown": "# A2Me MCP Server\n\n> **v1 · read-only.** A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **read-only, privacy-redacted** family-context tools for the [A2Me](https://a2me.app) family social platform — so assistants like Claude, ChatGPT, or KAI can answer \"when is mom's birthday?\" or help write a message to grandma, scoped to your own family.\n\nHosted at **`https://mcp.a2me.app/mcp`** and used in production for A2Me's [Connect a2me](https://a2me.app/features/ai-integration) feature.\n\n## Connect from an AI assistant\n\nIn Claude or ChatGPT, add a **custom connector** using the URL:\n\n```\nhttps://mcp.a2me.app/mcp\n```\n\nYou'll be sent through OAuth to sign in to A2Me and grant **read-only** access; the assistant then has family-aware context scoped to your account.\n\n## Run it locally\n\n```bash\nnpm install\nnpm run dev        # stdio transport, mock data by default\n```\n\nIt runs on **stdio** by default (for local MCP clients) and supports a remote **HTTP** transport (`MCP_TRANSPORT=http`) for the hosted deployment. By default it uses **mock data** (`A2ME_USE_MOCK=true`); set `A2ME_API_URL` + `A2ME_USE_MOCK=false` to call a real API. See [`.env.example`](./.env.example).\n\n## Available Tools\n\n| Tool                              | Description                                                         |\n| --------------------------------- | ------------------------------------------------------------------- |\n| `get_family_members`              | Returns the user's family members with relationship labels          |\n| `get_upcoming_family_dates`       | Birthdays, anniversaries, and events in the next N days             |\n| `get_recent_family_activity`      | Recent posts, photos, videos, birthday cards                        |\n| `get_person_profile`              | A family member's profile, interests, and activity summary          |\n| `get_relationship_between_people` | How two family members are related                                  |\n| `get_birthday_card_context`       | Context for writing a birthday card (memories, interests, tone)     |\n| `find_family_member`              | Fuzzy search by name or relationship (\"mom\", \"my grandmother\")      |\n| `answer_family_date_question`     | Natural language date questions (\"When is mom's birthday?\")         |\n| `get_message_context_for_person`  | Context for writing a message with suggestions                      |\n| `get_upcoming_events`             | Upcoming events with the user's RSVP status and RSVP counts         |\n| `get_trip_overview`               | A trip's dates, roster, travel details (flights/lodging), itinerary |\n| `get_life_story`                  | A family member's life story chapters (or recent story answers)     |\n| `get_unanswered_story_questions`  | Unanswered story questions — interview prep for a visit             |\n| `get_person_wishlist`             | A family member's wishlist for gift ideas                           |\n| `search_family_memories`          | Keyword search over recent family posts and memories                |\n| `whats_new`                       | Catch-up bundle: recent posts + what's coming up                    |\n\n## Prompts\n\nThe server also exposes **prompts** — one-click starting points that appear as\nconnector commands in Claude (and suggestions in ChatGPT), so users get value without\nknowing tool names. Each steers the assistant to the read-only tools above:\n\n| Prompt                  | What it does                                           |\n| ----------------------- | ------------------------------------------------------ |\n| `write_birthday_card`   | Draft a birthday card grounded in a person's context   |\n| `write_family_message`  | Draft a message for any occasion/tone                  |\n| `family_catch_up`       | Summarize what's new with the family                   |\n| `upcoming_family_dates` | List upcoming birthdays/anniversaries with suggestions |\n| `about_person`          | Warm summary of a family member and how you're related |\n\nThe `person` argument on these prompts **autocompletes from your family roster**\n(names + relationship labels) as you type — MCP argument completion, scoped to your\nfamily. See [`src/prompts/index.ts`](src/prompts/index.ts) and\n[`src/completions.ts`](src/completions.ts).\n\n## Example Scenarios\n\n1. **\"Help me write a birthday card for my sister\"**\n   - `find_family_member` → resolves \"my sister\" to Sarah Walker\n   - `get_birthday_card_context` → returns interests (painting, hiking, coffee), tone suggestions\n\n2. **\"When is grandma's birthday?\"**\n   - `answer_family_date_question` → returns Margaret Walker's birthday (November 8)\n\n3. **\"What's been happening in the family?\"**\n   - `get_recent_family_activity` → returns recent posts, photos, events\n\n4. **\"Help me write a thank you message to my dad\"**\n   - `get_message_context_for_person` → returns Robert Walker's context, interests, suggestions\n\n5. **\"Who's in my family?\"**\n   - `get_family_members` → returns all family members with relationships\n\n6. **\"What events are coming up?\"**\n   - `get_upcoming_family_dates` → returns upcoming birthdays, anniversaries, events\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    MCP Client (LLM)                       │\n│              (Claude, ChatGPT, KAI, etc.)                │\n└───────────────────────┬─────────────────────────────────┘\n                        │ stdio (MCP Protocol)\n┌───────────────────────▼─────────────────────────────────┐\n│                  A2Me MCP Server                          │\n│  ┌─────────────────────────────────────────────────┐    │\n│  │              Tool Registry (16 tools)             │    │\n│  └──────────────────────┬──────────────────────────┘    │\n│                         │                                │\n│  ┌──────────────────────▼──────────────────────────┐    │\n│  │         Family Context Resolver                   │    │\n│  │   (fuzzy matching, relationship resolution)       │    │\n│  └──────────────────────┬──────────────────────────┘    │\n│                         │                                │\n│  ┌──────────────────────▼──────────────────────────┐    │\n│  │            A2Me API Client                        │    │\n│  │   (currently mock, future: real HTTP calls)       │    │\n│  └──────────────────────┬──────────────────────────┘    │\n│                         │                                │\n│  ┌──────────────────────▼──────────────────────────┐    │\n│  │            Auth Context                           │    │\n│  │   (currently mock, future: OAuth/Firebase)        │    │\n│  └─────────────────────────────────────────────────┘    │\n└─────────────────────────────────────────────────────────┘\n                        │ (future)\n┌───────────────────────▼─────────────────────────────────┐\n│                   A2Me REST API                           │\n│               (kinnectd-api service)                     │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Authentication\n\nCurrently uses **mock authentication** — always returns an authenticated user (\"Alex Walker\") for local development.\n\n**Future production integration:**\n\n- OAuth2/Firebase token validation via A2Me API\n- Token passed via MCP session context or environment\n- Per-user data isolation (users only see their own family)\n\n## Required A2Me API Endpoints (Future)\n\n| Method | Endpoint                             | Description                          |\n| ------ | ------------------------------------ | ------------------------------------ |\n| GET    | `/family/members`                    | List user's family members           |\n| GET    | `/family/dates/upcoming`             | Upcoming dates with filters          |\n| GET    | `/family/activity/recent`            | Recent family activity feed          |\n| GET    | `/people/{personId}/context`         | Person profile with safe context     |\n| GET    | `/relationships/path`                | Relationship path between two people |\n| GET    | `/birthday-cards/context/{personId}` | Birthday card writing context        |\n\n## ChatGPT app widgets\n\nFor ChatGPT (Apps SDK), four tools render an interactive inline widget instead of\nplain JSON:\n\n- `get_upcoming_family_dates` → an **Upcoming family dates** card\n- `get_family_members` → a **Your family** roster\n- `get_person_profile` → a **Family member** profile card\n- `get_recent_family_activity` → a **Recent family activity** feed\n\nEach widget is a small React bundle in [`widgets/src/`](widgets/src) built by\n`npm run build:widgets` into `dist-widgets/<name>.js|.css`. The server serves those as\nstatic assets (`/widgets/...`) and exposes each as a `ui://widget/<name>.html`\nresource (MIME `text/html+skybridge`); the paired tool carries\n`_meta[\"openai/outputTemplate\"]` pointing at it. The widget reads the tool's\n`structuredContent` from `window.openai.toolOutput` and renders it. Other MCP clients\n(Claude, KAI) ignore the widgets and use the same tools' text output. See\n[`src/widgets/registry.ts`](src/widgets/registry.ts).\n\n## Development\n\n```bash\nnpm run dev            # Run the server with tsx (hot reload)\nnpm run build          # Compile server (tsc) + build widget bundles\nnpm run build:server   # Server only\nnpm run build:widgets  # Widget bundles only (-> dist-widgets/)\nnpm run test           # Run tests (incl. widget render tests)\nnpm run test:watch     # Watch mode\nnpm run lint           # ESLint\nnpm run format         # Prettier\nnpm run check          # Type check only\n```\n\n## Privacy Design\n\nThis server is designed to be **privacy-first**:\n\n- No email addresses, phone numbers, or physical addresses are ever returned\n- Birthdays are shown as month-day only (no birth year)\n- No financial or health information\n- All data scoped to the authenticated user's family only\n- Managed accounts (children) have additional protections\n\n## Privacy Policy\n\n**Privacy policy:** <https://a2me.app/privacy>\n\nThis connector accesses A2Me data on behalf of the authenticated user, over an\nOAuth 2.0 \"Connect A2Me\" flow, and is bound by the A2Me privacy policy above.\n\n- **What we collect / access:** read-only family-context data for the\n  authenticated user's own family — member names, relationship labels,\n  month–day of birthdays and events, and recent activity summaries. We never\n  return email addresses, phone numbers, physical addresses, birth years,\n  or financial/health data.\n- **How it's used:** returned to the connected AI assistant solely to answer\n  the user's request in-session. The connector does not train models on this\n  data and performs no writes back to A2Me.\n- **Storage & retention:** the connector holds no family data at rest. For\n  transparency and abuse prevention we log access metadata (timestamp,\n  tool name, calling assistant, scopes) in an append-only audit log; users can\n  review this under **Settings → Connected apps** in A2Me.\n- **Third-party sharing:** OAuth tokens are issued and validated via our auth\n  provider (Scalekit); no family data is shared with third parties beyond the\n  AI assistant the user explicitly connected.\n- **Contact:** privacy@a2me.app · security disclosures per [SECURITY.md](SECURITY.md).\n\n## Tech Stack\n\n- **Runtime:** Node.js 20+\n- **Language:** TypeScript (strict mode)\n- **MCP SDK:** `@modelcontextprotocol/sdk`\n- **Validation:** Zod\n- **Testing:** Vitest\n- **Transport:** Streamable HTTP (remote/production) and stdio (local dev)\n\n## License\n\nPrivate — Kinnectd / A2Me\n",
  "bytes": 11501,
  "sha": "9cc5c6502b829aba937bdab32d25e729b8fea8e40c03be0dee8a6788fa5cb1a9",
  "repo_slug": "kinnectd/a2me-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kinnectd_a2me_mcp_server_7234ee05/readme"
}