Coding Guides MCP Server

Ein Model-Context-Protocol-Server (MCP), der Zugriff auf Coding-Guides und Best Practices für KI-Assistenten wie Claude und GitHub Copilot bietet.

Was ist das?

Dieser MCP-Server stellt Codierungsrichtlinien und Styleguides als Ressourcen bereit, auf die MCP-Clients zugreifen können. Er wurde entwickelt, um AGENTS.md-Dateien zu erweitern oder zu ersetzen, indem er eine strukturierte Möglichkeit bietet, Coding-Praktiken und Richtlinien während der Entwicklung an KI-Assistenten auszuliefern.

Related MCP server: Code Understanding MCP Server

Funktionen

• Ressourcenbasierte API: Stellt Coding-Guides über MCP-Ressourcen bereit

• GitHub-Integration: Lädt Guides aus GitHub-Repositories über das Web

• Automatisches Caching: Speichert heruntergeladene Guides lokal für den Offline-Zugriff

• Fallback-Unterstützung: Verwendet lokalen Cache oder Verzeichnis, wenn das Netzwerk nicht verfügbar ist

• Einfache dateibasierte Speicherung: Guides können lokal als Markdown-Dateien gespeichert werden

• Offizielles MCP-SDK: Basiert auf dem Python-mcp-SDK (MCPServer, ehemals FastMCP)

• Einfache Integration: Funktioniert mit jedem MCP-kompatiblen Client (Claude Desktop, Cline usw.)

Verfügbare Ressourcen

• guides://list – Listet alle verfügbaren Coding-Guides auf

• guides://{guide_name} – Ruft den Inhalt eines bestimmten Guides ab (z. B. guides://python.md)

Installation

Aus dem Quellcode

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

Mit Docker

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

In VS Code

Oder suchen Sie in der MCP-Serverliste der Extensions-Ansicht nach codeguide-mcp (geben Sie @mcp in die Extensions-Suchleiste ein) oder fügen Sie es manuell zu .vscode/mcp.json hinzu:

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

Konfiguration

Konfigurieren Sie den Server, indem Sie eine config.toml-Datei erstellen oder Umgebungsvariablen festlegen:

GitHub-Konfiguration (empfohlen)

Um Guides aus einem GitHub-Repository zu laden:

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"

Konfiguration des lokalen Verzeichnisses

Um nur lokale Guides zu verwenden:

guides_dir = "guides"
log_level = "INFO"

Umgebungsvariablen

• GUIDES_GITHUB_REPO – GitHub-Repository (Format: owner/repo)

• GUIDES_GITHUB_PATH – Pfad zum Guides-Verzeichnis im Repository (Standard: guides)

• GUIDES_GITHUB_BRANCH – Abzurufender Branch (Standard: main)

• GUIDES_CACHE_DIR – Lokales Cache-Verzeichnis (Standard: .guides-cache)

• GUIDES_DIR – Lokales Verzeichnis mit Guide-Dateien (Standard: guides)

• GUIDES_LOG_LEVEL – Protokollierungsstufe (Standard: INFO)

Transport (siehe Remote-Bereitstellung):

• GUIDES_TRANSPORT – stdio, streamable-http oder auto (Standard: auto – HTTP, wenn eine PORT-Umgebungsvariable vorhanden ist, andernfalls stdio)

• PORT – Port, auf dem im HTTP-Modus gelauscht wird; hat Vorrang vor GUIDES_PORT (Cloud Run injiziert diesen)

• GUIDES_HOST – Bind-Adresse im HTTP-Modus (Standard: 0.0.0.0)

• GUIDES_HTTP_PATH – MCP-Endpunktpfad (Standard: /mcp)

• GUIDES_STATELESS_HTTP – Jede Anfrage unabhängig behandeln (Standard: true; erforderlich, wenn Replikate automatisch skaliert werden)

• GUIDES_ALLOWED_HOSTS – Host-Header-Allowlist, die DNS-Rebinding-Schutz ermöglicht (Standard: leer = keine Host-Validierung)

Verhalten

1. Netzwerk verfügbar + GitHub konfiguriert: Ruft Guides von GitHub ab und speichert sie lokal zwischen

2. Netzwerk nicht verfügbar: Verwendet lokalen Cache, falls verfügbar

3. Kein Cache verfügbar: Fällt auf das lokale guides_dir zurück, falls konfiguriert

Remote-Bereitstellung (Google Cloud Run)

Dasselbe Image bedient beide Transporte: Es spricht standardmäßig stdio über eine Pipe und wechselt zu Streamable HTTP, wenn eine PORT-Umgebungsvariable vorhanden ist – die Cloud Run immer injiziert. Es ist kein separates Image oder Entrypoint erforderlich.

1. Image veröffentlichen

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

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= (leer) bewirkt, dass der Dienst die im Image enthaltenen Guides ausliefert. Wenn GitHub aktiviert bleibt, entsteht pro Guide ein Netzwerk-Roundtrip und die unauthentifizierte GitHub-API-Beschränkung von 60 Anfragen/Stunde pro Egress-IP wird erreicht, woraufhin der Server stillschweigend auf dieselben eingebetteten Dateien zurückfällt.

Der MCP-Endpunkt ist dann https://<service-url>/mcp:

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

Cloud Run antwortet auf zwei Hostnamen für denselben Dienst – die von gcloud run deploy ausgegebene Form SERVICE-PROJECTNUMBER.REGION.run.app und die ältere Form SERVICE-HASH-REGIONCODE.a.run.app, die status.url meldet. Beide sind gleichwertig; beide funktionieren in einer Client-Konfiguration.

3. Clients darauf ausrichten

Siehe Verbinden mit einem Remote-Server unten für die client-spezifische Konfiguration.

Von Docker Hub abrufen

Cloud Run stellt öffentliche Docker-Hub-Images direkt bereit, speichert sie aber nur eine Stunde zwischen und zieht sie danach anonym erneut ab. Bei einer Skalierung kann daher das anonyme Pull-Limit von Docker Hub erreicht werden und Instanzen können nicht gestartet werden. Für alles über den gelegentlichen Gebrauch hinaus spiegeln Sie das Image über ein Remote-Repository in 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 \
  ...

Hinweise zum öffentlichen Betrieb

• --allow-unauthenticated macht den Endpunkt weltweit aufrufbar. Der Server ist schreibgeschützt, aber der clear_cache-Prompt ist für jeden Aufrufer erreichbar und verwirft die In-Memory-Caches, und der Datenverkehr treibt die Autoskalierungskosten in die Höhe – halten Sie --max-instances begrenzt. Um den Zugriff einzuschränken, lassen Sie das Flag weg und lassen Sie Clients ein Identitätstoken senden, oder stellen Sie den Dienst hinter Cloud Armor / API Gateway.

• GUIDES_STATELESS_HTTP muss true bleiben, es sei denn, Sie aktivieren auch Sitzungsaffinität, da Cloud Run die Anfragen einer Sitzung auf verschiedene Instanzen verteilen kann.

• GET / gibt absichtlich 404 zurück; nur /mcp wird bedient. Der Standard-Startprobe von Cloud Run ist ein TCP-Check auf $PORT, das ist also in Ordnung – konfigurieren Sie keinen HTTP-Health-Check auf /.

• Setzen Sie GUIDES_ALLOWED_HOSTS auf Ihren Diensthostnamen, um die Host-Header-Validierung zu aktivieren, wenn Sie den Dienst unter einer benutzerdefinierten Domain bereitstellen.

Veröffentlichung im MCP-Registry

Die MCP-Serverliste in der VS-Code-Extensions-Ansicht (geben Sie @mcp in die Suchleiste ein) wird vom GitHub-MCP-Registry gespeist, das aus dem offiziellen MCP-Registry übernimmt. Die Veröffentlichung dort ist daher der Weg, wie dieser Server in VS Code auffindbar wird – eine eigene VS-Code-Erweiterung ist nicht erforderlich.

server.json enthält die Registry-Metadaten: das Docker-Image für Clients, die es lokal ausführen möchten, und die gehostete URL für Clients, die das nicht möchten. Der Besitz des Images wird durch das Label io.modelcontextprotocol.server.name im Dockerfile nachgewiesen, dessen Wert muss gleich .name in server.json sein.

Authentifizieren Sie sich einmal (ein interaktiver Device-Code-Flow) und führen Sie dann das Veröffentlichungsskript aus:

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

tools/publish.sh erledigt die gesamte Veröffentlichung: Es prüft die erforderlichen Tools und den Docker-Login, verifiziert, dass server.json und pyproject.toml in der Version übereinstimmen und dass das Dockerfile-Label mit dem Servernamen übereinstimmt, baut und pusht :VERSION und :latest, validiert server.json gegen das Live-Registry, veröffentlicht und liest den Eintrag zur Bestätigung zurück.

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

Installieren Sie mcp-publisher aus dem Registry-Quickstart, falls Sie es nicht haben. Nach der Veröffentlichung kann die Aufnahme in die kuratierte Liste von GitHub eine Anfrage an partnerships@github.com erfordern.

Hinzufügen von Guides

Verwenden von GitHub (empfohlen)

Wenn Sie github_repo konfiguriert haben, fügen Sie einfach Markdown-Dateien zum angegebenen Verzeichnis in Ihrem GitHub-Repository hinzu. Der Server ruft sie automatisch ab und speichert sie zwischen.

Verwenden eines lokalen Verzeichnisses

Fügen Sie Markdown-Dateien zum Verzeichnis guides/ hinzu. Jede Datei ist automatisch als Ressource verfügbar.

Beispiel:

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

Verwendung mit MCP-Clients

Der Server kann auf zwei Arten verwendet werden:

Der lokale Modus benötigt kein Netzwerk und kein Hosting; der Remote-Modus ermöglicht es einem Team, eine Bereitstellung zu teilen und hält die Guides für alle identisch.

Verbinden mit einem Remote-Server

Eine bereitgestellte Instanz stellt ihren MCP-Endpunkt unter /mcp bereit. Die folgenden Ausschnitte verwenden die Referenzbereitstellung:

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

Sie ist öffentlich und benötigt keine Anmeldeinformationen. Ersetzen Sie sie durch Ihre eigene URL, wenn Sie den Dienst selbst betreiben – siehe Remote-Bereitstellung.

VS Code – .vscode/mcp.json für einen Arbeitsbereich oder Ihre Benutzer-mcp.json für alle Arbeitsbereiche:

{
  "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) oder .cursor/mcp.json (pro Projekt):

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

Claude Desktop – Fügen Sie es als benutzerdefinierten Connector in den Einstellungen hinzu oder überbrücken Sie den Remote-Endpunkt in einen stdio-Client mit mcp-remote:

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

Jeder Client, der Streamable HTTP spricht, funktioniert – richten Sie ihn auf die /mcp-URL. Für Server hinter Authentifizierung übergeben Sie ein Token mit --header "Authorization: Bearer $(gcloud auth print-identity-token)" (Claude Code) oder den entsprechenden headers-Block des Clients.

Überprüfen eines Remote-Endpunkts

Ein einzelnes curl bestätigt, dass eine Bereitstellung live und öffentlich ist:

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

Ein gesunder Server antwortet mit einem SSE-event: message-Frame, der seine Fähigkeiten und Anweisungen enthält. Beachten Sie, dass GET / absichtlich 404 zurückgibt – nur /mcp wird bedient.

Um stattdessen jede Ressource, jedes Tool und jeden Prompt über HTTP zu testen:

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

Lokale Verwendung

Claude Desktop

Fügen Sie zu Ihrer mcp.json hinzu:

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

oder

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

Andere MCP-Clients

Führen Sie den Server aus und verbinden Sie sich über stdio:

python main.py

Entwicklung

# 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

Lizenz

MIT

Mitwirken

Beiträge sind willkommen! Bitte öffnen Sie ein Issue oder einen Pull-Request.