gatherings MCP 服务器

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

这是一个基于 TypeScript 的 MCP 服务器，可以帮助跟踪社交活动的费用和付款，从而轻松计算报销金额并结算朋友之间的余额。

架构说明

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

虽然这种架构适用于我们当前的需求，但对于生产应用程序来说，它不是最高效或最易于维护的方法。

TODO

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

功能

工具

• 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 以在您的浏览器中访问调试工具。