Splid MCP

Splid MCP 服务

一个通过工具提供 Splid（splid.app）功能的模型上下文协议（MCP）服务，由逆向工程得到的 splid-js 客户端驱动。

• 语言/运行时：Node.js（ESM）+ TypeScript
• 传输方式：Streamable HTTP（本地检查器使用 stdio）
• 许可证：MIT

快速开始

1. 安装

npm install

2. 配置环境变量

在项目根目录创建 .env：

CODE=YOUR_SPLID_INVITE_CODE
PORT=8000

3. 构建并运行

npm run build
npm run dev

4. 在本地检查

npm run inspect

然后使用“Streamable HTTP”连接到 http://localhost:8000/mcp。

工具

所有工具都支持可选的群组选择器，用于覆盖 CODE 中的默认值：

• groupId?: string
• groupCode?: string（邀请码）
• groupName?: string（保留字段；尚不支持）

如果未提供任何选择器，服务将使用 CODE 中的默认群组。

health

• 用途：检查连接状态
• 输出：{ ok: true }

whoami

• 用途：显示当前选定的群组及其成员
• 输入：无
• 输出：包含群组信息和成员的 JSON

createExpense

• 用途：创建新的支出条目
• 输入：
  • title: string
  • amount: number > 0
  • currencyCode?: string（省略时默认为群组默认值）
  • payers: { userId?: string; name?: string; amount: number > 0 }[]（至少 1 项）
  • profiteers: { userId?: string; name?: string; share: number in (0,1] }[]（至少 1 项）
  • 可选的群组选择器字段
• 规则：
  • 名称不区分大小写，并会解析为成员的 GlobalId；未知名称会返回明确的错误。
  • 所有 share 值的总和必须等于 1（误差范围为 ±1e-6）。
• 示例（名称）：

{
  "title": "Dinner",
  "amount": 12.5,
  "payers": [{ "name": "Alice", "amount": 12.5 }],
  "profiteers": [{ "name": "Bob", "share": 0.6 }, { "name": "Alice", "share": 0.4 }]
}

• 示例（userIds）：

{
  "title": "Dinner",
  "amount": 12.5,
  "payers": [{ "userId": "<GlobalId>", "amount": 12.5 }],
  "profiteers": [{ "userId": "<GlobalId>", "share": 1 }]
}

listEntries

• 用途：列出群组中的近期条目
• 输入：
  • limit?: number（1..100，默认值为 20）
  • 可选的群组选择器字段
• 输出：条目数组

getGroupSummary

• 用途：显示群组的余额/摘要
• 输入：
  • 可选的群组选择器字段
• 输出：摘要对象（余额由 Splid 计算）

Streamable HTTP

• URL：http://localhost:8000/mcp
• 无需身份验证标头；使用 MCP Inspector 进行测试。

故障排查

• “Bad Request: Server not initialized”：刷新并重新连接；第一个 POST 必须是 initialize。
• 400，且出现 share 错误：确保 share 在 (0,1] 范围内，且总和为 1。
• 未知名称：检查 whoami 输出中的成员确切名称。

配置

• 环境变量：
  • CODE：默认群组的 Splid 邀请/加入代码
  • PORT（可选）：默认值为 8000

致谢

• Splid JS 客户端：https://github.com/LinusBolls/splid-js
• MCP 服务模板/文档：https://github.com/InteractionCo/mcp-server-template

许可证

MIT