MCP Mastery

MCP Mastery — 設計から進化まで

MCP サーバーのライフサイクル全体を5層でカバーする包括スキル。 Claude 公式 mcp-builder + mcp-integration を吸収し、Ryota エコシステムに最適化。

5層アーキテクチャ

Layer 5: 進化 (Evolution)     ← PCC + CBF + 蒸留
Layer 4: 運用 (Operations)     ← レジストリ, 監査, ヘルスチェック
Layer 3: 統合 (Integration)    ← マルチクライアント, HTTP Gateway
Layer 2: 実装 (Implementation) ← FastMCP パターン, ツール実装
Layer 1: 設計 (Design)         ← 3要素分類, セキュリティ, テナント

Progressive Disclosure: 各層の詳細は references/ で参照。

Layer 1: 設計 (Design)

MCP 3要素の分類

新サーバー設計時、全エンドポイントをこの3つに分類する:

ツール設計原則

1. 命名: {domain}_{action} — db_query, jobs_enqueue, obs_query_logs
2. 入力スキーマ: Pydantic で型・制約・description を定義
3. 出力: _wrap() / _wrap_err() envelope で統一
4. アノテーション:
   • readOnlyHint: true/false
   • destructiveHint: true/false (承認必須フラグ)
   • idempotentHint: true/false

セキュリティ基盤

• テナント分離: 全ツールで tenant_id を引き継ぎ、SET LOCAL app.tenant_id
• OPA ポリシー: 危険操作（DDL, 外部送信, DROP）を事前拒否
• Budget 管理: tenant_budgets で LLM/ジョブコスト制限
• 監査: 全ツール呼び出しを audit_trails に記録

→ 詳細: references/design-patterns.md

Layer 2: 実装 (Implementation)

Ryota スタック固定

Python 3.12+ / uv (パッケージ管理)
FastMCP SDK (MCP サーバー)
Granian (HTTP サーバー)
structlog (ログ)
Ruff (Lint/Format)
SQLModel (ORM)
pytest + httpx (テスト)

プロジェクト構造

my_mcp_server.py          # メインサーバー (FastMCP)
modules/
├── feature_a.py           # ドメインロジック
├── feature_b.py           # ドメインロジック
└── shared.py              # 共通ユーティリティ
pyproject.toml             # uv 依存関係

実装パターン

サーバー初期化

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("server-name")

Envelope ヘルパー

def _wrap(data: dict, summary: str = "", gate: str = "PASS") -> str:
    return json.dumps({
        "status": gate, "summary": summary,
        "data": data, "ts": datetime.now(UTC).isoformat(),
    }, ensure_ascii=False, default=str)

def _wrap_err(error_type: str, message: str, gate: str = "REJECT") -> str:
    return json.dumps({
        "status": gate, "error": error_type, "message": message,
        "ts": datetime.now(UTC).isoformat(),
    }, ensure_ascii=False)

遅延ロード (_Lazy パターン)

起動時間を <1s に抑えるため、重いモジュールは初回アクセス時にロード:

_modules = {}
def _get(name: str):
    if name not in _modules:
        _modules[name] = importlib.import_module(name)
    return _modules[name]

ツール登録

@mcp.tool()
def my_tool(param: str, count: int = 10) -> str:
    """ツールの説明（日本語OK）"""
    try:
        result = do_something(param, count)
        return _wrap(result, summary=f"Processed {count} items")
    except Exception as e:
        return _wrap_err("PROCESSING_ERROR", str(e))

→ 詳細: references/stack-reference.md → ゴールデンサンプル: ryota_ops_mcp_server.py (37ツール)

Layer 3: 統合 (Integration)

接続方式

マルチクライアント接続

各クライアントの接続テンプレートは references/client-configs.md を参照。

サポート対象:

• Antigravity (VS Code MCP 設定)
• Codex (CLI 直接実行)
• ChatGPT Developer Mode (MCP 設定)
• Gemini CLI (MCP 設定)
• OpenClaw (YAML 設定)
• Aladdin (Next.js → HTTP Gateway)
• n8n (HTTP Gateway → Webhook)

AI ロール別アクセス制御

ChatGPT（監査役）:
  ✅ Read Only ツール (audit, cbf_score, pcc_audit, system_info)
  ❌ Write ツール (macos_open_app, shell_run_safe, deploy_trigger)

Antigravity / Aladdin（実装者）:
  ✅ 全ツール使用可能

OpenClaw（自律ブラウザ）:
  ✅ audit + diff_guard + tests + pcc_audit
  🟡 macOS write は OrbStack 内のみ

Gemini CLI / Codex（大量処理）:
  ✅ pcc_audit, pcc_evolution_stats（直接実行）
  ⚠️ 2並行まで（レート制限回避）

レジストリ管理

全サーバーは mcp_registry.json で一元管理:

{
  "servers": {
    "server-name": {
      "file": "server.py",
      "transport": "stdio",
      "tools": 10,
      "version": "1.0",
      "status": "active"  // active | inactive | planned | archived
    }
  }
}

新サーバー追加時は必ずレジストリに登録すること。

→ 詳細: references/client-configs.md

Layer 4: 運用 (Operations)

サーバーライフサイクル

planned → active → (inactive) → archived

1. planned: MCP_SERVER_DESIGN.md に設計あり、未実装
2. active: 実装済み、接続可能
3. inactive: 実装あるが停止中（依存不足等）
4. archived: 廃止、参照のみ

ヘルスチェック

新サーバー実装後のチェックリスト:

• uv run python server.py で起動確認 (<1s)
• MCP Inspector (npx @modelcontextprotocol/inspector) でツール一覧確認
• 各ツールの基本動作テスト
• mcp_registry.json に登録
• structlog でログ出力確認
• エラーケースの _wrap_err() 確認

監査パターン

全ツール呼び出しは audit_trails テーブルに記録:

audit_log = {
    "tool": tool_name,
    "caller": evaluator_id,
    "input_hash": hashlib.sha256(input_json).hexdigest(),
    "result": "PASS" | "REJECT",
    "ts": datetime.now(UTC).isoformat()
}

失敗記録と学習

失敗は SKILL.md 末尾の表に追記し、次回の制約として自動注入:

Layer 5: 進化 (Evolution)

PCC パイプライン統合

新 MCP サーバーの各ツールを PCC で品質採点:

1. pcc_evaluate — ツール設計を5軸100点で評価
2. pcc_plan — 実装計画を PAC として記録
3. pcc_patch — 差分記録 + DoD 8カテゴリ採点
4. pcc_pipeline — 全履歴取得

CBF 品質ゲート

MCP ツール設計の品質判定に CBF 5軸を適用:

• Purpose (目的): ツールの責務は明確か
• Constraint (制約): セキュリティ・テナント分離は適切か
• Criteria (基準): 入出力スキーマは完全か
• Reproducibility (再現性): 同一入力で同一出力か
• Provenance (出自): 監査ログは記録されるか

蒸留データ生成

MCP ツール使用ログを JSONL で蒸留 → MLX fine-tuning:

pcc_distillation_export → training_data.jsonl

クイックリファレンス

新サーバー作成手順

1. MCP_SERVER_DESIGN.md で3要素を分類
2. my_server.py を FastMCP で実装（_wrap/_wrap_err 必須）
3. uv run python my_server.py で起動テスト
4. mcp_registry.json に登録
5. クライアント別設定を references/client-configs.md から取得
6. CBF 品質ゲートで設計レビュー
7. PCC パイプラインで品質記録

ファイル構成

.agents/skills/mcp-mastery/
├── SKILL.md                        ← ここ
├── references/
│   ├── design-patterns.md          ← 8サーバー設計パターン
│   ├── stack-reference.md          ← Ryota スタック仕様
│   └── client-configs.md           ← クライアント接続設定
└── examples/
    └── minimal-server.py           ← 最小実装例

name: mcp-mastery version: 1.0.0