---
name: mcp-mastery
description: MCP サーバーの設計・実装・統合・運用・進化を包括するスキル。「MCPサーバー作って」「MCPツール追加して」「MCP接続設定して」「MCPサーバーのレビュー」「新しいMCPサーバー設計」「MCP レジストリ更新」と言われたら必ず使う。FastMCP (Python) + Granian + uv + structlog の Ryota スタック固定。マルチクライアント接続（Antigravity/Codex/ChatGPT/Gemini CLI/OpenClaw/Aladdin/n8n）と AI ロール別アクセス制御をサポート。
---

# 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つに分類する:

| 要素 | 用途 | 例 |
|------|------|-----|
| **Resources** | 読み取り専用データ (URI + MIME type) | `repo://status`, `db://schema/tables` |
| **Tools** | 操作を実行する関数 (スキーマ化 I/O) | `db_query()`, `deploy_trigger()` |
| **Prompts** | 再利用可能な指示テンプレート | `explain_error`, `summarize_logs` |

### ツール設計原則

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`](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 依存関係
```

### 実装パターン

#### サーバー初期化

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

#### Envelope ヘルパー

```python
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 に抑えるため、重いモジュールは初回アクセス時にロード:

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

#### ツール登録

```python
@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`](references/stack-reference.md)
→ ゴールデンサンプル: `ryota_ops_mcp_server.py` (37ツール)

---

## Layer 3: 統合 (Integration)

### 接続方式

| 方式 | 用途 | 設定 |
|------|------|------|
| **stdio** | ローカル接続 (Antigravity, Codex) | `command` + `args` |
| **HTTP** | リモート接続 (n8n, 外部ツール) | `mcp_http_gateway.py` + ngrok |
| **SSE** | クラウドサービス接続 | `type: "sse"` + `url` |
| **WebSocket** | リアルタイム双方向 | `type: "ws"` + `url` |

### マルチクライアント接続

各クライアントの接続テンプレートは `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` で一元管理:

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

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

→ 詳細: [`references/client-configs.md`](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` テーブルに記録:

```python
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` 末尾の表に追記し、次回の制約として自動注入:

| 日付 | AI | 失敗内容 | 学んだルール |
|------|-----|---------|------------|
| 2026-02-27 | Gemini CLI | 3並行でレート制限 | 2並行まで |
| 2026-02-27 | Codex | .git/index.lock 拒否 | コミットは人間 or Antigravity |

---

## 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
---