Gatherings MCP Server

Gatherings MCP Server

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

依赖管理

本项目使用 uv 管理 Python 依赖，而不是 pip。这是由于 Model Context Protocol Python SDK 的依赖要求。

请确保已安装 uv，或通过 pip 安装：

pip install uv

安装项目依赖：

uv pip install -r requirements.txt

概览

Gatherings MCP Server 提供了一个 API，使 AI 助手能够通过 Machine Conversation Protocol 与 Gatherings 应用交互。这使 AI 系统能够帮助用户管理社交活动、外出活动或任何由参与者分摊费用的聚会的共同开支。

功能

• 创建和管理包含多名成员的聚会
• 为特定成员添加费用
• 计算公平的报销金额
• 记录付款和报销
• 生成详细的付款摘要
• 在聚会中添加或移除成员
• 根据需要重命名成员

安装

前提条件

• Python 3.8+
• SQLAlchemy
• MCP SDK

设置

1. 克隆此仓库：

   git clone https://your-repository.git
   cd accel
   

2. 安装所需依赖：

   pip install -r requirements.txt
   

3. 设置环境变量（可选）：

   # Custom database location
   export GATHERINGS_DB_PATH=path/to/database.db
   
   # Custom script location
   export GATHERINGS_SCRIPT=path/to/gatherings.py
   

用法

启动 MCP 服务：

python gatherings_mcp_server.py

服务通过 stdio 运行，因此兼容 MCP 协议客户端。

API 参考

MCP 服务提供以下工具：

create_gathering(gathering_id: str, members: int)

创建指定成员人数的新聚会。

add_expense(gathering_id: str, member_name: str, amount: float)

为聚会中的某位成员添加一笔费用。

calculate_reimbursements(gathering_id: str)

计算聚会中谁欠谁多少钱。

record_payment(gathering_id: str, member_name: str, amount: float)

记录成员支付的款项（正值）或向成员支付的报销款（负值）。

rename_member(gathering_id: str, old_name: str, new_name: str)

重命名聚会中的成员。

show_gathering(gathering_id: str)

显示聚会详情，包括费用和付款状态。

list_gatherings()

列出数据库中的所有聚会。

close_gathering(gathering_id: str)

将聚会标记为已关闭。

delete_gathering(gathering_id: str, force: bool = False)

删除聚会及其所有相关数据。设置 force=True 可删除已关闭的聚会。

add_member(gathering_id: str, member_name: str)

向现有聚会添加新成员。

remove_member(gathering_id: str, member_name: str)

从聚会中移除成员（仅限没有任何费用的成员）。

示例流程

1. 为与 5 位朋友共进晚餐创建一个聚会：

   create_gathering("2023-10-15-dinner", 5)
   

2. 在大家付款时添加费用：

   add_expense("2023-10-15-dinner", "Alice", 120.50)
   add_expense("2023-10-15-dinner", "Bob", 35.00)
   

3. 计算报销金额：

   calculate_reimbursements("2023-10-15-dinner")
   

4. 在大家结清款项时记录付款：

   record_payment("2023-10-15-dinner", "Charlie", 31.10)
   

5. 所有款项结清后关闭聚会：

   close_gathering("2023-10-15-dinner")
   

架构

Gatherings MCP 服务由三个主要组件构成：

1. MCP 服务接口（gatherings_mcp_server.py）：提供 AI 工具可交互的 MCP 协议接口。

2. 服务层（services.py）：包含管理聚会、费用和付款的业务逻辑。

3. 数据层（models.py）：使用 SQLAlchemy ORM 定义数据库架构并处理数据持久化。

数据模型

• 聚会：表示需要分摊费用的社交活动
• 成员：聚会的参与者
• 费用：成员为聚会支出的款项
• 付款：成员为结清余额而支付的款项

贡献

欢迎贡献！请随时提交 Pull Request。