MCP Tool Server (

MCP ツールサーバー（mcp_server.py）

mcp_server.py スクリプトは、さまざまな通信トランスポートを介して Python 関数を「ツール」として公開するために設計された非同期サーバーです。FastMCP フレームワークを利用してツールを管理し、クライアントとのやり取りを処理します。組み込みツールが用意されており、Python ファイルやディレクトリからカスタムツールを動的に読み込むこともできます。

機能

• 複数のトランスポート：以下を介した通信をサポートします。
  • stdio：標準入出力。コマンドラインからの直接操作や、ほかのプロセスとの連携に適しています。
  • sse：Server-Sent Events。ウェブクライアントがツールの出力を購読できます（http://<host>:<port>/sse で待ち受けます）。
• 組み込みツール：
  • echo：呼び出し時に渡されたパラメーターを返します。
  • health：サーバーの稼働状態を報告します（"ready" を返します）。
• カスタムツールの読み込み：
  • 指定された .py ファイル、または .py ファイルを含むディレクトリから、Python 関数をツールとして動的に読み込みます。
  • 各ツールファイルには、ツールとして公開する関数をちょうど1つ定義する必要があります。
  • ツールファイル内でのインポートをサポートします。
• 設定可能なログ記録：
  • デフォルトでは、INFO レベルのメッセージをコンソールに出力します。
  • サーバーアプリケーションと基盤となる MCP SDK の両方について、指定したファイルへの詳細な DEBUG レベルのログ記録をサポートします。
• 非同期処理：asyncio を使用して構築されており、同時処理を効率的に扱えます。

前提条件

• Python 3.x
• Python パッケージの mcp（特に mcp.server.fastmcp を使用します）。Python 環境にこのパッケージがインストールされていることを確認してください。

コマンドラインでの使用方法

概要

python mcp_server.py [tools_paths...] [--log FILENAME] [--transport {stdio,sse}] [--port PORT]

オプション

• tools_paths（位置引数、0個以上）

  • Python ツールファイル、または Python ツールファイルを含むディレクトリへのパスです。
  • ディレクトリを指定すると、サーバーは _ で始まるファイルを除く *.py ファイルを検索します。
  • 例：./my_tool.py ./utils_directory
  • デフォルト：なし（パスを指定しない場合は、組み込みツールのみが利用できます）。

• --log FILENAME

  • 指定したファイルへの詳細なログ記録を有効にします（アプリケーションと MCP SDK の DEBUG レベル）。
  • ツールの呼び出し、応答、内部処理の詳細をすべて含みます。
  • コンソールには引き続き INFO レベルのメッセージが表示されます。

• --transport {stdio|sse}

  • 使用する通信トランスポートです。
  • stdio：標準入出力を使用します。
  • sse：Server-Sent Events を使用します。サーバーはデフォルトで 0.0.0.0 で待ち受けます。
  • デフォルト：stdio

• --port PORT

  • SSE トランスポートで使用するポート番号です。
  • デフォルト：8080

ツールの読み込み

カスタムツールは、サーバーが公開できる Python 関数です。

• 定義：ツールモジュールとして使用する各 Python ファイル（.py）には、関数をちょうど1つ定義する必要があります。この関数がツールとして登録されます。関数名がツール名になります。
• 検出：
  • .py ファイルへのパスが指定されると、サーバーはそのファイルからツールの読み込みを試みます。
  • ディレクトリへのパスが指定されると、サーバーはそのディレクトリ内の .py ファイル（__init__.py などのファイルや、アンダースコアで始まるファイルを除く）を検索し、有効な各ファイルからツールの読み込みを試みます。
• インポート：ツールファイルでは、必要に応じてほかのモジュールをインポートできます。ローカルインポートを可能にするため、読み込み中はツールのディレクトリが一時的に sys.path に追加されます。

例

1. カスタムツールの作成

たとえば、calculator.py という Python ファイルを作成します。

# calculator.py
def add(a: int, b: int) -> int:
    """
    Adds two integers and returns the result.
    """
    print(f"Tool 'add' called with a={a}, b={b}") # Example of internal tool logging
    return a + b

2. サーバーの実行

a) 組み込みツールのみを使用する場合（stdio トランスポート）：

python mcp_server.py

サーバーが起動し、標準入力／出力を介して echo ツールと health ツールを操作できます（詳細は FastMCP クライアントのインタラクションプロトコルによって異なります）。

b) カスタムツールを使用する場合（stdio トランスポート）：

python mcp_server.py calculator.py

これで、calculator.py の add ツールも利用できるようになります。

c) ツールのディレクトリと詳細なログを使用する場合（stdio トランスポート）：

calculator.py やほかのツールファイルを含む、my_tools という名前のディレクトリがあるものとします。

mkdir my_tools
mv calculator.py my_tools/
# You can add more .py tool files to my_tools/

python mcp_server.py my_tools --log server.log

サーバーは my_tools ディレクトリから有効なツールをすべて読み込みます。詳細なログは server.log に書き込まれ、INFO メッセージはコンソールに出力されます。

d) SSE トランスポートを使用する場合：

python mcp_server.py calculator.py --transport sse --port 8888

サーバーが起動し、http://0.0.0.0:8888/sse で SSE 接続を待ち受けます。クライアントはこのエンドポイントに接続して、echo、health、add ツールを操作できます。

サーバーとのやり取り（概念）

ツールとのやり取りの方法は、選択したトランスポートと FastMCP のクライアント側の実装によって異なります。

• stdio の場合：通常は、JSON-RPC 形式のメッセージをサーバーの標準入力に送信し、標準出力から応答を受け取ります。

  // stdio の概念的な入力例（実際の形式は FastMCP によって異なります）
  // {"jsonrpc": "2.0", "method": "add", "params": {"a": 5, "b": 3}, "id": 1}
  

• sse の場合：クライアントは /sse エンドポイントに接続します。その後、サーバーはツールの呼び出しと応答に関するメッセージをプッシュします。

ロギング

• コンソール：デフォルトでは、INFO レベルのメッセージが stdout に出力されます。これにはサーバーの起動メッセージ、登録されたツール、基本的な動作が含まれます。
• ファイルへのロギング（--log オプション）：
  • mcp_server.py と mcp SDK の両方で、DEBUG レベルのロギングが有効になります。
  • 非常に詳細なログで、次の内容が含まれます。
    • ツール呼び出しのパラメーターと結果の詳細。
    • サーバー内部の処理。
    • MCP SDK のデバッグメッセージ。
  • ログファイルは、次のような形式で書き込まれます：%(asctime)s - %(name)s - %(levelname)s - %(message)s。

シャットダウン

サーバーを正常にシャットダウンするには、Ctrl+C を押します。