Gatherings MCP 服务器

一个用于 Gatherings 费用分摊应用程序的机器会话协议 (MCP) 服务器接口。

概述

Gatherings MCP 服务器提供了一个 API，允许 AI 助手通过机器会话协议与 Gatherings 应用程序进行交互。 这使 AI 系统能够帮助用户管理社交活动、郊游或任何参与者之间分摊费用的聚会的共享费用。

功能

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

安装

前提条件

• Python 3.8+
• SQLAlchemy
• MCP SDK

设置

1. 克隆此存储库：

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

2. 安装所需的依赖项：

   pip install -r requirements.txt
   

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

   # 自定义数据库位置
   export GATHERINGS_DB_PATH=path/to/database.db
   
   # 自定义脚本位置
   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 定义数据库模式并处理数据持久性。

数据模型

• Gathering: 代表一个有费用需要分摊的社交活动
• Member: 聚会的参与者
• Expense: 成员为聚会花费的钱
• Payment: 成员为结算余额而支付的钱

贡献

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