Universal MCP Tool Framework

Model Context Protocol ツールのための再利用可能なPython基盤です。このフレームワークは、登録、ディスカバリ、権限、操作モードの分離、構造化エラー、ロギング、設定、ヘルス/ステータス出力、拡張規約を一元化します。

設計上の境界

このフレームワークはMCP サーバー基盤であり、汎用シェル、ファイルシステムコントローラ、ポリシーエンジンではありません。ツールは明示的に登録され、ひとつの権限境界を通過して実行されます。

ツールは両方のチェックを通過する必要があります。つまり、操作モードが有効であり、必要なスコープが実行コンテキストに存在することです。

Related MCP server: achmadya-dev/mcp-core

同梱される機能

要件

• Python 3.10+

• 公式 MCP Python SDK を mcp==2.0.0 に固定

クイックスタート

python -m venv .venv
. .venv/bin/activate
pip install -e .
python -m unittest discover -s tests -p "test_*.py"

MCP SDK 経由でサーバーを起動します:

mcp run server.py

MCP Inspector での対話的な開発向け:

mcp dev server.py

設定

読み取り以外の操作が必要な場合のみ、サンプルをコピーして変更してください。

{
  "server_name": "Universal MCP Tool Framework",
  "enabled_modes": ["read"],
  "log_level": "INFO"
}

read が唯一のデフォルトモードです。登録済みの書き込みツールを許可するには write を追加し、登録済みの実行ツールを許可するには execute を追加します。モードを有効にしても、ツール単位で必須となるスコープが回避されることはありません。

選択した設定ファイルを指定してサーバーを起動します:

UNIVERSAL_MCP_CONFIG=config.json mcp run server.py

ツールを追加する

1. 操作モードを 1 つ選択します。

2. 必要なスコープをすべて宣言します。

3. ToolRegistry を介してハンドラを登録します。

4. ディスカバリ、許可された実行、拒否パスのテストを追加します。

5. ツールが公開サーバーの機能に含まれる場合にのみ、薄い MCP ハンドラを公開します。

from universal_mcp.models import OperationMode
from universal_mcp.registry import ToolRegistry

registry = ToolRegistry()

@registry.register(
    name="inventory_get_item",
    description="Return one inventory item by stable identifier.",
    mode=OperationMode.READ,
    required_scopes={"inventory:read"},
)
def inventory_get_item(item_id: str) -> dict[str, str]:
    return {"item_id": item_id}

共通の権限・ロギング・エラー契約が常に適用されるよう、ToolRuntime.execute() を経由して呼び出します。

結果コントラクト

すべてのランタイム実行は、この安定したエンベロープを生成します:

{
  "ok": true,
  "data": {},
  "error": null
}

拒否および失敗したリクエストは ok: false となり、tool_not_found、permission_denied、tool_execution_failed などの機械可読なエラーコードを伴います。

リポジトリ構造

.
├── config.example.json
├── pyproject.toml
├── server.py
├── src/universal_mcp/
│   ├── config.py
│   ├── examples.py
│   ├── models.py
│   ├── registry.py
│   ├── runtime.py
│   └── server.py
└── tests/test_framework.py

検証

python -m unittest discover -s tests -p "test_*.py"

テストスイートは、登録、ディレクトリ、デフォルトの読み取りアクセス、デフォルトでの書き込み/実行拒否、スコープの強制、構造化エラー、ステータス出力、JSON 設定を検証します。

ユニバーサルプロジェクトセットアップツールキット

このリポジトリは、再現可能な Python プロジェクト作成のための制御ジェネレータ umcp-scaffold も提供します。

完全に初期化されたプロジェクトを作成します。デフォルトでは、ジェネレーターはローカル Git リポジトリを作成し、分離した .venv を作成し、ローカル依存関係をインストールし、生成されたプロジェクトを検証します。

umcp-scaffold create "My Project" ./my-project --type mcp-tool

生成後のプロジェクトを後で検証するには:

umcp-scaffold validate ./my-project

生成されるすべてのプロジェクトには、スキーマバージョン、名前、パッケージ名、テンプレートの種類、ライフサイクル状態、Git の可否フラグ、作成時刻、最後の検証状態を含む .project-state.json が付与されます。ジェネレーターは、プロジェクトを上書きせず、空でないターゲットディレクトリを拒否します。

ローカルコード解析・品質ツールキット

umcp-quality はローカル Python プロジェクトを検査し、PASS、FAIL、WARNING の結果を含む機械可読な品質レポートを返します。

umcp-quality ./my-project
umcp-quality ./my-project --format markdown

FAIL は非ゼロのコマンド終了ステータスを生成します。WARNING は、仮想依存が無い、テストが無い、設定ディレクトリが無い、Git 履歴が利用できないなど、不合格ではないが不完全な状態を示します。