Сервер MCP «Coding Guides»

Сервер Model Context Protocol (MCP), предоставляющий доступ к руководствам по написанию кода и лучшим практикам для ИИ-ассистентов, таких как Claude и GitHub Copilot.

Что это?

Этот MCP-сервер предоставляет руководства по написанию кода и стилевые руководства в виде ресурсов, к которым могут обращаться MCP-клиенты. Он предназначен для расширения или замены файлов AGENTS.md, предоставляя структурированный способ передачи практик и рекомендаций по коду ИИ-ассистентам во время разработки.

Related MCP server: Code Understanding MCP Server

Возможности

• API на основе ресурсов: предоставляет руководства по коду через ресурсы MCP

• Интеграция с GitHub: загружает руководства из репозиториев GitHub через интернет

• Автоматическое кэширование: кэширует загруженные руководства локально для офлайн-доступа

• Поддержка резервного режима: использует локальный кэш или каталог, когда сеть недоступна

• Простое хранение в файлах: руководства могут храниться локально в виде файлов Markdown

• Официальный MCP SDK: построен на Python-пакете mcp (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

Или найдите codeguide-mcp в списке 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 — HTTP при наличии переменной окружения PORT, иначе 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 — список разрешённых заголовков Host, обеспечивающий защиту от DNS-ребinding (по умолчанию: пусто = без проверки Host)

Поведение

1. Сеть доступна + настроен GitHub: загружает руководства из GitHub и кэширует их локально

2. Сеть недоступна: использует локальный кэш, если он доступен

3. Кэш недоступен: переключается на локальный guides_dir, если он настроен

Удалённое развёртывание (Google Cloud Run)

Один и тот же образ обслуживает оба транспорта: по умолчанию он работает через stdio по каналу, и переключается на Streamable HTTP при наличии переменной окружения PORT — которую 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 в 60 запросов в час на исходящий IP, после чего сервер молча переключится на те же встроенные файлы.

Конечная точка MCP будет доступна по адресу https://<service-url>/mcp:

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

Cloud Run отвечает на двух именах хостов для одного сервиса — в форме SERVICE-PROJECTNUMBER.REGION.run.app, выводимой командой gcloud run deploy, и в более старой форме SERVICE-HASH-REGIONCODE.a.run.app, которую сообщает status.url. Обе эквивалентны; любая из них работает в конфигурации клиента.

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 — это TCP-проверка на $PORT, так что это нормально — не настраивайте HTTP-проверку работоспособности на /.

• Установите GUIDES_ALLOWED_HOSTS на имя хоста вашего сервиса, чтобы включить проверку заголовка Host, если вы публикуете сервис под пользовательским доменом.

Публикация в реестре MCP

Список MCP-серверов в представлении «Расширения» VS Code (введите @mcp в строке поиска) формируется из реестра GitHub MCP Registry, который получает данные из официального реестра MCP. Публикация там — это способ сделать этот сервер обнаруживаемым в VS Code — собственное расширение VS Code не требуется.

server.json содержит метаданные реестра: образ Docker для клиентов, которые хотят запускать его локально, и размещённый URL для клиентов, которые предпочитают не делать этого. Право собственности на образ подтверждается меткой io.modelcontextprotocol.server.name в Dockerfile, значение которой должно быть равно .name в server.json.

Аутентифицируйтесь один раз (интерактивный поток с кодом устройства), затем запустите скрипт публикации:

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 — добавьте его как пользовательский коннектор в настройках или соедините удалённую конечную точку с stdio-клиентом с помощью mcp-remote:

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

Любой клиент, поддерживающий Streamable HTTP, работает — укажите URL /mcp. Для серверов, защищённых аутентификацией, передайте токен с помощью --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.