taibu-mcp-server

TaiBu 的在线 MCP Server，基于 Streamable HTTP 运行，面向远程部署场景。

当前发布线：2.0.x

说明：本 README 将 1.2.5 之后累计的改动按功能重排为 1.2.6 -> 1.3.0 -> 1.4.0 -> 1.5.0 -> 2.0.0，便于按大功能分批发布 npm 版本。

适用场景

• 需要把 TaiBu MCP 工具部署成远程服务
• 需要 OAuth 2.1 + PKCE 接入 ChatGPT 等 MCP 客户端
• 需要继续兼容用户级 API Key 调用

安装

npm install taibu-mcp-server

核心特性

• 复用 taibu-core 的 15 个工具能力
• Streamable HTTP 入口：/mcp
• OAuth 2.1 + PKCE + 动态客户端注册
• Authorization: Bearer <token> 与 x-api-key 双认证链路
• 基于共享 transport 的 structuredContent + content 响应策略
• OAuth 授权页内置当前工具清单展示

输出约定

在线 MCP 响应分成两条通道：

• content[0].text: canonical text，适合直接阅读或继续交给 AI
• structuredContent: canonical JSON，并与工具公开 outputSchema 对齐，适合客户端按 schema 消费

注意：

• structuredContent 与 Web 结果页使用的是同源 canonical JSON
• content[0].text 只承担文本阅读，不再承载 JSON 字符串

最小运行方式

pnpm install
pnpm -C packages/core build
pnpm -C packages/mcp-server build
pnpm -C packages/mcp-server start

默认服务信息：

• GET /health
• GET /info
• POST /mcp
• GET /.well-known/oauth-authorization-server
• GET /.well-known/oauth-protected-resource

环境变量

基础运行

| 变量 | 说明 | |------|------| | SUPABASE_URL | Supabase 项目地址 | | SUPABASE_ANON_KEY | Supabase anon key | | SUPABASE_SYSTEM_ADMIN_EMAIL | 系统管理员邮箱，用于 MCP Server 受控访问数据库 | | SUPABASE_SYSTEM_ADMIN_PASSWORD | 系统管理员密码 | | MCP_HOST | 监听地址，默认 127.0.0.1 | | PORT | 端口，默认 3001 | | MCP_ALLOWED_ORIGINS | 浏览器 Origin 白名单 | | MCP_ALLOWED_HOSTS | Host 白名单 | | MCP_MAX_SESSIONS | 最大并发会话数 | | MCP_SESSION_TTL_MS | 会话生命周期 | | MCP_SESSION_IDLE_MS | 会话空闲超时 | | MCP_MAX_SSE_PER_USER | 每用户 SSE 并发上限 | | MCP_TRUST_PROXY | 反向代理后设为 true | | TAIBU_SITE_URL | OAuth 授权页 Logo 与站点链接来源 | | AMAP_WEB_SERVICE_KEY | 可选。出生地点解析服务所需的高德 Web Service Key |

OAuth 2.1

| 变量 | 说明 | |------|------| | MCP_JWT_SECRET | JWT 签名密钥，至少 32 字符 | | MCP_ISSUER_URL | OAuth issuer URL | | MCP_ALLOWED_TOKEN_AUDIENCES | 额外允许的 access token audience | | MCP_ACCESS_TOKEN_TTL | Access token 有效期，单位秒 | | MCP_REFRESH_TOKEN_TTL | Refresh token 有效期，单位秒 | | MCP_OAUTH_DEBUG | OAuth 调试日志开关 |

MCP 客户端示例

OAuth / Streamable HTTP

{
  "mcpServers": {
    "taibu": {
      "type": "streamable-http",
      "url": "https://your-domain.example.com/mcp"
    }
  }
}

API Key 调用

{
  "mcpServers": {
    "taibu": {
      "type": "streamable-http",
      "url": "https://your-domain.example.com/mcp",
      "headers": {
        "x-api-key": "sk-mcp-xxxxxxxx"
      }
    }
  }
}

Bearer token 的优先级高于 API Key；若 Bearer token 存在但无效，不会回退到 API Key。

与其他包的关系

• taibu-core: 工具注册、算法实现、transport 适配器
• taibu-mcp: 本地 stdio MCP Server

注意：taibu-core 仍保持纯算法边界，本身不接地图服务，也不会自动把地点名换算为经度。

License

taibu-mcp-server 使用 MIT 许可证，详见当前目录下的 LICENSE 文件。

版本批次

| 版本 | 批次说明 | |------|----------| | 2.0.0 | 跟随 core 切换到最终 MCP 契约：content 输出规范文本，structuredContent 输出 canonical JSON，在线服务保留 runtime placeResolutionInfo 扩展 | | 1.5.0 | 统一在线服务版本号，收口共享 transport、动态授权页工具展示、会话管理与运行时契约 | | 1.4.0 | 跟随核心接入 daliuren 大六壬工具 | | 1.3.0 | 跟随核心接入 qimen 奇门遁甲工具 | | 1.2.6 | 延续 1.2.5 做补丁发布，集中修复缓存回源、鉴权边界、结构化输出与测试覆盖 | | 1.2.5 | core / mcp 的旧基线版本；本次将在线服务也统一收口到同一版本线 |