Gatherings MCP Server

Gatherings MCP サーバー

集まりや費用の分担を管理するための Model Context Protocol サーバーです。

依存関係の管理

このプロジェクトでは、Python の依存関係の管理に pip ではなく uv を使用します。これは、Model Context Protocol Python SDK の依存関係要件に対応するために必要な変更です。

uv がインストールされていることを確認するか、pip 経由でインストールしてください：

pip install uv

プロジェクトの依存関係をインストールするには：

uv pip install -r requirements.txt

概要

Gatherings MCP サーバーは、AI アシスタントが Machine Conversation Protocol を通じて Gatherings アプリケーションを操作できる API を提供します。これにより、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 サーバーは、主に3つのコンポーネントで構成されています：

1. MCP サーバーインターフェース（gatherings_mcp_server.py）：AI ツールが操作できる MCP プロトコルのインターフェースを提供します。

2. サービスレイヤー（services.py）：集まり、費用、支払いを管理するビジネスロジックを含みます。

3. データレイヤー（models.py）：SQLAlchemy ORM を使用してデータベーススキーマを定義し、データの永続化を処理します。

データモデル

• Gathering：分担する費用がある社交イベントを表します
• Member：集まりの参加者です
• Expense：集まりのためにメンバーが支出した金額です
• Payment：残高を精算するためにメンバーが支払った金額です

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。