内容
# outbound-mcp
**对外合作伙伴门户 API 的 MCP 服务器。** 跨提供商 - 与 Claude Desktop、Claude Code、ChatGPT、n8n 以及任何其他支持模型上下文协议的设备兼容（遵循 2025-06-18 规范，使用 Streamable HTTP 传输）。
## 功能描述
将 [对外合作伙伴门户 v1 API](https://github.com/outbountpartners/outbound-api-spec) 公开为 LLM 代理可以调用的工具目录。服务器是一个薄代理：它在会话初始化时接收用户的门户 API 密钥，将调用转发到 v1 API，并返回封装在 MCP 内容信封中的 JSON 响应。
## 实时端点
```
https://sirhkzqpdgarrcyqnjtl.supabase.co/functions/v1/mcp
```
- **GET** 用于发现/健康检查（无需身份验证）
- **GET /mcp/tools** 用于原始工具目录（无需身份验证）
- **POST** 用于 JSON-RPC 2.0 消息（调用 `tools/call` 时需要身份验证）
浏览发现 URL 以查看协议版本、服务器信息、传输和工具数量。
## 工具
6 个资源下的 23 个工具。每个工具映射到一个 v1 API 端点：
| 资源 | 工具 |
|---|---|
| **系统** | `health`, `whoami` |
| **会议** | `meetings_list`, `meetings_get`, `meetings_create`, `meetings_update`, `meetings_submit_feedback` |
| **客户** | `clients_list`, `clients_get`, `clients_create`, `clients_update` |
| **活动** | `campaigns_list`, `campaigns_get`, `campaigns_create`, `campaigns_update` |
| **用户** | `users_list`, `users_get`, `users_invite`, `users_update`, `users_deactivate`, `users_reactivate` |
| **排行榜** | `leaderboard_get` |
| **佣金** | `commission_get` |
每个工具包含：
- 参数的完整 JSON 模式（也在服务器端验证）
- GET 风格工具上的 `annotations.readOnlyHint: true`
- `users_deactivate` 上的 `annotations.destructiveHint: true`，以便兼容的客户端在调用前提示
## 身份验证
从门户内的 `/api` 管理页面（仅限管理员/超级管理员）获取门户 API 密钥。在每次 MCP 请求中传递：
- `x-api-key: opk_live_...` 头部（推荐）
- 或 `Authorization: Bearer opk_live_...`
根据密钥的权限，v1 API 在服务器端强制执行作用域。如果您的密钥缺少作用域，您将从底层 API 获取 `403 insufficient_scope` 错误，并通过 MCP 响应呈现。
## 从客户端连接
### Claude Desktop / Claude Code
编辑 `claude_desktop_config.json`（桌面版）或项目根目录中的 `.mcp.json`（代码）：
```json
{
"mcpServers": {
"outbound-partners": {
"type": "http",
"url": "https://sirhkzqpdgarrcyqnjtl.supabase.co/functions/v1/mcp",
"headers": {
"x-api-key": "opk_live_..."
}
}
}
}
```
> **字段名称：** 使用 `"type": "http"` - 而不是 `"transport": "http"`。Claude Code/Desktop 静默忽略使用错误键的条目。
### ChatGPT（支持 MCP）
在 GPT 或工作区设置中，添加自定义 MCP 服务器：
- URL：`https://sirhkzqpdgarrcyqnjtl.supabase.co/functions/v1/mcp`
- 头部：`x-api-key: opk_live_...`
### n8n
n8n MCP 节点直接接受 URL 和头部。插入一个 `MCP Client` 节点，设置 URL，并添加 `x-api-key` 头部。
### 编程（Anthropic / OpenAI SDK）
```python
# Claude
from anthropic import Anthropic
client = Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[{"role": "user", "content": "Show me the leaderboard"}],
mcp_servers=[{
"type": "url",
"url": "https://sirhkzqpdgarrcyqnjtl.supabase.co/functions/v1/mcp",
"name": "outbound",
"authorization_token": "opk_live_..."
}]
)
```
## 快速测试
```bash
# 发现
curl https://sirhkzqpdgarrcyqnjtl.supabase.co/functions/v1/mcp
# 初始化握手
curl -X POST -H 'Content-Type: application/json' -H 'x-api-key: opk_live_...' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
https://sirhkzqpdgarrcyqnjtl.supabase.co/functions/v1/mcp
# 列出工具
curl -X POST -H 'Content-Type: application/json' -H 'x-api-key: opk_live_...' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
https://sirhkzqpdgarrcyqnjtl.supabase.co/functions/v1/mcp
# 调用工具
curl -X POST -H 'Content-Type: application/json' -H 'x-api-key: opk_live_...' \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"leaderboard_get","arguments":{"period":"this_week"}}}' \
https://sirhkzqpdgarrcyqnjtl.supabase.co/functions/v1/mcp
```
## 架构
规范源位于 [`outbound-partners-client-dashboard`](https://github.com/outbountpartners/outbound-partners-client-dashboard) 下的 `supabase/functions/mcp/`。此仓库是公共镜像，在规范源更改时更新。
```
LLM 客户端（Claude / ChatGPT / n8n）
│ JSON-RPC over HTTP POST
▼
mcp 边函数（此代码）
│ HTTP 转发（传递 x-api-key）
▼
api 边函数（/v1/* 路由器）
│
▼
Supabase Postgres
```
零新增基础设施 - 在 Supabase 现有的边运行时（Deno）上运行。除了 Supabase 自动注入的内容外，无需配置环境变量。
## 自托管
想要部署您自己的实例吗？将 `src/index.ts` 和 `src/tools.ts` 放入 Supabase 边函数（或任何 Deno HTTP 服务器）中，并将 `API_BASE` 指向您的 v1 API。MCP 层是无状态的 - 无需数据库模式，无需自己的密钥。
## 源代码
- [`src/index.ts`](./src/index.ts) - HTTP 服务器 + JSON-RPC 2.0 分发器 + 工具调用
- [`src/tools.ts`](./src/tools.ts) - 包含 JSON 模式输入的工具目录
## 版本控制
当前 MCP 协议版本：`2025-06-18`。服务器版本：`1.0.0`。
## 维护者
Rai - rai@outboundpartners.com
