a2me-mcp-server

A2Me MCP 服务

v1 · 只读。 一个 Model Context Protocol 服务，为 A2Me 家庭社交平台提供只读且已去除隐私信息的家庭上下文工具，让 Claude、ChatGPT 或 KAI 等助手能够回答“妈妈的生日是什么时候？”之类的问题，或帮助撰写给奶奶的消息，且范围仅限于你自己的家庭。

托管于 https://mcp.a2me.app/mcp，并已在生产环境中用于 A2Me 的 Connect a2me 功能。

从 AI 助手连接

在 Claude 或 ChatGPT 中，使用以下 URL 添加自定义连接器：

https://mcp.a2me.app/mcp

你将通过 OAuth 登录 A2Me 并授予只读访问权限；随后，助手便可获取仅限于你账户的家庭相关上下文。

在本地运行

npm install
npm run dev        # stdio transport, mock data by default

默认通过 stdio 运行（适用于本地 MCP 客户端），并支持远程 HTTP 传输（MCP_TRANSPORT=http），用于托管部署。默认使用模拟数据（A2ME_USE_MOCK=true）；设置 A2ME_API_URL + A2ME_USE_MOCK=false 即可调用真实 API。请参阅 .env.example。

可用工具

工具	描述
get_family_members	返回用户的家庭成员及其关系标签
get_upcoming_family_dates	未来 N 天内的生日、周年纪念日和活动
get_recent_family_activity	最近的帖子、照片、视频和生日贺卡
get_person_profile	家庭成员的个人资料、兴趣和活动摘要
get_relationship_between_people	两位家庭成员之间的关系
get_birthday_card_context	撰写生日贺卡的上下文（回忆、兴趣、语气）
find_family_member	按姓名或关系进行模糊搜索（“妈妈”“我的祖母”）
answer_family_date_question	以自然语言询问日期（“妈妈的生日是什么时候？”）
get_message_context_for_person	撰写消息的上下文及建议
get_upcoming_events	即将举行的活动，以及用户的 RSVP 状态和 RSVP 计数
get_trip_overview	一次旅行的日期、人员名单、出行详情（航班/住宿）和行程
get_life_story	家庭成员的人生故事章节（或最近回答的故事问题）
get_unanswered_story_questions	尚未回答的故事问题——为探访做访谈准备
get_person_wishlist	家庭成员的愿望清单，可用于寻找礼物点子
search_family_memories	对近期家庭帖子和回忆进行关键词搜索
whats_new	近期动态汇总：最近的帖子和即将发生的事情

提示词

服务器还提供提示词——可一键启动的入口，会作为连接器命令显示在 Claude 中（并作为建议显示在 ChatGPT 中），让用户无需了解工具名称也能获得价值。每个提示词都会引导助手使用上方的只读工具：

提示词	功能
write_birthday_card	根据某人的背景撰写生日贺卡
write_family_message	撰写适用于任何场合或语气的消息
family_catch_up	总结家人的近况
upcoming_family_dates	列出即将到来的生日和纪念日，并提供建议
about_person	温暖地介绍一位家庭成员以及你们的关系

输入这些提示词时，person 参数会根据你的家庭名册（姓名和关系标签）自动补全——这是限定在你家庭范围内的 MCP 参数补全。请参阅 src/prompts/index.ts 和 src/completions.ts。

示例场景

1. “帮我给姐姐写一张生日贺卡”

   • find_family_member → 将“我姐姐”解析为 Sarah Walker
   • get_birthday_card_context → 返回兴趣（绘画、徒步、咖啡）和语气建议

2. “奶奶什么时候过生日？”

   • answer_family_date_question → 返回 Margaret Walker 的生日（11 月 8 日）

3. “家里最近有什么新鲜事？”

   • get_recent_family_activity → 返回近期帖子、照片和活动

4. “帮我给爸爸写一条感谢消息”

   • get_message_context_for_person → 返回 Robert Walker 的背景、兴趣和建议

5. “我的家人有哪些？”

   • get_family_members → 返回所有家庭成员及其关系

6. “最近有哪些活动？”

   • get_upcoming_family_dates → 返回即将到来的生日、纪念日和活动

架构

┌─────────────────────────────────────────────────────────┐
│                    MCP Client (LLM)                       │
│              (Claude, ChatGPT, KAI, etc.)                │
└───────────────────────┬─────────────────────────────────┘
                        │ stdio (MCP Protocol)
┌───────────────────────▼─────────────────────────────────┐
│                  A2Me MCP Server                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Tool Registry (16 tools)             │    │
│  └──────────────────────┬──────────────────────────┘    │
│                         │                                │
│  ┌──────────────────────▼──────────────────────────┐    │
│  │         Family Context Resolver                   │    │
│  │   (fuzzy matching, relationship resolution)       │    │
│  └──────────────────────┬──────────────────────────┘    │
│                         │                                │
│  ┌──────────────────────▼──────────────────────────┐    │
│  │            A2Me API Client                        │    │
│  │   (currently mock, future: real HTTP calls)       │    │
│  └──────────────────────┬──────────────────────────┘    │
│                         │                                │
│  ┌──────────────────────▼──────────────────────────┐    │
│  │            Auth Context                           │    │
│  │   (currently mock, future: OAuth/Firebase)        │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
                        │ (future)
┌───────────────────────▼─────────────────────────────────┐
│                   A2Me REST API                           │
│               (kinnectd-api service)                     │
└─────────────────────────────────────────────────────────┘

身份验证

目前使用模拟身份验证——在本地开发中始终返回已通过身份验证的用户（“Alex Walker”）。

未来的生产环境集成：

• 通过 A2Me API 验证 OAuth2/Firebase 令牌
• 通过 MCP 会话上下文或环境传递令牌
• 按用户隔离数据（用户只能查看自己的家庭信息）

必需的 A2Me API 端点（未来）

方法	端点	描述
GET	/family/members	列出用户的家庭成员
GET	/family/dates/upcoming	带筛选条件的即将到来的日期
GET	/family/activity/recent	近期家庭动态信息流
GET	/people/{personId}/context	包含安全背景信息的个人资料
GET	/relationships/path	两个人之间的关系路径
GET	/birthday-cards/context/{personId}	撰写生日贺卡所需的背景信息

ChatGPT 应用小组件

对于 ChatGPT（Apps SDK），有 4 个工具会渲染交互式内嵌小组件，而不是纯 JSON：

• get_upcoming_family_dates → 一张 即将到来的家庭日期卡片
• get_family_members → 一份 您的家庭成员列表
• get_person_profile → 一张 家庭成员资料卡
• get_recent_family_activity → 一份 近期家庭活动动态

每个小组件都是 widgets/src/ 中的一个小型 React 包，由 npm run build:widgets 构建为 dist-widgets/<name>.js|.css。服务会将这些文件作为 静态资源（/widgets/...）提供，并将每个文件公开为一个 ui://widget/<name>.html 资源（MIME text/html+skybridge）；配对的工具会携带指向该资源的 _meta["openai/outputTemplate"]。小组件会从 window.openai.toolOutput 读取工具的 structuredContent 并进行渲染。其他 MCP 客户端 （Claude、KAI）会忽略这些小组件，并使用相同工具的文本输出。请参阅 src/widgets/registry.ts。

开发

npm run dev            # Run the server with tsx (hot reload)
npm run build          # Compile server (tsc) + build widget bundles
npm run build:server   # Server only
npm run build:widgets  # Widget bundles only (-> dist-widgets/)
npm run test           # Run tests (incl. widget render tests)
npm run test:watch     # Watch mode
npm run lint           # ESLint
npm run format         # Prettier
npm run check          # Type check only

隐私设计

此服务采用隐私优先设计：

• 绝不返回电子邮件地址、电话号码或实际住址
• 生日仅显示月份和日期（不含出生年份）
• 不包含财务或健康信息
• 所有数据仅限于已认证用户自己的家庭
• 托管账户（儿童）享有额外保护

隐私政策

隐私政策： https://a2me.app/privacy

此连接器通过 OAuth 2.0“连接 A2Me”流程，代表已认证用户访问 A2Me 数据，并受上述 A2Me 隐私政策约束。

• 收集／访问的内容： 仅限已认证用户自己家庭的只读家庭相关数据——成员姓名、关系标签、生日和活动的月份与日期，以及近期活动摘要。我们绝不返回电子邮件地址、电话号码、实际住址、出生年份或财务／健康数据。
• 数据用途： 仅在当前会话中将数据返回给已连接的 AI 助手，用于回答用户的请求。连接器不会使用这些数据训练模型，也不会向 A2Me 写入任何内容。
• 存储与保留： 连接器不会在静态存储中保留任何家庭数据。为确保透明度并防止滥用，我们会在只追加审计日志中记录访问元数据（时间戳、工具名称、调用的助手、权限范围）；用户可在 A2Me 的 设置 → 已连接的应用 中查看这些记录。
• 向第三方共享： OAuth 令牌由我们的身份验证提供商（Scalekit）签发和验证；除用户明确连接的 AI 助手外，我们不会与第三方共享任何家庭数据。
• 联系方式： [email protected] · 安全问题披露请参阅 SECURITY.md。

技术栈

• 运行时： Node.js 20+
• 语言： TypeScript（严格模式）
• MCP SDK： @modelcontextprotocol/sdk
• 验证： Zod
• 测试： Vitest
• 传输方式： Streamable HTTP（远程／生产环境）和 stdio（本地开发）

许可证

专有 — Kinnectd / A2Me