Coding Guides

编码指南 MCP 服务

一个模型上下文协议（MCP）服务，可为 Claude 和 GitHub Copilot 等 AI 助手提供编码指南和最佳实践。

这是什么？

此 MCP 服务将编码规范和风格指南作为资源公开，供 MCP 客户端访问。它旨在通过结构化的方式，在开发过程中向 AI 助手提供编码实践和指南，从而扩展或替代 AGENTS.md 文件。

功能

• 基于资源的 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，则回退到本地 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 会使每份指南都增加一次网络往返，并受到未经身份验证的 GitHub API 每个出口 IP 每小时 60 次请求的限制；达到限制后，服务会静默回退到同一批内置文件。

此时 MCP 端点为 https://<service-url>/mcp：

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

Cloud Run 会为同一服务提供两个主机名——gcloud run deploy 打印的 SERVICE-PROJECTNUMBER.REGION.run.app 形式，以及 status.url 报告的旧版 SERVICE-HASH-REGIONCODE.a.run.app 形式。两者等效，在客户端配置中任选其一即可。

3. 配置客户端连接

各客户端的配置请参阅下文的连接到远程服务。

从 Docker Hub 拉取

Cloud Run 可以直接部署 Docker Hub 上的公开镜像，但只会缓存一小时，之后会匿名重新拉取。因此，扩容时可能触及 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 上限。若要限制访问，请省略此标志并让客户端发送身份令牌，或在服务前部署 Cloud Armor / API Gateway。
• 除非同时启用会话亲和性，否则必须保持 GUIDES_STATELESS_HTTP 为 true，因为 Cloud Run 可能会将同一会话的请求路由到不同实例。
• 按设计，GET / 会返回 404；服务仅提供 /mcp。Cloud Run 的默认启动探测是在 $PORT 上进行 TCP 检查，因此没有问题——请勿将 HTTP 健康检查配置到 /。
• 如果将服务公开在自定义域名下，请将服务主机名设置为 GUIDES_ALLOWED_HOSTS，以启用 Host 标头验证。

发布到 MCP Registry

VS Code 扩展视图中的 MCP 服务列表（在搜索栏输入 @mcp）由 GitHub MCP Registry 提供数据，该注册表从官方 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，只需将 Markdown 文件添加到 GitHub 仓库中指定的目录。服务会自动获取并缓存这些文件。

使用本地目录

将 Markdown 文件添加到 guides/ 目录。每个文件都会自动作为资源提供。

示例：

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

在 MCP 客户端中使用

可以通过两种方式使用此服务：

模式	传输方式	客户端如何连接
本地	stdio	客户端启动 python main.py 或 docker run -i，并通过管道通信
远程	Streamable HTTP	客户端向托管的 …/mcp URL 发送 HTTPS 请求

本地模式无需联网或托管；远程模式便于团队共享同一个部署，并确保所有人的指南一致。

连接远程服务

部署后的实例会在 /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 或拉取请求。