Coding Guides MCP Server

AIアシスタント（ClaudeやGitHub Copilotなど）向けに、コーディングガイドとベストプラクティスへのアクセスを提供するModel Context Protocol（MCP）サーバーです。

これは何か？

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

Related MCP server: Code Understanding MCP Server

特徴

• リソースベースのAPI: コーディングガイドをMCPリソースとして公開

• GitHub連携: ウェブ上の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）

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

• 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環境変数が存在する場合（Cloud Runが常に注入）はStreamable HTTPに切り替わります。別のイメージやエントリポイントは不要です。

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を有効にしたままにすると、ガイドごとにネットワークの往復が発生し、認証なしのGitHub API制限（egress IPあたり60リクエスト/時間）に達すると、サーバーは静かに同じ組み込みファイルにフォールバックします。

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を前面に配置してください。

• GUIDES_STATELESS_HTTPは、セッションアフィニティを有効にしない限りtrueのままにする必要があります。Cloud Runはセッションのリクエストを異なるインスタンスにルーティングする可能性があるためです。

• GET /は設計上404を返します。/mcpのみが提供されます。Cloud Runのデフォルトのスタートアッププローブは$PORTへのTCPチェックであるため、これは問題ありません — /へのHTTPヘルスチェックを設定しないでください。

• カスタムドメインでサービスを公開する場合は、GUIDES_ALLOWED_HOSTSをサービスホスト名に設定して、Hostヘッダー検証を有効にしてください。

MCPレジストリへの公開

VS Code拡張機能ビューのMCPサーバー一覧（検索バーに@mcpと入力）は、公式のMCPレジストリから取り込むGitHub MCPレジストリによって供給されています。したがって、そこに公開することは、このサーバーが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のキュレーションリストへの掲載にはpartnerships@github.comへのリクエストが必要な場合があります。

ガイドの追加

GitHubを使用（推奨）

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

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

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

例：

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

MCPクライアントでの使用

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

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

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

デプロイされたインスタンスは/mcpでMCPエンドポイントを公開します。以下のスニペットは参照デプロイを使用しています：

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

これは公開されており、認証情報は不要です。自分でサービスを実行する場合は、独自のURLに置き換えてください — リモートデプロイを参照してください。

VS Code — ワークスペースごとの.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 — 設定でカスタムコネクタとして追加するか、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またはプルリクエストを開いてください。