适用于 ChatGPT 的 Splitwise 连接器

一个仅数据的 MCP 服务器，将 ChatGPT 连接到 Splitwise 官方 API。它支持：

• list_groups

• list_friends（包括余额）

• list_expenses

• get_expense

• create_expense（平均群组分摊或显式份额）

该服务器在 /mcp 使用 Streamable HTTP。它同时充当一个轻量级 OAuth 2.1 授权桥：ChatGPT 与此服务器完成 PKCE，而此服务器完成 Splitwise OAuth，并将 Splitwise 令牌保留在 ChatGPT 之外。

前提条件

• Node.js 20 或更高版本

• 用于部署的稳定公共 HTTPS URL（或测试期间的开发隧道）

• 一个 Splitwise 账户和 Splitwise OAuth 应用

1. 注册 Splitwise 应用

1. 打开 https://secure.splitwise.com/apps 并创建一个 OAuth 应用。

2. 将其回调 URL 设置为 https://YOUR-CONNECTOR-HOST/oauth/splitwise/callback。

3. 复制客户端 ID 和客户端密钥。切勿将其提交到版本库。

Splitwise 必须重定向到连接器，而不是直接重定向到 ChatGPT。连接器随后恢复 ChatGPT 单独的 PKCE 流程。

2. 配置并运行

cp .env.example .env
# Fill in .env, then:
npm install
npm run dev

必需变量：

可选变量：PORT、SPLITWISE_AUTHORIZE_URL、SPLITWISE_TOKEN_URL 和 SPLITWISE_API_BASE_URL。

使用 openssl rand -hex 32 生成会话密钥。对于容器：

docker build -t splitwise-mcp .
docker run --env-file .env -p 3000:3000 splitwise-mcp

3. OAuth 流程

1. ChatGPT 从 MCP 服务器发现 /.well-known/oauth-protected-resource。

2. 它在 /.well-known/oauth-authorization-server 发现此连接器的 OAuth 元数据，并在 /register 动态注册一个公共客户端。

3. ChatGPT 在 /authorize 启动授权码 + PKCE，包括 MCP resource 值。

4. 连接器将用户重定向到 Splitwise，并在 /oauth/splitwise/callback 接收结果。

5. 连接器在服务器端交换 Splitwise 的代码，创建一个五分钟的加密连接器代码，并重定向到 ChatGPT。

6. ChatGPT 使用其 PKCE 验证器在 /token 交换该代码。连接器返回一个经过认证的加密访问令牌，其中包含最少的会话上下文。

7. 每个 /mcp 请求在调用 Splitwise 之前解密并验证令牌、过期时间、作用域上下文和资源。

动态客户端注册、连接器代码和 30 天访问令牌是从 SESSION_SECRET 派生的无状态 AES-256-GCM 信封。只要每个实例保持相同的密钥，它们就能在休眠、重启、重新部署和多个副本中存活。轮换 SESSION_SECRET 会故意使所有现有注册和连接失效。此示例不签发刷新令牌，因此 30 天后需要重新关联。

4. 测试并连接到 ChatGPT

运行：

npm run build
npm test
npx @modelcontextprotocol/inspector@latest

在 Inspector 中选择 Streamable HTTP 并使用 https://YOUR-CONNECTOR-HOST/mcp。

在 ChatGPT 中，在 设置 → 安全与登录 下启用开发者模式。在插件页面，添加一个连接，选择公共端点选项，并输入 https://YOUR-CONNECTOR-HOST/mcp。查看发现的五个工具，然后调用一个读取工具以开始账户关联。

建议的检查：

• “列出我的 Splitwise 群组。”

• “显示我与 Splitwise 好友的余额。”

• “列出群组 123 中最近五笔支出。”

• “获取支出 456 的完整详情。”

• “在群组 123 中创建一笔 24 美元的晚餐支出，平均分摊。”

生产环境说明

可运行的服务器不存储 OAuth 会话状态。在进行更大规模的多用户部署之前：

• 保持 SESSION_SECRET 稳定、保密，并在所有副本中保持一致。为了更强的密钥管理，从托管的 KMS 派生或检索加密密钥；切勿记录令牌或密钥。

• 无状态授权码在没有存储的情况下无法标记为已消费。PKCE、精确的客户端/重定向/资源绑定、认证加密和五分钟的生命周期限制了重放暴露。如果需要严格执行一次性使用，请添加一个以代码标识符为键的短期共享重放缓存。

• 将动态注册的重定向 URI 限制为应用管理页面显示的精确 ChatGPT 回调 URL（加上显式配置的开发回调）。

• 添加速率限制、结构化安全日志、密钥轮换、隐私政策以及令牌撤销/账户解除关联。

• 保留 resource 绑定、PKCE 验证、短代码生命周期和精确的重定向 URI 匹配。

• 在 HTTPS 后面运行。不要将此开发服务器直接暴露到互联网。

create_expense 工具被标记为非幂等写入。其指令要求模型在调用之前总结确切的金额、货币、群组、付款人和分摊比例。Splitwise 可能返回带有应用级 errors 对象的 HTTP 200，因此连接器在报告成功之前会检查该对象。