🚀 聚会 MCP 服务器

这是一个基于 TypeScript 的 MCP 服务器，主要用于管理聚会以及费用分摊。它能够帮助用户跟踪社交活动中的支出和支付情况，让计算报销金额、结算朋友间的费用差额变得轻松简单。

🚀 快速开始

开发

• 安装依赖项：

npm install

• 构建服务器：

npm run build

• 带有自动重建的开发：

npm run watch

安装

配置

若要与 Claude Desktop 配合使用，需添加以下服务器配置：

{
  "mcpServers": {
    "gatherings": {
      "command": "node",
      "args": ["/path/to/gatherings-server/build/index.js"],
      "env": {
        "GATHERINGS_DB_PATH": "gatherings.db",
        "GATHERINGS_SCRIPT": "/path/to/gatherings-server/gatherings.py"
      },
      "disabled": false,
      "autoApprove": [],
      "alwaysAllow": [
        "create_gathering",
        "add_expense",
        "calculate_reimbursements",
        "record_payment",
        "rename_member", 
        "show_gathering",
        "list_gatherings",
        "close_gathering",
        "delete_gathering",
        "add_member",
        "remove_member"
      ],
      "timeout": 300
    }
  }
}

配置选项

调试

由于 MCP 服务器通过 stdio 进行通信，调试可能会有一定难度。我们推荐使用 MCP Inspector，它可作为包脚本使用：

npm run inspector

Inspector 会提供一个用于访问调试工具的 URL，在浏览器中打开该 URL 即可进行调试。

✨ 主要特性

工具

• create_gathering - 创建新的聚会
  • 需接受 gathering_id 和 members 作为必需参数
• add_expense - 为成员添加支出
  • 需接受 gathering_id、member_name 和 amount 作为必需参数
• calculate_reimbursements - 计算聚会的报销金额
  • 需接受 gathering_id 作为必需参数
• record_payment - 记录成员的支付
  • 需接受 gathering_id、member_name 和 amount 作为必需参数
• rename_member - 重命名无名成员
  • 需接受 gathering_id、old_name 和 new_name 作为必需参数
• show_gathering - 显示聚会的详细信息
  • 需接受 gathering_id 作为必需参数
• list_gatherings - 列出所有聚会
• close_gathering - 关闭一个聚会
  • 需接受 gathering_id 作为必需参数，可选 force 参数
• delete_gathering - 删除一个聚会
  • 需接受 gathering_id 作为必需参数，可选 force 参数
• add_member - 向聚会添加新成员
  • 需接受 gathering_id 和 member_name 作为必需参数
• remove_member - 将成员从聚会中移除
  • 需接受 gathering_id 和 member_name 作为必需参数

🔧 技术细节

注意事项：架构

⚠️ 重要提示

此项目采用了一种非标准的架构来实现 Node.js 应用程序。TypeScript MCP 服务器作为包装器围绕一个 Python 后端实现。Node.js 服务器接收 MCP 请求，将其转换为对 Python 脚本的命令行调用，并返回结果。

尽管当前这种架构满足了我们的需求，但对于生产应用来说，这不是最高效或最容易维护的方法。

待办事项

• 将实现重构为更标准的架构：
  • 完全将后端迁移到 TypeScript/JavaScript
  • 或者在 Node.js 和 Python 组件之间实现适当的进程间通信
  • 或者用 REST API 替换，其中 Python 后端提供 MCP 服务器使用的 API
• 改进 Node.js 和 Python 组件之间的错误处理
• 为组件之间的集成添加自动化测试
• 优化 Dockerfile