gatherings MCP Server

gatherings MCP サーバー

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

これは、交流イベントの費用や支払いを追跡し、友人同士の精算額や残高を簡単に計算できる TypeScript ベースの MCP サーバーです。

アーキテクチャに関する注意事項

重要：このプロジェクトでは、Node.js アプリケーションとして標準的ではないアーキテクチャを採用しています。TypeScript 製の MCP サーバーは、Python バックエンド実装のラッパーとして機能します。Node.js サーバーは MCP リクエストを受け取り、Python スクリプトを呼び出すコマンドライン呼び出しに変換して、結果を返します。

現在のニーズには対応できていますが、本番アプリケーション向けとしては、最も効率的で保守しやすい方法ではありません。

TODO

• より標準的なアーキテクチャを採用するよう、実装をリファクタリングする：
  • バックエンドを TypeScript／JavaScript に完全移行する
  • または、Node.js コンポーネントと Python コンポーネント間に適切なプロセス間通信を実装する
  • または、Python バックエンドが API を提供し、MCP サーバーがそれを利用する REST API 方式に置き換える
• Node.js コンポーネントと Python コンポーネント間のエラー処理を改善する
• コンポーネント間の連携を対象とした自動テストを追加する
• Dockerfile を最適化する

機能

ツール

• 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 サーバーは標準入出力を介して通信するため、デバッグが難しい場合があります。パッケージスクリプトとして利用できる MCP Inspector の使用をおすすめします：

npm run inspector

Inspector は、ブラウザーでデバッグツールにアクセスするための URL を表示します。