Servidor de Guías de MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso a guías de codificación y mejores prácticas para asistentes de IA como Claude y GitHub Copilot.

¿Qué es esto?

Este servidor MCP expone guías de codificación y guías de estilo como recursos que pueden ser accedidos por clientes MCP. Está diseñado para extender o reemplazar archivos AGENTS.md proporcionando una forma estructurada de servir prácticas y guías de codificación a asistentes de IA durante el desarrollo.

Related MCP server: Code Understanding MCP Server

Características

• API basada en recursos: Expone guías de codificación a través de recursos MCP

• Integración con GitHub: Carga guías desde repositorios de GitHub a través de la web

• Caché automática: Almacena en caché las guías descargadas localmente para acceso sin conexión

• Soporte de respaldo: Utiliza la caché local o el directorio local cuando la red no está disponible

• Almacenamiento simple basado en archivos: Las guías se pueden almacenar como archivos Markdown localmente

• SDK oficial de MCP: Construido con el SDK de Python mcp (MCPServer, anteriormente FastMCP)

• Integración fácil: Funciona con cualquier cliente compatible con MCP (Claude Desktop, Cline, etc.)

Recursos disponibles

• guides://list - Lista todas las guías de codificación disponibles

• guides://{guide_name} - Recupera el contenido de una guía específica (por ejemplo, guides://python.md)

Instalación

Desde la fuente

# 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 .

Con Docker

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

En VS Code

O busque codeguide-mcp en la lista de servidores MCP de la vista de Extensiones (escriba @mcp en la barra de búsqueda de Extensiones), o añádalo manualmente a .vscode/mcp.json:

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

Configuración

Configure el servidor creando un archivo config.toml o estableciendo variables de entorno:

Configuración de GitHub (Recomendada)

Para cargar guías desde un repositorio de 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"

Configuración de directorio local

Para usar solo guías locales:

guides_dir = "guides"
log_level = "INFO"

Variables de entorno

• GUIDES_GITHUB_REPO - Repositorio de GitHub (formato: owner/repo)

• GUIDES_GITHUB_PATH - Ruta al directorio de guías en el repositorio (predeterminado: guides)

• GUIDES_GITHUB_BRANCH - Rama desde la que obtener (predeterminado: main)

• GUIDES_CACHE_DIR - Directorio de caché local (predeterminado: .guides-cache)

• GUIDES_DIR - Directorio local que contiene los archivos de guía (predeterminado: guides)

• GUIDES_LOG_LEVEL - Nivel de registro (predeterminado: INFO)

Transporte (ver Implementación remota):

• GUIDES_TRANSPORT - stdio, streamable-http, o auto (predeterminado: auto — HTTP cuando hay una variable de entorno PORT, stdio en caso contrario)

• PORT - Puerto para escuchar en modo HTTP; tiene prioridad sobre GUIDES_PORT (Cloud Run lo inyecta)

• GUIDES_HOST - Dirección de enlace en modo HTTP (predeterminado: 0.0.0.0)

• GUIDES_HTTP_PATH - Ruta del endpoint MCP (predeterminado: /mcp)

• GUIDES_STATELESS_HTTP - Manejar cada solicitud de forma independiente (predeterminado: true; requerido cuando las réplicas se escalan automáticamente)

• GUIDES_ALLOWED_HOSTS - Lista de hosts permitidos en la cabecera Host que habilita la protección contra DNS-rebinding (predeterminado: vacío = sin validación de Host)

Comportamiento

1. Red disponible + GitHub configurado: Obtiene las guías desde GitHub y las almacena en caché localmente

2. Red no disponible: Usa la caché local si está disponible

3. Sin caché disponible: Recurre al directorio local guides_dir si está configurado

Implementación remota (Google Cloud Run)

La misma imagen sirve ambos transportes: habla stdio a través de una tubería por defecto, y cambia a HTTP Streamable cuando hay una variable de entorno PORT presente — que Cloud Run siempre inyecta. No se necesita una imagen o punto de entrada separado.

1. Publicar la imagen

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. Implementar

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= (vacío) hace que el servicio sirva las guías integradas en la imagen. Dejar GitHub habilitado añade un viaje de ida y vuelta por red por guía y se topa con el límite de 60 solicitudes/hora de la API de GitHub no autenticada por IP de salida, tras lo cual el servidor recurre silenciosamente a esos mismos archivos integrados de todos modos.

El endpoint MCP es entonces https://<service-url>/mcp:

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

Cloud Run responde en dos nombres de host para el mismo servicio — la forma SERVICE-PROJECTNUMBER.REGION.run.app impresa por gcloud run deploy, y la forma más antigua SERVICE-HASH-REGIONCODE.a.run.app que informa status.url. Ambos son equivalentes; cualquiera funciona en la configuración de un cliente.

3. Apuntar los clientes a él

Consulte Conexión a un servidor remoto a continuación para la configuración por cliente.

Extraer desde Docker Hub

Cloud Run implementa imágenes públicas de Docker Hub directamente, pero las almacena en caché solo durante una hora y las vuelve a extraer de forma anónima después, por lo que un escalado puede chocar con los límites de extracción anónima de Docker Hub y no poder iniciar instancias. Para algo más que un uso casual, use un repositorio remoto de 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 \
  ...

Notas sobre ejecutarlo públicamente

• --allow-unauthenticated hace que el endpoint sea accesible desde cualquier lugar del mundo. El servidor es de solo lectura, pero el prompt clear_cache es alcanzable por cualquier llamante y vacía las cachés en memoria, y el tráfico impulsa el costo de autoescalado — mantenga --max-instances limitado. Para restringir el acceso, omita la bandera y haga que los clientes envíen un token de identidad, o proteja el servicio con Cloud Armor / API Gateway.

• GUIDES_STATELESS_HTTP debe permanecer true a menos que también habilite la afinidad de sesión, ya que Cloud Run puede enrutar las solicitudes de una sesión a diferentes instancias.

• GET / devuelve 404 por diseño; solo se sirve /mcp. La sonda de inicio predeterminada de Cloud Run es una verificación TCP en $PORT, así que esto está bien — no configure una verificación de salud HTTP en /.

• Establezca GUIDES_ALLOWED_HOSTS al nombre de host de su servicio para habilitar la validación de la cabecera Host si expone el servicio bajo un dominio personalizado.

Publicación en el Registro MCP

La lista de servidores MCP en la vista de Extensiones de VS Code (escriba @mcp en la barra de búsqueda) se alimenta del Registro MCP de GitHub, que a su vez se nutre del Registro MCP oficial. Publicar allí es, por tanto, cómo este servidor se vuelve descubrible en VS Code — no se requiere ninguna extensión de VS Code propia.

server.json contiene los metadatos del registro: la imagen Docker para clientes que quieran ejecutarlo localmente, y la URL alojada para clientes que prefieran no hacerlo. La propiedad de la imagen se demuestra con la etiqueta io.modelcontextprotocol.server.name en el Dockerfile, cuyo valor debe ser igual a .name en server.json.

Autentíquese una vez (un flujo interactivo de código de dispositivo), luego ejecute el script de publicación:

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

tools/publish.sh hace el lanzamiento completo: verifica las herramientas requeridas y el inicio de sesión de Docker, comprueba que server.json y pyproject.toml coinciden en la versión y que la etiqueta del Dockerfile coincide con el nombre del servidor, construye y publica :VERSION y :latest, valida server.json contra el registro en vivo, publica, y luego lee la entrada de nuevo para confirmar.

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

Instale mcp-publisher desde el inicio rápido del registro si no lo tiene. Después de publicar, la inclusión en la lista curada de GitHub puede requerir una solicitud a partnerships@github.com.

Añadir guías

Usando GitHub (Recomendado)

Si ha configurado github_repo, simplemente añada archivos Markdown al directorio especificado en su repositorio de GitHub. El servidor los obtendrá y almacenará en caché automáticamente.

Usando un directorio local

Añada archivos Markdown al directorio guides/. Cada archivo estará automáticamente disponible como recurso.

Ejemplo:

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

Uso con clientes MCP

El servidor se puede consumir de dos maneras:

El modo local no necesita red ni alojamiento; el modo remoto permite que un equipo comparta una única implementación y mantiene las guías idénticas para todos.

Conexión a un servidor remoto

Una instancia implementada expone su endpoint MCP en /mcp. Los fragmentos a continuación usan la implementación de referencia:

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

Es pública y no necesita credenciales. Sustituya su propia URL si ejecuta el servicio usted mismo — consulte Implementación remota.

VS Code — .vscode/mcp.json para un espacio de trabajo, o su mcp.json de usuario para todos los espacios de trabajo:

{
  "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 (global) o .cursor/mcp.json (por proyecto):

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

Claude Desktop — añádalo como conector personalizado en Configuración, o conecte el endpoint remoto a un cliente stdio con mcp-remote:

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

Cualquier cliente que hable HTTP Streamable funciona — apúntelo a la URL /mcp. Para servidores detrás de autenticación, pase un token con --header "Authorization: Bearer $(gcloud auth print-identity-token)" (Claude Code) o el bloque headers equivalente del cliente.

Verificación de un endpoint remoto

Un solo curl confirma que una implementación está activa y es pública:

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"}}}'

Un servidor saludable responde con una trama SSE event: message que contiene sus capacidades e instrucciones. Tenga en cuenta que GET / devuelve 404 por diseño — solo se sirve /mcp.

Para ejercitar cada recurso, herramienta y prompt a través de HTTP en su lugar:

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

Uso local

Claude Desktop

Añada a su mcp.json:

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

o

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

Otros clientes MCP

Ejecute el servidor y conéctese a través de stdio:

python main.py

Desarrollo

# 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

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abra un issue o una pull request.