UVG ローカル MCP サーバー

著者: Anggelie Velásquez — 学籍番号 221181 Universidad del Valle de Guatemala — コース CC3067

1. 説明

ローカル MCP（Model Context Protocol）サーバー。FastMCP や公式 MCP SDK を一切使わず、標準 Python 3 でゼロから実装。サーバーは stdio を介してクライアントと通信し、JSON-RPC 2.0 を手動で実装している。

Related MCP server: @belal-elsabbagh-apex/copilot-mcp

2. 目的

プロトコルを手動で構築し、そのロジックを隠すライブラリに依存せずに、MCP サーバーのライフサイクル（initialize → notifications/initialized → tools/list → tools/call）の理解を示すこと。

3. アーキテクチャ

Cliente MCP  <-- stdio (stdin/stdout) -->  server.py
                                              │
                                    ┌─────────┴─────────┐
                                    │                    │
                                jsonrpc.py           tools.py
                          (formato JSON-RPC 2.0)  (herramientas)

• server.py: エントリポイント。stdin の読み取りループとメソッドのルーティング。

• jsonrpc.py: JSON-RPC 2.0 のレスポンス/エラー構築と基本的な検証。

• tools.py: ツールの一元登録（メタデータ + スキーマ + 実行関数）。

4. 使用プロトコル

• トランスポート: stdio（標準入力 / 標準出力）。

• フレーミング: 1 行に 1 つの JSON-RPC 2.0 メッセージ（JSON Lines / NDJSON）。Content-Length 形式のフレーミングは使用しない。

• メッセージ形式: JSON-RPC 2.0。手動実装（JSON-RPC ライブラリも MCP ライブラリも不使用）。

• 報告される MCP プロトコルバージョン: 2024-11-05（initialize レスポンスの protocolVersion フィールド）。

• stdout は JSON-RPC レスポンス専用。すべてのログは stderr に送信。

5. 実装済み MCP メソッド

その他のメソッドは JSON-RPC エラー -32601 Method not found を返す。

6. 利用可能なツール

analizar_texto

入力: { "texto": "Hola mundo" } 返り値: 文字数、単語数、行数、大文字変換テキスト、小文字変換テキスト。

calcular_estadisticas

入力: { "numeros": [10, 20, 30, 40] } 返り値: 個数、合計、平均、最小値、最大値。 numeros がリストであり、空でなく、数値のみを含むことを検証する。

informacion_sistema

引数なし。返り値: オペレーティングシステム、Python バージョン、プラットフォーム、現在の作業ディレクトリ。 パスワード、トークン、環境変数、ファイルの内容は公開しない。

7. 要件

• Python 3.8 以上。

• 外部依存関係は不要（requirements.txt を参照）。

8. インストール

git clone https://github.com/Anggelie/mcp-local-server-uvg.git
cd mcp-local-server-uvg

9. サーバーを手動で実行する方法

PowerShell から、サーバーは stdin からのメッセージを待機する:

python src/server.py

JSON の 1 行を入力して Enter を押すことができる。例:

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}

サーバーは stdout に JSON の 1 行で応答する。終了するには、Ctrl+Z を押してから Enter を押す（Windows の stdin 終了）。

サンプルファイル全体を一度に送信することもできる:

Get-Content examples/requests.jsonl | python src/server.py

10. テスト方法

自動テスト（unittest）

python -m unittest discover tests -v

デモクライアント（サブプロセス）

python examples/test_client.py

このスクリプトは src/server.py をサブプロセスとして起動し、3 つのツールに対して initialize -> initialized -> tools/list -> tools/call のサイクルを自動実行する。さらに、存在しないメソッドのケースも実行する。

11. MCP クライアントでの設定方法

サンプル設定が client-config/claude_desktop_config.example.json に含まれている:

{
  "mcpServers": {
    "uvg-local-server": {
      "command": "python",
      "args": [
        "C:\\RUTA\\AL\\PROYECTO\\src\\server.py"
      ]
    }
  }
}

重要: C:\RUTA\AL\PROYECTO を、このリポジトリをクローンした実際のパスに置き換えること。

12. 例

examples/requests.jsonl を参照。1 行に 1 つの JSON-RPC メッセージが含まれており、initialize、notifications/initialized、tools/list、3 つのツールに対する tools/call、およびエラーケースをカバーしている。

13. プロジェクト構造

mcp-local-server-uvg/
│
├── src/
│   ├── server.py      # Punto de entrada del servidor
│   ├── jsonrpc.py      # Utilidades JSON-RPC 2.0
│   └── tools.py        # Registro de herramientas
│
├── tests/
│   ├── test_jsonrpc.py
│   └── test_tools.py
│
├── examples/
│   ├── requests.jsonl
│   └── test_client.py
│
├── client-config/
│   └── claude_desktop_config.example.json
│
├── .gitignore
├── requirements.txt
├── README.md
└── README_ES.md

14. エラー処理

JSON-RPC 2.0 の標準コードを実装している: