nyosegawa/mcp-light-generator

MCP Light Generator

MCPサーバーのツール定義(description)を分析し、「判断用1行サマリー」と「実行時ベストプラクティス」に分離する。出力は2つ: Light版MCPサーバー(FastMCP proxy) + ベストプラクティスSkill。

背景

MCPツールのdescriptionには2種類の情報が混在している:

• 判断用情報: 「Notionにページを作成する」— ツールを使うかの判断に必要。1行で済む
• 実行時ベストプラクティス: 「data_source_idを使え」「先にfetchしろ」— 実際にツールを使う瞬間まで不要

MCP Lightはこれを分離し、前者をLight版MCPサーバーのdescriptionに、後者をAgent Skillに外出しする。

手順

Step 1: 対象MCPサーバーの特定

ユーザーにMCPサーバー名を確認する。例:

• @notionhq/notion-mcp-server
• @anthropic/github-mcp-server
• カスタムMCPサーバー

Step 2: ツール定義の収集

ToolSearch を使って対象MCPサーバーの全ツールをロードする。

ToolSearch: "+{server-prefix}" で全ツールを検索

各ツールの以下を記録する:

• name: ツール名
• description: 元のdescription全文
• inputSchema: パラメータスキーマ（変更しない）

Step 3: description の分離

各ツールのdescriptionを分析し、2つに分離する。

3a. Light版サマリー（1-2行）

以下のルールで圧縮する:

• 何をするかを1文で書く（英語、動詞始まり）
• 末尾に See {server}-best-practices skill for usage details. を付ける
• inputSchemaの情報は含めない（スキーマ自体が残るため）
• 例: Create Notion pages in a database or standalone. See notion-best-practices skill for usage details.

3b. ベストプラクティス（Skill用）

元のdescriptionから以下を抽出する:

• パラメータの制約・特殊形式（日付形式、特殊プレフィックスなど）
• 推奨ワークフロー（「先にfetchしてからcreateする」など）
• エラー回避のコツ
• 具体的な使用例

Step 4: 出力ファイルの生成

出力先ディレクトリをユーザーに確認し、以下の構造で生成する。 references/fastmcp-proxy-pattern.md を参照してFastMCPプロキシのコードパターンを確認する。

{server-name}-light/
├── mcp/
│   ├── server.py          # FastMCP proxyサーバー
│   └── pyproject.toml     # パッケージ定義
└── skill/
    └── {server-name}-best-practices/
        └── SKILL.md        # ベストプラクティスSkill

server.py の構造

from fastmcp import FastMCP
from fastmcp.server.proxy import ProxyClient

LIGHT_DESCRIPTIONS = {
    "tool-name": "1-line summary. See {server}-best-practices skill for usage details.",
    # ... 全ツール分
}

proxy_client = ProxyClient("npx @original/mcp-server")
server = FastMCP.as_proxy(proxy_client, name="{server-name}-light")

for tool in server.list_tools():
    if tool.name in LIGHT_DESCRIPTIONS:
        tool.description = LIGHT_DESCRIPTIONS[tool.name]

SKILL.md の構造

---
name: {server-name}-best-practices
description: Best practices for {Server Name} MCP tools. Auto-loaded when using {server-name}-light MCP server. Contains parameter formats, recommended workflows, and error prevention tips.
---

# {Server Name} Best Practices

## 共通ルール
[全ツール共通のルール・制約]

## {tool-name-1}
[ツール固有のベストプラクティス]

## {tool-name-2}
...

Step 5: トークン削減レポート

圧縮前後のトークン数を概算し、レポートを出力する。

## トークン削減レポート

| ツール名 | 元のdescription | Light版 | 削減率 |
|---|---|---|---|
| tool-1 | ~500 tokens | ~20 tokens | 96% |
| ... | ... | ... | ... |

### サマリー
- 元のdescription合計: ~X tokens
- Light版description合計: ~Y tokens
- inputSchema（不変）: ~Z tokens
- description単体の削減率: XX%
- 常時コンテキストの削減率: XX%（description + schema 基準）

トークン数は「英語1単語 ≈ 1.3 tokens、1文字（日本語）≈ 2-3 tokens」で概算する。正確な計測が必要な場合はtiktokenを使用する。

Step 6: インストール手順の提示

生成が完了したら、以下のインストール手順を提示する:

# 1. Light版MCPサーバーをインストール
pip install -e ./{server-name}-light/mcp/

# 2. Claude CodeにMCPサーバーを追加
claude mcp add {server-name}-light -- python -m {server_name}_light

# 3. ベストプラクティスSkillを配置
cp -r ./{server-name}-light/skill/{server-name}-best-practices/ ~/.claude/skills/

# 4. 元のMCPサーバーを無効化（任意）
claude mcp remove {original-server-name}

重要なルール

• inputSchemaは絶対に変更しない — パラメータ構造はそのまま保持する
• 情報は捨てない — descriptionから取り除いた情報は全てSkillに移す
• ツール名は変えない — 元のMCPサーバーと同じツール名を使う
• 共通ルールを抽出する — 複数ツールに共通するパターン（日付形式など）は共通セクションにまとめる