使用说明
拆分MCP服务器
A. 模型上下文协议 将AI助手连接到 API花键.使用直接REST API调用在TypeScript中从头开始构建-无第三方Splitwise SDK。
为什么？
现有的Splitwise MCP服务器依赖于在写入操作时中断的SDK包装器(createExpense, createGroup由于MCP参数格式和SDK的预期对象类型之间的接口不匹配。该服务器直接调用Splitwise REST API，处理平面密钥编码(users__0__user_id)因此，每个端点都可以开箱即用地正确工作。
特性
- 27工具 涵盖完整的Splitwise API-费用、群组、好友、评论、货币、类别、通知
- 直接REST API调用 --没有SDK抽象层会中断或失去同步
- 可流式HTTP传输 --通过HTTP与任何MCP客户端配合使用
- 结构化JSON日志记录 具有自动PII屏蔽功能（在所有日志输出中编辑电子邮件和令牌）
快速开始
# Clone and install
pnpm install
# Configure
cp .env.example .env
# Edit .env and add your Splitwise API key
# Get one at https://secure.splitwise.com/apps
# Build and run
pnpm build
pnpm start
服务器启动于 http://127.0.0.1:3000/mcp.
使用Docker
cp .env.example .env
# Add your API key to .env
docker compose up -d
配置
所有配置都是通过环境变量（或 .env 文件）：
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
SPLITWISE_API_KEY |
是 | - | 您的Splitwise API密钥 |
MCP_PORT |
没有 | 3000 |
服务器端口 |
MCP_HOST |
没有 | 127.0.0.1 |
绑定地址 |
CORS_ORIGIN |
没有 | * |
允许的CORS来源 |
REQUEST_TIMEOUT_MS |
没有 | 30000 |
拆分API请求超时 |
工具
开支
| 工具 | 说明 |
|---|---|
create_expense |
通过手动分摊或等额分割创建费用 |
update_expense |
更新现有支出 |
delete_expense |
删除费用 |
undelete_expense |
恢复已删除的费用 |
get_expense |
按ID获取费用明细 |
list_expenses |
使用筛选器（组、朋友、日期范围、分页）列出费用 |
群组
| 工具 | 说明 |
|---|---|
create_group |
创建一个包含可选初始成员的组 |
delete_group |
删除组 |
undelete_group |
还原已删除的组 |
get_group |
获取组详细信息 |
list_groups |
列出所有组 |
add_user_to_group |
将用户添加到组 |
remove_user_from_group |
从组中删除用户 |
老友记
| 工具 | 说明 |
|---|---|
create_friend |
通过电子邮件添加朋友 |
create_friends |
一次添加多个好友 |
delete_friend |
删除好友 |
get_friend |
获取好友详细信息 |
list_friends |
列出所有有余额的朋友 |
评论
| 工具 | 说明 |
|---|---|
create_comment |
在费用中添加注释 |
delete_comment |
删除评论 |
get_comments |
获取有关费用的所有评论 |
用户和实用程序
| 工具 | 说明 |
|---|---|
get_current_user |
获取经过身份验证的用户 |
get_user |
按ID获取任何用户 |
update_user |
更新用户配置文件 |
get_currencies |
列出支持的货币 |
get_categories |
列出支出类别 |
get_notifications |
获取通知 |
建筑
src/
├── index.ts # HTTP server, MCP wiring, request logging
├── config.ts # Env var loading + validation, PII masking utility
├── logger.ts # Structured JSON logger with PII redaction
├── api/
│ ├── client.ts # SplitwiseClient — fetch calls, flat key encoding, error checking
│ ├── types.ts # TypeScript interfaces for all API shapes
│ └── errors.ts # SplitwiseApiError class
└── tools/
├── register.ts # Wires all tool modules to the MCP server
├── shared.ts # Shared error handling + response formatting
├── expenses.ts # Expense tools (most complex — user shares, splits)
├── groups.ts # Group tools
├── friends.ts # Friend tools
├── comments.ts # Comment tools
├── users.ts # User tools
└── utilities.ts # Currency, category, notification tools
服务器是 无状态 --每个传入的MCP请求都会创建一个新的传输和服务器实例。这 SplitwiseClient 在请求之间共享（它不包含状态，只包含API密钥和配置）。
Splitwise的API格式是如何处理的
Splitwise API期望POST主体为 application/x-www-form-urlencoded 对于数组，使用平面双下划线键约定：
cost=50.00&users__0__user_id=123&users__0__paid_share=50.00&users__1__user_id=456&users__1__owed_share=25.00
这 SplitwiseClient.flattenParams() 方法自动处理这个问题——工具调用者传递干净的嵌套对象，客户端在发送之前将它们平铺。
错误处理
即使操作失败，Splitwise也会返回HTTP 200——实际错误在响应体中。客户端中的每个API调用都对此进行检查，并抛出 SplitwiseApiError 有了细节，工具调用者总是能得到清晰的错误消息。
发展
# Run with hot reload
pnpm dev
# Build
pnpm build
# Clean build artifacts
pnpm clean
许可证
麻省理工学院
