Gatherings MCP Server

聚会 MCP 服务器

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

依赖管理

该项目使用uv而不是pip进行 Python 依赖项管理。由于模型上下文协议 Python SDK 的依赖项要求，因此必须进行此更改。

确保已安装uv或通过 pip 安装它：

安装项目依赖项：

概述

Gatherings MCP 服务器提供了一个 API，允许 AI 助手通过机器对话协议 (MCP) 与 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 服务器：

服务器在 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 请求。