Coding Guides

Coding Guides MCP Server

Claude や GitHub Copilot などの AI アシスタントがコーディングガイドやベストプラクティスを利用できるようにする Model Context Protocol（MCP）サーバーです。

これは何ですか？

この MCP サーバーは、コーディングガイドラインやスタイルガイドを、MCP クライアントからアクセスできるリソースとして公開します。開発中に AI アシスタントへコーディングのプラクティスやガイドラインを提供する、構造化された方法として、AGENTS.md ファイルを拡張または置き換えることを目的としています。

機能

• リソースベースの API：コーディングガイドを MCP リソース経由で公開します
• GitHub 連携：Web 経由で GitHub リポジトリからガイドを読み込みます
• 自動キャッシュ：ダウンロードしたガイドをオフラインで利用できるよう、ローカルにキャッシュします
• フォールバック対応：ネットワークが利用できない場合は、ローカルキャッシュまたはディレクトリを使用します
• シンプルなファイルベースのストレージ：ガイドは Markdown ファイルとしてローカルに保存できます
• 公式 MCP SDK：Python の mcp SDK（MCPServer、旧 FastMCP）を基盤としています
• 簡単な統合：MCP 互換クライアント（Claude Desktop、Cline など）で動作します

利用可能なリソース

• guides://list - 利用可能なコーディングガイドをすべて一覧表示します
• guides://{guide_name} - 指定したガイドの内容を取得します（例：guides://python.md）

インストール

ソースから

# Clone the repository
git clone https://github.com/delian/codeguide-mcp.git
cd codeguide-mcp

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

Docker を使用

docker build -t codeguide-mcp .
docker run -i codeguide-mcp

VS Code で

または、拡張機能ビューの MCP サーバー一覧で codeguide-mcp を検索する（拡張機能の検索バーに @mcp と入力する）か、.vscode/mcp.json に手動で追加します。

{
  "servers": {
    "codeguide-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "delian/codeguide-mcp"]
    }
  }
}

設定

config.toml ファイルを作成するか、環境変数を設定してサーバーを構成します。

GitHub の設定（推奨）

GitHub リポジトリからガイドを読み込む場合：

github_repo = "owner/repository"  # e.g., "delian/codeguide-mcp"
github_path = "guides"            # Path to guides directory in repo
github_branch = "main"            # Branch to fetch from
  cache_dir = ".guides-cache"       # Local cache directory
log_level = "INFO"

ローカルディレクトリの設定

ローカルのガイドのみを使用する場合：

guides_dir = "guides"
log_level = "INFO"

環境変数

• GUIDES_GITHUB_REPO - GitHub リポジトリ（形式：owner/repo）
• GUIDES_GITHUB_PATH - リポジトリ内のガイドディレクトリのパス（デフォルト：guides）
• GUIDES_GITHUB_BRANCH - 取得元のブランチ（デフォルト：main）
• GUIDES_CACHE_DIR - ローカルキャッシュディレクトリ（デフォルト：.guides-cache）
• GUIDES_DIR - ガイドファイルを格納するローカルディレクトリ（デフォルト：guides）
• GUIDES_LOG_LEVEL - ログレベル（デフォルト：INFO）

トランスポート（リモートデプロイ（Google Cloud Run）を参照）：

• GUIDES_TRANSPORT - stdio、streamable-http、または auto（デフォルト：auto — PORT 環境変数がある場合は HTTP、それ以外は stdio）
• PORT - HTTP モードでリッスンするポート。GUIDES_PORT より優先されます（Cloud Run が注入します）
• GUIDES_HOST - HTTP モードのバインドアドレス（デフォルト：0.0.0.0）
• GUIDES_HTTP_PATH - MCP エンドポイントのパス（デフォルト：/mcp）
• GUIDES_STATELESS_HTTP - 各リクエストを独立して処理します（デフォルト：true。レプリカの自動スケーリング時に必須です）
• GUIDES_ALLOWED_HOSTS - DNS リバインディング保護を有効にする Host ヘッダーの許可リスト（デフォルト：空 = Host の検証なし）

動作

1. ネットワーク利用可能 + GitHub 設定済み：GitHub からガイドを取得し、ローカルにキャッシュします
2. ネットワーク利用不可：利用可能な場合はローカルキャッシュを使用します
3. キャッシュ利用不可：設定されている場合はローカルの guides_dir にフォールバックします

リモートデプロイ（Google Cloud Run）

同じイメージで両方のトランスポートに対応します。デフォルトではパイプ経由で stdio を使用し、PORT 環境変数がある場合は Streamable HTTP に切り替わります。Cloud Run は常にこの変数を注入します。別のイメージやエントリポイントは不要です。

1. イメージを公開する

docker build -t delian/codeguide-mcp:0.1.0 -t delian/codeguide-mcp:latest .
docker push delian/codeguide-mcp:0.1.0
docker push delian/codeguide-mcp:latest

2. デプロイ

gcloud run deploy codeguide-mcp \
  --image=docker.io/delian/codeguide-mcp:0.1.0 \
  --region=europe-west1 \
  --allow-unauthenticated \
  --port=8080 \
  --set-env-vars=GUIDES_TRANSPORT=streamable-http,GUIDES_GITHUB_REPO= \
  --memory=512Mi --cpu=1 \
  --min-instances=0 --max-instances=4 --concurrency=40

GUIDES_GITHUB_REPO=（空）にすると、サービスはイメージに組み込まれたガイドを提供します。GitHub を有効にしたままにすると、ガイドごとにネットワークへの往復が発生し、送信元 IP あたり毎時 60 リクエストという、認証されていない GitHub API の制限に達します。その後、サーバーは同じ組み込みファイルに黙ってフォールバックします。

MCP エンドポイントは https://<service-url>/mcp です。

gcloud run services describe codeguide-mcp --region=europe-west1 \
  --format='value(status.url)'

Cloud Run は、同じサービスに対して 2 つのホスト名で応答します。gcloud run deploy が出力する SERVICE-PROJECTNUMBER.REGION.run.app 形式と、status.url が報告する旧形式の SERVICE-HASH-REGIONCODE.a.run.app です。どちらも同等で、クライアント設定ではどちらを使ってもかまいません。

3. クライアントを接続する

クライアントごとの設定については、以下のリモートサーバーへの接続を参照してください。

Docker Hub からの取得

Cloud Run は Docker Hub のパブリックイメージを直接デプロイできますが、キャッシュは 1 時間だけで、その後は匿名で再取得します。そのため、スケールアップ時に Docker Hub の匿名取得制限に達し、インスタンスの起動に失敗することがあります。気軽に使う範囲を超えて利用する場合は、Artifact Registry のリモートリポジトリを経由してミラーリングしてください。

gcloud artifacts repositories create dockerhub \
  --repository-format=docker --location=europe-west1 \
  --mode=remote-repository --remote-docker-repo=DOCKER-HUB

gcloud run deploy codeguide-mcp \
  --image=europe-west1-docker.pkg.dev/PROJECT_ID/dockerhub/delian/codeguide-mcp:0.1.0 \
  ...

公開して実行する際の注意事項

• --allow-unauthenticated を指定すると、エンドポイントは誰でも呼び出せるようになります。サーバーは読み取り専用ですが、clear_cache プロンプトは誰でも利用でき、メモリ内キャッシュを削除します。また、トラフィックによってオートスケーリングのコストが発生するため、--max-instances に上限を設定してください。アクセスを制限するには、このフラグを省略してクライアントから ID トークンを送信するか、Cloud Armor / API Gateway をサービスの前段に配置してください。
• Cloud Run がセッションのリクエストを異なるインスタンスにルーティングする可能性があるため、セッションアフィニティも有効にしない限り、GUIDES_STATELESS_HTTP は true のままにしてください。
• GET / は仕様上 404 を返し、サービスが提供するのは /mcp のみです。Cloud Run のデフォルトの起動プローブは $PORT に対する TCP チェックなので、これで問題ありません。/ に対する HTTP ヘルスチェックは設定しないでください。
• カスタムドメインでサービスを公開する場合は、GUIDES_ALLOWED_HOSTS にサービスのホスト名を設定し、Host ヘッダーの検証を有効にしてください。

MCP Registry への公開

VS Code の拡張機能ビューにある MCP サーバーの一覧（検索バーに @mcp と入力）には、公式の MCP Registry から取り込まれる GitHub MCP Registry の情報が表示されます。そのため、このサーバーを VS Code で見つけられるようにするには、ここで公開します。独自の VS Code 拡張機能は必要ありません。

server.json にはレジストリのメタデータが記載されています。ローカルで実行したいクライアント向けの Docker イメージと、ローカルでの実行を希望しないクライアント向けのホスト URL です。イメージの所有権は、Dockerfile の io.modelcontextprotocol.server.name ラベルで証明されます。その値は server.json の .name と一致している必要があります。

一度認証（デバイスコードを使った対話型フロー）してから、公開スクリプトを実行します。

mcp-publisher login github     # namespace io.github.<your-username>/*
tools/publish.sh

tools/publish.sh はリリースに必要な処理をすべて実行します。必要なツールと Docker へのログインを確認し、server.json と pyproject.toml のバージョンが一致していること、および Dockerfile のラベルがサーバー名と一致していることを検証します。次に :VERSION と :latest をビルドしてプッシュし、server.json をライブレジストリに対して検証してから公開し、最後にエントリーを読み戻して確認します。

tools/publish.sh --dry-run          # everything except push and publish
tools/publish.sh --version 0.2.0    # bump server.json + pyproject + image tag, then release
tools/publish.sh --skip-build       # reuse images already on Docker Hub

お持ちでない場合は、レジストリのクイックスタートから mcp-publisher をインストールしてください。公開後、GitHub の厳選リストに掲載するには、[email protected] への申請が必要になる場合があります。

ガイドの追加

GitHub を使用する（推奨）

github_repo を設定している場合は、GitHub リポジトリ内の指定ディレクトリに Markdown ファイルを追加してください。サーバーが自動的に取得してキャッシュします。

ローカルディレクトリを使用する

guides/ ディレクトリに Markdown ファイルを追加してください。各ファイルは自動的にリソースとして利用可能になります。

例：

echo "# Python Style Guide\n\nUse PEP 8..." > guides/python.md

MCP クライアントでの使用方法

サーバーは次の 2 つの方法で利用できます。

モード	トランスポート	クライアントからの接続方法
ローカル	stdio	クライアントが python main.py または docker run -i を起動し、パイプ経由で通信します
リモート	Streamable HTTP	クライアントがホストされた …/mcp URL に HTTPS リクエストを送信します

ローカルモードではネットワークもホスティングも不要です。リモートモードではチームで 1 つのデプロイを共有でき、全員が同じガイドを利用できます。

リモートサーバーへの接続

デプロイしたインスタンスは、MCP エンドポイントを /mcp で公開します。以下の例では、リファレンスデプロイを使用しています。

https://codeguide-mcp-86057491046.europe-west1.run.app/mcp

このエンドポイントは公開されており、認証情報は不要です。サービスを自分で実行する場合は、独自の URL に置き換えてください。詳しくはリモートデプロイ（Google Cloud Run）をご覧ください。

VS Code — 1 つのワークスペースでは .vscode/mcp.json を、すべてのワークスペースではユーザーの mcp.json を使用します。

{
  "servers": {
    "codeguide-mcp": {
      "type": "http",
      "url": "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"
    }
  }
}

Claude Code：

claude mcp add --transport http codeguide-mcp \
  https://codeguide-mcp-86057491046.europe-west1.run.app/mcp

Cursor — ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）を使用します。

{
  "mcpServers": {
    "codeguide-mcp": {
      "url": "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"
    }
  }
}

Claude Desktop — Settings でカスタムコネクターとして追加するか、 mcp-remote を使ってリモートエンドポイントを stdio クライアントにブリッジします。

{
  "mcpServers": {
    "codeguide-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"]
    }
  }
}

任意のクライアントで Streamable HTTP を使用できます。/mcp URL を指定してください。 認証が必要なサーバーの場合は、トークンを --header "Authorization: Bearer $(gcloud auth print-identity-token)" （Claude Code の場合）またはクライアントの同等の headers ブロックで渡します。

リモートエンドポイントの確認

単一の curl コマンドで、デプロイが稼働中かつ公開されていることを確認できます。

curl -s -X POST https://codeguide-mcp-86057491046.europe-west1.run.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
       "protocolVersion":"2025-06-18","capabilities":{},
       "clientInfo":{"name":"curl","version":"1"}}}'

正常なサーバーは、機能と指示を含む SSE の event: message フレームを返します。GET / は仕様上 404 を返します。提供されるのは /mcp のみです。

代わりに、すべてのリソース、ツール、プロンプトを HTTP 経由で試すには、次のようにします。

uv run python verify_server.py --http https://codeguide-mcp-86057491046.europe-west1.run.app/mcp

ローカルでの使用方法

Claude Desktop

mcp.json に追加します。

{
  "mcpServers": {
    "coding-guides": {
      "command": "python",
      "args": ["-m", "main"]
    }
  }
}

または

{
  "mcpServers": {
    "coding-guides": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "docker.io/delian/codeguide-mcp"]
    }
  }
}

その他の MCP クライアント

サーバーを実行し、stdio 経由で接続します。

python main.py

開発

# Install development dependencies
uv pip install -e ".[dev]"

# Run pre-commit hooks
pre-commit install
pre-commit run --all-files

# Run the server
python main.py

ライセンス

MIT

コントリビューション

コントリビューションを歓迎します。Issue またはプルリクエストを作成してください。