DevTools MCP

MCP をサーバー実装からローカルテスト、既存 MCP の利用、パブリックデプロイ、Smithery への公開までエンドツーエンドで学ぶために作った、小規模な開発者向けユーティリティ MCP サーバーです。

1. 概要

DevTools MCP は、Model Context Protocol 上で 4 つの小規模な開発者向けツールを公開します。エラーメッセージの説明、JSON の検証・整形、説明文からの正規表現生成、LLM（Groq）によるテキスト要約です。最小限の TypeScript/Vite 製ダッシュボードにより、実際の MCP クライアントとして接続し、ブラウザからこれらのツールを実行できます。

Related MCP server: ai-assistant

2. なぜ MCP か

MCP は、LLM ホスト（Claude Desktop、IDE、エージェント）がツールを発見して呼び出す方法を標準化します。個々のプロジェクトが独自の tool-calling API を発明する必要はありません。MCP とラベルを貼っただけの REST API ではなく、実際の MCP サーバーを構築することが、このプロジェクトの主な学習目標でした。

3. アーキテクチャ

MCP Client
    |
MCP Protocol
    |
DevTools MCP Server
    |-- explain_error    (local/deterministic)
    |-- format_json      (local/deterministic)
    |-- generate_regex   (local/deterministic)
    `-- summarize_text
            |
        Groq API
            |
        GPT-OSS 120B

サーバー (server/server.py) は mcp.server.MCPServer（MCP Python SDK v2）です。ローカルテストでは stdio 経由で実行され（MCP Inspector、Client(mcp)）、リモート・ブラウザアクセスには Streamable HTTP（/mcp）経由で実行されます。TypeScript フロントエンド (frontend/) は本物の MCP クライアントです。@modelcontextprotocol/sdk の Client と StreamableHTTPClientTransport を使い、手作りの REST ブリッジではなく、Streamable HTTP（サーバー側で CORS 有効）経由で直接サーバーと通信します。

4. ツール

5. プロジェクト構造

devtools-mcp/
├── server/
│   ├── server.py               # MCPServer + tool registration + ASGI app
│   ├── tools.py                # explain_error / format_json / generate_regex logic
│   ├── ai.py                   # Groq-backed summarize_text logic
│   └── tests/
│       └── test_server.py      # pytest suite using the SDK's in-memory Client
├── frontend/
│   ├── index.html
│   ├── src/
│   │   ├── main.ts             # real MCP client (StreamableHTTPClientTransport)
│   │   └── style.css
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
├── .env.example
├── .gitignore
├── requirements.txt
├── render.yaml                 # optional Render Blueprint
├── README.md
└── EXISTING_MCP_EXPERIENCE.md

6. 前提条件

• Python 3.10+

• Node.js 18+ と npm（フロントエンド用 npx で MCP Inspector を実行するため）

• A Groq API キー（summarize_text にのみ必要）

• （デプロイ時のオプション）Render アカウントと Smithery アカウント

7. インストール

git clone <this-repo>
cd devtools-mcp
python3 -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

8. 環境変数

.env.example を .env にコピーし、必要なものを記入してください:

GROQ_API_KEY=            # required for summarize_text
GROQ_MODEL=openai/gpt-oss-120b
MCP_ALLOWED_HOSTS=        # only needed when deployed behind a real hostname
MCP_ALLOWED_ORIGINS=      # comma-separated browser origins allowed via CORS

.env は gitignore されています。実際の機密情報をコミットしないでください。

9. ローカルセットアップ

Stdio（デフォルト。ローカル MCP クライアント用）:

python -m server.server

Streamable HTTP（フロントエンドや HTTP ベースの任意の MCP クライアント用。ローカルのみ）:

uvicorn server.server:app --host 127.0.0.1 --port 8000

MCP_ALLOWED_HOSTS はローカルでは未設定のままで構いません。SDK 組み込みの localhost 限定 DNS リバインディング保護によって、127.0.0.1/localhost は自動的にカバーされます。ヘルスチェック: curl http://127.0.0.1:8000/health。

10. MCP Inspector テスト

# Against stdio:
uv run mcp dev server/server.py     # requires uv; or: npx @modelcontextprotocol/inspector
# Against a running Streamable HTTP server:
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list

これは開発時にローカルの Streamable HTTP サーバーに対して実行され、4 つのツールすべてが正しい入出力スキーマで検出可能であることを確認しました（正確な結果については、下記の「テスト」を参照）。

11. フロントエンドのセットアップ

cd frontend
npm install
npm run dev          # http://localhost:5173

実行中のダッシュボードで、サーバー URL フィールドに MCP サーバーの /mcp エンドポイント（デフォルトでは http://localhost:8000/mcp）を設定し、Connect をクリックします。ツールを選択し、フォームに入力して Run をクリックします。ローカルで使用するには、バックグラウンドを MCP_ALLOWED_ORIGINS=http://localhost:5173 で起動して、CORS を許可します。

本番ビルド: npm run build（出力先は frontend/dist/）

12. Groq のセットアップ

1. console.groq.com で API キーを作成します。

2. .env か、デプロイプラットフォームの環境変数に GROQ_API_KEY を設定します（必要に応じて GROQ_MODEL も。デフォルトは、openai/gpt-oss-120b）。

3. このプロジェクトで使用している LLM プロバイダーは他にありません。

13. 既存 MCP の利用

既存の MCP サーバー（Context7）を使うデモについては、EXISTING_MCP_EXPERIENCE.md を参照してください。それが何か、どのように接続したか、実行した実際のクエリ、学んだことを記載しています。

14. Render へのデプロイ

Render のネイティブ Python ランタイムを使用しています（Docker は不要）。

ダッシュボード設定:

1. このリポジトリを GitHub にプッシュします。

2. Render で: New → Web Service → リポジトリを接続します。

3. ランタイム: Python 3。ビルドコマンド: pip install -r requirements.txt。開始するコマンド: uvicorn server.server:app --host 0.0.0.0 --port $PORT。

4. 環境変数を設定します: GROQ_API_KEY、GROQ_MODEL、MCP_ALLOWED_HOSTS=<your-service>.onrender.com,<your-service>.onrender.com:*、MCP_ALLOWED_ORIGINS=<your-frontend-origin>（フロントエンドもデプロイする場合）。

5. デプロイします。MCP エンドポイントは https://<your-service>.onrender.com/mcp になります。

同じセットアップを簡単にするために、render.yaml Blueprint も同梱しています。

手動確認が必須の手順: 実際にデプロイするには Render アカウントが必要ですが、この対応の一環としては実行されていません。手動手順として残る詳細は完了レポートを参照してください。

15. Smithery での公開

現在の Smithery CLI は、ホストされているリモート MCP サーバーの URL を直接公開できます（この経路では Docker/コンテナのパッケージングは不要です）:

npm install -g smithery
smithery auth login
smithery mcp publish "https://<your-service>.onrender.com/mcp" -n "<your-org>/devtools-mcp"

公開後、4 つのツールが露出していることを確認します:

smithery mcp add "https://<your-service>.onrender.com/mcp" --id devtools-mcp
smithery tool list devtools-mcp

手動手順が必要です: 先に Smithery アカウントと、公開可能な Render デプロイが必要です。これはこの対応の一部としては実行されていません。

16. パブリック MCP 利用

デプロイ後は、任意の Streamable HTTP MCP クライアントで次の場所に接続できます:

https://<your-service>.onrender.com/mcp

SDK の Client を使った例:

from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async with streamable_http_client("https://<your-service>.onrender.com/mcp") as (r, w, _):
    async with Client(r, w) as client:
        await client.initialize()
        print(await client.list_tools())

17. テスト

この環境で実際に実行:

pytest server/tests/ -v

結果: 11 passed - ツール検出、format_json の有効・不正・空の入力、explain_error のパターン一致・不正一致（空の入力含む）、既知のパターンに対する generate_regex（実際の正規表現一致チェックを含む）と未一致の説明、GROQ_API_KEY がない場合の summarize_text、空の入力。

また、（pytest 以外、手動で）実際に実行:

• uvicorn server.server:app は正常に起動し、/health は {"status":"ok",...} を返しました。

• /mcp の生の initialize という name の JSON-RPC POST が 200 を返しました。

• 実際の MCP Inspector CLI（npx @modelcontextprotocol/inspector --cli）が Streamable HTTP 経由で接続し、4 つのツールを正しいスキーマで列挙し、generate_regex、explain_error、format_json（JSON の有効・無効の両方）、summarize_text（この環境では実際の Groq キーがなかったため、不足中の API キーエラーを正しく報告）を正常に呼び出しました。

• トランスポートのセキュリティ: 偽装した X-Forwarded-Proto 付けない Host で、期待通り 421 Misdirected エラーを受け取ることを確認。

• CORS プリフライト: MCP_ALLOWED_ORIGINS を有効にした後、Origin: http://localhost:5173 を持つ元の /mcp への OPTIONS リクエストが 200 と正しい access-control-* をヘッダーで返した。

• フロントエンド: npx tsc --noEmit がエラーなしでき、npm run build が成功し frontend/dist/ を生成しました。

未検証 (この環境には存在しない外部アカウント・認証が必要): 実 Groq API キー を使った実地の summarize_text 呼び出し、Render デプロイ自体、Smithery の公開・一覧表示。

18. 制限

• summarize_text は短くて、エラーのある旨のパスだけがエンドツーエンドでテストされました。実際の Groq 資格情報では呼び出されていません。

• Render デプロイと Smithery 公開は、ご自身のアカウントでの手動手順が必要で（セクション14〜15参照）、この対応では実行されていません。

• explain_error と generate_regex は、LLM ではなく小規模な手書きのパターン・ライブラリを使います。意図的にシンプルで決定的な内容になっているため、あらゆるエラーやパターン記述を認識できるわけではありません。

• フロントエンドには認証がありません。このプロジェクトで明示的に「アカウントなし・認証なし」という範囲にしているため、ローカル・デモ用です。

6. 学習内容

• MCP とは何か: 標準化されたプロトコルで、「LLM にコンテキスト／アクションを提供すること」と「LLM 本体のやりとり」を分離します。そのため、一度作成したサーバーは（このしれたい）、対応している任意のクライアントで問題なく動きます。

• ホスト / クライアント / サーバー: ホストは LLM アプリ（Claude ・デスクトップ、ブラウザーのダッシュボードの背後にあるアプリ）、クライアントはその中にある MCP を話す部分（SDK の Client、当社のフロントエンドの StreamableHTTPClientTransport ベースのクライアント）、サーバーは私たちが構築したものです。サーバーはモデルに直接話しかけません。

• ツール vs リソース vs プロンプト: ツールはモデルが操作する内容（LLM が format_json を呼ぶかどうか）; リソースはアプリが投入するデータ; プロンプトはユーザーが呼び出すテンプレート。このプロジェクトに必要なのはツールだけ。

• ツール発見と起動: クライアントは tools/list 使って利用できる内容（名前、説明、JSON スキーマの入出力、すべて便利なタイプヒントと docstring から自動生成される）を学習し、次に tools/call を使い、名前と引数を指定してツールを起動します。

• MCP vs プレーンな REST API: REST API はクライアントごとに個別の統合が必要です。MCP サーバーは自分自身のは、機能とスキーマを説明するので、MCP 対応ホストならカスタムのグルー・コードなしで使えます。サーバー側の変更なしで、同じサーバーを MCP Inspector と、自作フロントエンド・クライアントの両方につなぐことで実証されています。

• LLMが使われる部分はどこか: それは summarize_text だけです。Groq を呼び出します。サーバーの他の部分は平易きな決定論コードで、これは「MCP サーバー」と「AI アプリケーション」が同じものではないという、役立つ気付きです。

• デプロイの現実: Streamable HTTP サーバーは、既定では localhost だけに ホスト/IP 許可を制限しています。実ホストネームで運用する場合は、明示的に開ける（TransportSecuritySettings）必要があります。この環境で実際に 421 を発生させ、手を動かして確認しました。