B2match (unofficial)

b2match-mcp

用于 B2match 活动和配对平台的只读 MCP 服务。

此软件包旨在由用户通过 npx 和 stdio MCP 传输方式在本地运行。

**免责声明：**本项目为非官方项目，与 B2match 无关，也未获其认可或支持。本项目使用了 B2match 未公开文档的 Web GraphQL API，因此字段可用性可能随时变更，恕不另行通知。请遵守 B2match 的服务条款和 GDPR 使用本项目。参与者资料可能包含他人的个人数据——请将导出内容保存在本地，遵守各活动的可见性规则，不要收集或重新发布个人数据。

只读与隐私保障

• MCP 服务仅发送 GraphQL query 操作。任何变更和订阅操作都会在发起网络请求前解析并拒绝。
• 明确禁止已知的“看似只读”的写入操作，包括个人资料查看、标记为已读、会议出席和书签变更。
• B2match 在选中某些查询字段时，仍可能更新其自身的已读／查看计数。请参阅服务端副作用。
• 本服务绝不会调用 Plausible、Sentry、Google Analytics、HubSpot、LinkedIn pixel 或任何非 B2match 分析端点。
• 除 https://api.b2match.com/v4/query 和 CLI 打开的 B2match Google 登录 URL 外，本服务不会发起任何外部调用。
• 此软件包不会收集遥测或分析数据。
• 工具或状态命令绝不会打印令牌。
• 如果有可用的操作系统钥匙串，令牌会存储在其中；否则会存储在权限为 0600 的配置文件中。

安装／运行

需要 Node.js 22 或更新版本。在搭载 Apple Silicon 的 macOS 上，推荐通过 npx 安装；身份验证存储路径无需本机构建步骤。

npx -y b2match-mcp

从代码库检出目录运行：

npm install
npm run build
node dist/cli.js

MCP 客户端配置

Claude Desktop

{
  "mcpServers": {
    "b2match": {
      "command": "npx",
      "args": ["-y", "b2match-mcp"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "b2match": {
      "command": "npx",
      "args": ["-y", "b2match-mcp"]
    }
  }
}

VS Code

添加到 .vscode/mcp.json 或用户 MCP 设置中：

{
  "servers": {
    "b2match": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "b2match-mcp"]
    }
  }
}

从此检出目录进行本地开发：

{
  "mcpServers": {
    "b2match": {
      "command": "node",
      "args": ["/absolute/path/to/b2match-mcp/dist/cli.js"]
    }
  }
}

身份验证

公开活动数据可匿名访问。查看者个人资料、活动列表、会议、日程、对话、通知和可用时间等个人数据，需要本地存储的 B2match 会话令牌。

macOS／Linux 登录

b2match-mcp login https://www.b2match.com/e/<event-slug>
# or: npx b2match-mcp login https://www.b2match.com/e/<event-slug>

默认命令会：

1. 匿名解析活动，并向 B2match 请求 Google 登录 URL。
2. 将已安装的 Chrome、Chromium、Edge 或 Brave 作为独立进程启动。
3. 在工具配置目录下使用专用的持久化配置，而非日常使用的浏览器配置。
4. 仅为该专用配置在 127.0.0.1 上开放远程调试端口（不会对日常使用的浏览器开放）。登录完成或超时后，端口会关闭。
5. 由你手动完成 Google 登录和双重身份验证。CLI 不会填写任何表单。
6. 等待活动标签页 URL（www.b2match.com/e/<slug>?token=…）中的 JWT 或活动会话 Cookie，验证令牌有效后将其存储，并关闭该浏览器窗口。如果尚未设置 Cookie，Chrome 可能会在 Google 登录后的活动页面上返回 404；此时可使用 URL 令牌完成登录。

通常再次登录时只需点击一次，因为专用配置会保留 Google 会话。

macOS 可能会在 CLI 首次存储或读取令牌时显示钥匙串访问提示。如果希望使用钥匙串存储，请批准 b2match-mcp／你的终端的访问权限。如果访问被拒绝或钥匙串不可用，CLI 将改用私有配置文件。

仅粘贴 / 环境变量令牌

仅在专用浏览器流程无法运行时使用：

b2match-mcp login --paste
# or: npx b2match-mcp login --paste
B2MATCH_TOKEN='<session-cookie-value>' b2match-mcp

B2MATCH_TOKEN 仅在内存中使用，不会持久化。不要在命令行中传递令牌，否则会泄露到 shell 历史记录中。

状态 / 登出

b2match-mcp status
b2match-mcp logout
b2match-mcp logout --all

logout 仅会移除已存储的 B2match 令牌。logout --all 还会删除专用浏览器配置文件。

专用浏览器配置文件

登录使用位于 ~/.config/b2match-mcp/browser-profile（或 $B2MATCH_MCP_CONFIG_DIR/browser-profile / $XDG_CONFIG_HOME/b2match-mcp/browser-profile）的专用 Chromium 配置文件。该配置文件会保留 Google 会话，因此之后登录通常只需点击一次。

若要同时清除 Google 会话和已存储的 B2match 令牌：

b2match-mcp logout --all

若只删除配置文件并保留已存储的令牌：

rm -rf ~/.config/b2match-mcp/browser-profile

不带 --all 的 logout 会保留配置文件，以便下次登录时重用 Google 会话。

存储位置

• macOS：通过 /usr/bin/security 使用登录钥匙串（b2match-mcp 服务、default 账户）。每次保存后，CLI 都会回读项目；如果密钥缺失或不正确，则会回退到私有文件，并打印 keychain read-back failed, stored in file。
• Linux：安装并解锁时使用 secret-tool / libsecret。
• Windows：私有备用文件。
• 备用文件：$B2MATCH_MCP_CONFIG_DIR/auth.json、$XDG_CONFIG_HOME/b2match-mcp/auth.json 或 ~/.config/b2match-mcp/auth.json，权限为 0600。
• 如果钥匙串项目存在但为空或无法读取，b2match-mcp status 会报告 source: "keychain-unreadable"（并提示重新登录），而不是误报为已登出并显示 source: "none"。
• 专用浏览器配置文件：~/.config/b2match-mcp/browser-profile（与配置目录相同）。

如果令牌是 JWT，CLI 会将其 exp 声明记录为 expiresAt。B2match 也有不透明令牌，这种情况下无法在本地获知其有效期。如果经过身份验证的查看器检查返回 401，则会报告令牌无效或已过期，并在当前进程中记住这一状态。随后，公共工具会以匿名方式继续运行，而不会删除已存储的令牌。

登录故障排除

• 未找到受支持的浏览器： 安装 Chrome、Chromium、Edge 或 Brave，或使用 b2match-mcp login --paste。
• Google 阻止了窗口： 如果可以，请在专用窗口中完成登录；否则使用 --paste。
• Google 登录后超时 / 404： 如果 Chrome 在设置 Cookie 前返回 404，CLI 也会从事件标签页 URL 中读取 JWT。完成登录并等待；或使用 --paste。
• 拒绝了钥匙串提示： 运行 b2match-mcp logout，然后重新运行 login 并批准提示；或者设置 B2MATCH_MCP_DISABLE_KEYCHAIN=1，以使用私有文件备用方案。
• status 显示 keychain-unreadable： 钥匙串项目为空或已损坏，并且未找到可用的 auth.json。运行 b2match-mcp logout，然后重新运行 login。如果文件中的令牌仍然有效，status 会使用 source: "file"，并针对钥匙串项目设置 warning。
• 令牌错误 / 已过期： 运行 b2match-mcp logout，重新登录，然后再次运行 login。

工具

公开／匿名：

• get_event - 活动元数据、日期、注册时间段、登录方式和导航信息。数字 ID 和 slug 返回相同字段。
• list_participants - 分页显示精简的参与者摘要，并支持可选搜索。设置 detail=true 可获取更完整的列表数据。
• get_participant - 获取一位参与者的个人资料，不会触发个人资料查看跟踪。
• list_organisations、get_organisation - 组织／参与页面。会自动解析 /components/<id> 等菜单路径。
• list_opportunities、get_opportunity - 市场条目。会自动解析菜单路径；找不到的机会会返回 MCP 未找到错误。
• get_agenda、get_session、list_session_attendees、list_speakers。

已认证：

• auth_status
• list_my_events
• my_participation
• my_schedule
• my_meetings - 按状态列出会议；未筛选的响应会使用精简的可用情况摘要，除非设置 detail=true
• my_availability - 默认按天合并空闲时段；设置 detail=true 可获取完整时段网格
• find_meeting_slots
• meeting_recommendations
• list_conversations - 显示最新消息预览；不会将对话标记为已读
• get_conversation - 默认禁用，因为获取消息会将对话标记为已读；请参阅副作用
• list_notifications - 默认返回未读／未查看计数；完整列表会重置未查看计数

可选的原始查询：

• 仅当设置 B2MATCH_ALLOW_RAW=1 时才会注册 graphql_read。它仍会拒绝非查询操作；除非设置 B2MATCH_ALLOW_SIDE_EFFECT_READS=1，否则也会拒绝选择 messagesV2 或通知列表的查询。

服务端副作用

此客户端绝不会发送 MarkConversationAsSeen 或 ReadNotification 等 B2match mutation。不过，当查询选择某些字段时，B2match 仍可能更改自身的已读／已查看状态：

• get_conversation（messagesV2）会将该对话标记为已读（未读对话计数减少）。
• list_notifications 使用 notifications(...) 列表字段时会重置未查看计数（未查看 → 0）。未读计数不变。单独获取 notificationsCounter 不会重置未查看计数。
• list_conversations（包括 lastMessageV2）已知不会产生副作用。

限制条件：

• 默认情况下，list_notifications 只返回 unread／unseen 计数。
• get_conversation 和完整通知列表需要设置 B2MATCH_ALLOW_SIDE_EFFECT_READS=1，并且显式传入工具参数（acknowledge_marks_read／acknowledge_marks_seen）。
• 除非设置相同的环境变量，否则 graphql_read 会拒绝选择 messagesV2 或 notifications 列表的查询。

如果只需要最新消息，请使用 list_conversations。

每个活动范围内的工具都接受当前活动 URL（https://www.b2match.com/e/<slug>）、旧版活动 URL（https://<slug>.b2match.io）、裸 slug 或数字活动 ID。

未存储令牌时，已认证工具会返回 MCP 错误并说明如何登录。只有在已存储令牌收到 HTTP 401 后，工具才会提示令牌无效或已过期。

开发

npm install
npm run build
npm test

有关 lint、格式化、覆盖率、Conventional Commits 和只读保护的信息，请参阅 CONTRIBUTING.md。

针对公开活动执行实时冒烟测试（可选加入，不在 CI 中运行）：

B2MATCH_LIVE_SMOKE=1 B2MATCH_SMOKE_EVENT='https://www.b2match.com/e/<event-slug>' npm test -- tests/live-smoke.test.ts

只有同时设置这两个环境变量时才会运行冒烟测试。

发布

Release Please 会根据 main 上的 Conventional Commits 创建发布版本。创建发布版本时，同一工作流（.github/workflows/release-please.yml）会使用 npm publish --provenance --access public 发布（仅限 OIDC 可信发布——无需 NODE_AUTH_TOKEN）。Provenance 需要公开仓库。请将 npm 可信发布配置为使用工作流 release-please.yml。要重新发布现有标签：gh workflow run release-please.yml -f publish_tag=vX.Y.Z。.github/workflows/publish.yml 仅用于手动重新发布分支最新版本。

验证状态

已在此仓库中验证：

• TypeScript 构建和单元测试。
• 仅查询限制、事件标识符解析、Cookie 名称辅助函数、专用浏览器启动参数、章节路径解析、精简的参与者摘要，以及 401/身份验证错误策略。
• 打包后的 CLI --help / status。
• 提供 B2MATCH_SMOKE_EVENT 时，可选择运行匿名实时冒烟测试，测试每个公开工具。

需要在真实机器上实际登录：

• 使用专用配置文件登录 Google、Keychain 提示、URL 令牌或 Cookie 捕获。
• 需身份验证的工具：list_my_events、my_participation、日程、会议、可用时间、会议时段、推荐、对话和通知。

许可证

MIT。