gatherings MCP Server

gatherings MCP 服务

用于管理聚会和分摊费用的模型上下文协议服务。

这是一个基于 TypeScript 的 MCP 服务，可帮助记录社交活动的费用和付款，方便计算报销金额并结清朋友之间的余额。

架构说明

重要提示：本项目采用了非标准的 Node.js 应用架构。TypeScript MCP 服务充当 Python 后端实现的封装层。Node.js 服务接收 MCP 请求，将其转换为对 Python 脚本的命令行调用，并返回结果。

虽然这种架构满足了我们当前的需求，但对于生产应用来说，它并不是最高效或最易维护的方案。

待办事项

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

功能

工具

• 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
• delete_gathering - 删除聚会
  • 必需参数为 gathering_id，force 参数可选
• add_member - 向聚会添加新成员
  • 必需参数为 gathering_id 和 member_name
• remove_member - 从聚会中移除成员
  • 必需参数为 gathering_id 和 member_name

开发

安装依赖：

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
    }
  }
}

配置选项

• command 和 args：指定如何运行服务
• env：环境变量
  • GATHERINGS_DB_PATH：数据库文件的路径
  • GATHERINGS_SCRIPT：用于处理聚会操作的 Python 脚本路径
• alwaysAllow：无需提示即可自动允许使用的工具列表
• timeout：最长执行时间，单位为秒

调试

由于 MCP 服务通过 stdio 通信，调试可能比较困难。我们建议使用 MCP Inspector，它可通过包脚本运行：

npm run inspector

Inspector 会提供一个 URL，供你在浏览器中访问调试工具。