test-dh-mcp

test-dh-mcp

このプロジェクトでは、FastMCP 実装を使用して MCP（Multi-Channel Protocol）サーバーを定義し、実行する方法を紹介します。ツールの登録、サーバー／クライアントの使用方法、Claude Desktop および MCP Inspector との統合例が含まれています。

• MCP サーバーのクイックスタート
• mcp Python パッケージのドキュメント（PyPI）

プロジェクト構成

• src/mcp_server.py — MCP サーバーを実行するためのメインエントリーポイント（SSE または stdio トランスポートに設定可能）。
• src/dhmcp/__init__.py — @mcp_server.tool() デコレーターを使用して、すべてのツールを登録します。
• src/mcp_client.py — ツールのテストに使用する非同期クライアントの例。
• requirements.txt — Python の依存関係（mcp[cli] と autogen-ext を含む）。

依存関係管理に uv を使用する

uv は、最新の超高速な Python パッケージマネージャー兼ランナーです。pip と venv のドロップイン代替として使用でき、インストールの高速化と依存関係管理の改善を実現します。

主な概念

• pyproject.toml：プロジェクトの依存関係とメタデータを指定する、最新の推奨方式です。uv はこれを信頼できる情報源として使用します。
• requirements.txt：従来の Python ツールやワークフローとの互換性のためにサポートされています。pyproject.toml を使用する場合は任意です。
• uv.lock：再現可能なインストールのためのロックファイルです（uv が自動管理します）。

最新のワークフロー（推奨）

1. 依存関係をプロジェクトに直接追加します：

   uv pip install <package>
   # Example:
   uv pip install autogen-ext mcp[cli]
   

   これにより pyproject.toml と uv.lock が更新されます。
2. 環境を同期します：

   uv pip install  # Installs all dependencies from pyproject.toml
   

3. スクリプトを実行します：

   uv run src/mcp_server.py
   uv run src/mcp_client.py
   

4. 依存関係をアップグレードします：

   uv sync --upgrade
   

互換性を重視したワークフロー（requirements.txt）

• 既存の requirements.txt がある場合は、次のコマンドを使用できます：

  uv pip install -r requirements.txt
  # or
  uv add --requirements requirements.txt
  

• これにより依存関係が同期され、ロックファイルが更新されます。互換性を最大限に高めるため、両方のファイルを同期した状態に保つことができます。

補足

• uv では requirements.txt は任意です。新しいプロジェクトでは、pyproject.toml と uv.lock のみを使用できます。
• レガシープロジェクトや pip を使うユーザーと共有する場合は、requirements.txt を最新の状態に保ってください。
• uv は仮想環境の有無にかかわらず動作します。必要に応じて uv venv .venv を使用して作成してください。
• 複数の環境がある場合は、--active を使用して現在アクティブな環境を対象にしてください。

クイックスタート：サーバー

1. 依存関係をインストールする

仮想環境の使用をおすすめします。

• venv を使用する場合：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• uv を使用する場合：

uv pip install -r requirements.txt

2. MCP サーバーを実行する

プロジェクトのルートディレクトリから、用途に合ったトランスポートを選んで実行します。

• SSE トランスポート（デフォルト、ブラウザー／Web クライアント向け）：

  python src/mcp_server.py
  # or, explicitly:
  python src/mcp_server.py --transport sse
  # or, using uv:
  uv run src/mcp_server.py
  

  サーバーは http://localhost:8000/sse でリッスンします。

• Stdio トランスポート（Claude Desktop／Inspector に推奨）：

  python src/mcp_server.py --transport stdio
  # or, using uv:
  uv run src/mcp_server.py --transport stdio
  

  サーバーは stdio 経由で通信します（HTTP ポートは不要です）。

選択したトランスポートでサーバーが実行中であることを示すログが表示されます。

クイックスタート：クライアント

注： Python クライアント（mcp_client.py）を使用するには、MCP サーバーがSSE モード（デフォルト）で実行されている必要があります。サーバーが stdio モードで実行されている場合は動作しません。

1. 依存関係をインストールする

仮想環境の使用をおすすめします。

• venv を使用する場合：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• uv を使用する場合：

uv pip install -r requirements.txt

2. MCP クライアントを実行する

プロジェクトのルートディレクトリから実行します。

• venv を使用する場合：

cd src
python -m mcp_client

• uv を使用する場合：

cd src
uv run mcp_client.py

クライアントが実行中で、利用可能なツールの一覧が表示されていることを示すログが出力されます。

Claude Desktop

カスタムツールを使用するには、Claude Desktop をローカルの stdio MCP サーバーに接続できます。

1. ~/Library/Application\ Support/Claude/claude_desktop_config.json を編集して、MCP サーバーを追加します。Deephaven ワーカーの設定は、現在すべて JSON 設定ファイルで管理されており、パスは必須の DH_MCP_CONFIG_FILE 環境変数を使って指定する必要があります。デフォルトのパスはありません。この環境変数は必ず設定してください。

   Claude Desktop の設定例（venv を使用）：

   {
     "mcpServers": {
       "test-dh-mcp": {
         "command": "/Users/chip/dev/test-dh-mcp/.venv/bin/python3",
         "args": ["/Users/chip/dev/test-dh-mcp/src/mcp_server.py", "--transport", "stdio"],
         "env": {
           "DH_MCP_CONFIG_FILE": "/Users/chip/dev/test-dh-mcp/deephaven_workers.json"
         }
       }
     }
   }
   

   または、uv を使用する場合：

   {
     "mcpServers": {
       "test-dh-mcp": {
         "command": "uv",
         "args": [
           "--directory",
           "/Users/chip/dev/test-dh-mcp/src",
           "run",
           "mcp_server.py",
           "--transport",
           "stdio"
         ],
         "env": {
           "DH_MCP_CONFIG_FILE": "/Users/chip/dev/test-dh-mcp/deephaven_workers.json"
         }
       }
     }
   }
   

   注：プロジェクトのルートにある設定ファイルの名前が deephaven_workers.json ではない場合、または設定ファイルの場所を明示したい場合は、必ず env セクションで DH_MCP_CONFIG_FILE を設定してください。

      "args": [
        "--directory",
        "/Users/chip/dev/test-dh-mcp/src",
        "run", 
        "mcp_server.py", 
        "--transport", 
        "stdio"
      ],
      "env": {
        "DH_MCP_SERVER_NAME": "test-dh-mcp",
        "DH_MCP_HOST": "localhost",
        "DH_MCP_PORT": "10000",
        "DH_MCP_AUTH_TYPE": "Anonymous"
      }
    }
   

   } }

注： Deephaven セッションの設定セクションに記載されているすべての DH_MCP_* 環境変数をここで設定できます。これらの変数は、すべてのツール呼び出しにおける Deephaven セッションを制御します。

4. Claude Desktop を再起動します。
5. デバッグログは ~/Library/Logs/Claude/ にあります。

Deephaven ワーカーの設定

Deephaven ワーカーの設定はすべて JSON ファイルで行うようになりました。このファイルのパスは、DH_MCP_CONFIG_FILE 環境変数で指定する必要があります。デフォルトのパスはありません。この環境変数は必須です。

設定ファイルは次のようになります。

{
  "workers": {
    "worker1": {
      "host": "localhost",
      "port": 10000,
      "auth_type": "Anonymous",
      "auth_token": "",
      "never_timeout": true
    },
    "worker2": {
      "host": "otherhost",
      "port": 10001,
      "auth_type": "Bearer",
      "auth_token": "YOUR_TOKEN"
    }
  },
  "default_worker": "worker1"
}

• workers オブジェクトでは、ワーカー名と接続設定を対応付けます。
• default_worker は省略可能で、ツール呼び出しでワーカー名が指定されていない場合に使用されます。設定する場合は、workers ディクショナリのキーのいずれかと一致する必要があります。

重要： DH_MCP_CONFIG_FILE 環境変数には、必ずワーカー設定ファイルのパスを設定してください。デフォルトの設定パスはありません。

各ワーカーでサポートされるフィールド：

フィールド	型	説明
host	str	Deephaven サーバーのホスト名または IP（省略可能）
port	int	Deephaven サーバーのポート（省略可能）
auth_type	str	認証タイプ（例：Anonymous、Bearer）（省略可能）
auth_token	str	認証トークン（省略可能）
never_timeout	bool	セッションをタイムアウトさせないかどうか（省略可能、デフォルト：True）
session_type	str	セッションタイプ（例：python）（省略可能、デフォルト：'python'）
use_tls	bool	TLS/SSL を使用するかどうか（省略可能、デフォルト：False）
tls_root_certs	str or null	TLS ルート証明書のパス（省略可能）
client_cert_chain	str or null	クライアント証明書チェーンのパス（省略可能）
client_private_key	str or null	クライアント秘密鍵のパス（省略可能）

注：ユースケースや認証方式に応じて、これらのフィールドの一部だけを指定してワーカーを定義できます。必須のフィールドはありません。可能な場合はデフォルト値が使用されます。

ツールの使用方法

• echo_tool(message: str) -> str：入力メッセージの先頭に 'Echo:' を付けて返します。
• gnome_count_colorado() -> int：コロラド州に現在いるノームの数を返します（デモ用ツール）。
• deephaven_worker_names() -> list[str]：設定ファイルにあるすべての Deephaven ワーカー名を返します。
• deephaven_default_worker() -> str：設定で指定されているデフォルトワーカーの名前を返します（未設定の場合は None）。
• deephaven_list_tables(worker_name: str = None) -> list：指定したワーカーのテーブル名を一覧表示します。worker_name が指定されていない場合は、設定の default_worker を使用します。
• deephaven_table_schemas(worker_name: str = None) -> list：指定したワーカーのすべてのテーブルのスキーマを返します。worker_name が指定されていない場合は、設定の default_worker を使用します。

複数のワーカーを設定する方法については、上記の設定ファイルの例を参照してください。

ツールの登録

@mcp_server.tool() デコレーターを使用して、dhmcp/__init__.py で新しいツールを定義します。例：

@mcp_server.tool()
def echo_tool(message: str) -> str:
    """
    Echo tool that returns the input message prefixed with 'Echo:'.
    """
    return f"Echo: {message}"

トラブルシューティング

• 正しいディレクトリ（スクリプトを直接実行する場合は src）からコマンドを実行していることを確認してください。
• ツール定義を変更した場合は、サーバーを再起動してください。
• 接続に問題がある場合は、サーバーが起動して想定されるアドレス／ポートでリッスンしていること（SSE の場合）、または stdio を介して正しく接続されていること（Claude/Inspector の場合）を確認してください。

サーバーは起動していますか？

• SSE モード：

  curl http://localhost:8000/sse
  

• Stdio モード：
  • Claude/Inspector のログで、接続とツールの一覧表示が正常に行われたことを確認してください。

MCP Inspector

MCP Inspector は、MCP サーバーの状態を検査できるツールです。

1. MCP Inspector をインストールします：

   npm install -g @modelcontextprotocol/inspector@latest
   

2. MCP Inspector を実行します：

⚠️ WARNING: MCP Inspector を使用する場合、すべての文字列値を引用符で囲んで入力してください（例："worker1"）。 引用符を使用しないと、Inspector がサーバーに null または無効な値を送信する場合があります。 Format JSON ボタンをクリックすると、値を検証できます。

- ** SSE モード： **

    - `venv` を使用する場合：

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    /Users/chip/dev/test-dh-mcp/venv/bin/python3 mcp_server.py --transport sse
    ```

    - `uv` を使用する場合：

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    uv run mcp_server.py --transport sse
    ```

- ** Stdio モード： **

    - `venv` を使用する場合：

    ```
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    /Users/chip/dev/test-dh-mcp/venv/bin/python3 mcp_server.py --transport stdio
    ```

    - `uv` を使用する場合：

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    uv run mcp_server.py --transport stdio
    ```