Coding Guides MCP 服务器

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

这是什么？

此 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 重绑定保护（默认：空 = 不进行主机验证）

行为

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 启用会增加每个指南的网络往返，并可能达到未认证的 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 设置为您的服务主机名，以启用主机头验证。

发布到 MCP 注册表

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

使用本地目录

将 Markdown 文件添加到 guides/ 目录。每个文件将自动作为资源可用。

示例：

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

与 MCP 客户端一起使用

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

本地模式无需网络和托管；远程模式允许团队共享一个部署，并保持指南对所有人一致。

连接到远程服务器

已部署的实例在 /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 或 pull request。