Pulse Backend MCP Server

Pulse Backend MCP サーバー

社内の開発者が生産性を高められるよう、BigQuery へのアクセスと専門的なデータツールを提供する Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーは、Model Context Protocol を実装し、LLM を活用したアプリケーションが会社のデータにアクセスし、専門的なデータ処理を制御された方法で実行できるようにします。このサーバーは、BigQuery および社内固有のデータ構造を操作するための複数のツールを公開します。

プロジェクト構成

pulse-backend-mcp/
├── README.md                 # Project documentation
├── pyproject.toml            # Python project configuration
├── uv.lock                   # Dependency lock file
├── .env                      # Environment variables (create this file)
└── src/                      # Source code directory
    └── server.py             # Main MCP server implementation

MCP とは？

Model Context Protocol（MCP）は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。USB-C がデバイスを周辺機器に接続する標準的な方法を提供するのと同じように、MCP は AI モデルをさまざまなデータソースやツールに接続する標準的な方法を提供します。

MCP アーキテクチャ

MCP はクライアント・サーバーアーキテクチャを採用しています。

• MCP ホスト：Claude Desktop、IDE、AI ツールなど、MCP を介してデータにアクセスするプログラム
• MCP クライアント：サーバーと 1 対 1 の接続を維持するプロトコルクライアント
• MCP サーバー：標準化されたプロトコルを通じて特定の機能を公開する軽量なプログラム（このサーバーなど）
• データソース：MCP サーバーが安全にアクセスできるデータベース、ファイル、サービス

通信の流れ

1. ホストアプリケーション（例：Claude Desktop）が MCP サーバーへの接続を開始します
2. クライアントは tools/list エンドポイントを通じて、利用可能なツールを検出します
3. ユーザーからプロンプトを受けると、LLM はツールを使って BigQuery クエリを実行したり、クライアント情報を取得したりできます
4. サーバーは要求された操作を実行し、結果をクライアントに返します
5. クライアントはホストアプリケーション内で結果をユーザーに提示します

主な機能

• BigQuery 連携：社内の BigQuery データセットに対して SQL クエリを実行
• クライアントデータへのアクセス：データウェアハウスからクライアントの詳細情報とデータセットを取得
• 拡張可能なアーキテクチャ：新たなユースケースに対応するツールを追加

前提条件

• Python 3.13 以降
• BigQuery にアクセスできる Google Cloud アカウント
• 適切な権限を持つサービスアカウントの認証情報
• ClickUp API キー（タスク連携用）

インストール

1. リポジトリをクローンします。

   git clone https://github.com/yourusername/saras-mcp.git
   cd saras-mcp
   

2. 仮想環境を作成します。

   python -m venv venv
   source venv/bin/activate  # On Windows, use: venv\Scripts\activate
   

3. 依存関係をインストールします。

   pip install -r requirements.txt
   

設定

1. 次のいずれかの方法で Google Cloud の認証情報を設定します。

   • GOOGLE_APPLICATION_CREDENTIALS 環境変数に、サービスアカウントキーファイルのパスを設定します。

     export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
     

   • ツールの呼び出し時に、サービスアカウントのパスを直接渡します

2. ルートディレクトリに .env ファイルを作成し、次の変数を設定します。

   GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
   GOOGLE_PROJECT_ID=your-project-id
   CLICKUP_API_KEY=your-clickup-api-key
   

3. （任意）必要に応じて、ツール定義のデフォルトプロジェクト ID を変更します

使い方

インスペクターで MCP サーバーを起動します。

mcp dev src/server.py

サーバーはデフォルトの MCP ポート（通常は 8080）で起動します。これで、MCP 対応クライアントをこのサーバーに接続できます。

MCP Inspector でのテスト

サーバーの実装をテストするには、次の手順に従います。

1. MCP Inspector をインストールします
2. 起動中のサーバーに接続します
3. 利用可能なツールを確認し、機能をテストします

利用可能なツール

1. execute_bigquery

BigQuery SQL クエリを実行し、構造化データとして結果を取得します。

パラメーター：

• query（文字列、必須）：実行する SQL クエリ
• project_id（文字列、任意）：Google Cloud プロジェクト ID（デフォルト："insightsprod"）
• service_account_path（文字列、任意）：サービスアカウント JSON 認証情報のパス

ツールの注釈：

• 読み取り専用：はい（データを変更しません）
• オープンワールド：はい（外部の BigQuery サービスと連携します）

2. get_client_details

データウェアハウスからクライアント情報を取得します。

パラメーター：

• client_id（string、任意）：絞り込みに使用する特定のクライアント ID
• client_name（string、任意）：検索するクライアント名（一部一致に対応）
• project_id（string、任意）：Google Cloud プロジェクト ID（デフォルト："insightsprod"）
• service_account_path（string、任意）：サービスアカウントの JSON 認証情報へのパス

ツールのアノテーション：

• 読み取り専用：はい（データを変更しません）
• オープンワールド：いいえ（内部データウェアハウスを操作します）

3. get_client_datasets

特定のクライアントで利用可能なデータセットを取得します。

パラメーター：

• client_id（string、任意）：絞り込みに使用する特定のクライアント ID
• client_name（string、任意）：検索するクライアント名（一部一致に対応）
• project_id（string、任意）：Google Cloud プロジェクト ID（デフォルト："insightsprod"）
• service_account_path（string、任意）：サービスアカウントの JSON 認証情報へのパス

ツールのアノテーション：

• 読み取り専用：はい（データを変更しません）
• オープンワールド：いいえ（内部データウェアハウスを操作します）

4. get_dataset_tables

特定の BigQuery データセット内のすべてのテーブルと、そのメタデータを一覧表示します。

パラメーター：

• dataset_id（string、必須）：テーブルを一覧表示する BigQuery データセットの ID
• project_id（string、任意）：Google Cloud プロジェクト ID（デフォルト：環境から取得）
• service_account_path（string、任意）：サービスアカウントの JSON 認証情報へのパス

ツールのアノテーション：

• 読み取り専用：はい（データを変更しません）
• オープンワールド：いいえ（内部データウェアハウスを操作します）

5. get_clickup_task

特定の ClickUp タスクに関する詳細情報を取得します。

パラメーター：

• task_id（string、必須）：ClickUp タスクの一意の識別子
• api_key（string、任意）：認証用の ClickUp API キー（デフォルト：環境から取得）
• include_subtasks（boolean、任意）：サブタスクの情報を含めるかどうか
• include_comments（boolean、任意）：タスクのコメントを含めるかどうか

ツールのアノテーション：

• 読み取り専用：はい（データを変更しません）
• オープンワールド：はい（外部の ClickUp API と連携します）

サーバーの拡張

新しいツールの追加

MCP サーバーに新しいツールを追加するには：

1. server.py に @mcp.tool() を付けた新しい関数を追加します
2. 関数のパラメーターと戻り値の型を定義します
3. ツールの目的と使い方を説明する、充実した docstring を追加します
4. 堅牢なユーザーエクスペリエンスを実現するため、エラー処理を実装します

例：

@mcp.tool()
def my_new_tool(param1: str, param2: int = 0) -> dict:
    """Description of what the tool does.

    Args:
        param1: Description of param1
        param2: (Optional) Description of param2

    Returns:
        Dictionary containing the results or error information
    """
    try:
        # Implementation
        return {"success": True, "results": [...]}
    except Exception as e:
        return {
            "success": False, 
            "error": "Error Type", 
            "message": str(e),
            "code": 500
        }

適切なエラー処理

エラーが発生する可能性があるツールでは：

1. 適切なエラー構造を使用します
2. 可能な場合は具体的なエラーコードを返します
3. 意味のあるエラーメッセージを提示します

例：

try:
    # Tool operation
    result = perform_operation()
    return {"success": True, "results": result}
except NotFound as e:
    return {
        "success": False,
        "error": "Not Found",
        "message": str(e),
        "code": 404,
    }
except Exception as e:
    return {
        "success": False,
        "error": "Execution Error",
        "message": str(e),
        "code": 500,
    }

ツールのアノテーション

ツールを定義する際は、クライアントがツールの動作を理解できるよう、次のアノテーションの追加を検討してください。

• readOnlyHint：ツールが環境を変更するかどうかを示します
• destructiveHint：ツールが破壊的な操作を実行する可能性があるかどうかを示します
• idempotentHint：同じ引数で繰り返し呼び出しても追加の効果がないかどうかを示します
• openWorldHint：ツールが外部のエンティティと連携するかどうかを示します

セキュリティに関する考慮事項

MCP サーバーを開発する際は、次のセキュリティのベストプラクティスに従ってください。

1. 入力の検証

   • すべてのパラメーターをスキーマに照らして検証します
   • インジェクション攻撃を防ぐため、SQL クエリをサニタイズします
   • パラメーターのサイズと範囲を確認します

2. アクセス制御

   • 必要に応じて適切な認証を実装します
   • 機密データへのアクセスには適切な認可を使用します
   • リソースを大量に消費する操作には、レート制限を検討します

3. エラー処理

   • 内部エラーをクライアントに公開しないでください
   • セキュリティに関係するエラーをログに記録します
   • エラー発生後は、適切にリソースをクリーンアップします

MCP プロトコルのリソース

• MCP の紹介
• コアアーキテクチャ
• リソース
• ツール
• MCP サーバー開発者ガイド

コントリビューション

1. 機能追加またはバグ修正用の新しいブランチを作成します
2. 変更内容に適切なテストを追加します
3. 変更内容を明確に説明したプルリクエストを送信します

ライセンス

[ライセンスをここに記入]