MCP Server

Der lokale Polycrate-MCP-Server (polycrate mcp): sechs Tool-Familien für Hub, Dokumentation, Specs, Workspace- und Block-Releases und Actions. Konfiguration für Cursor, Claude Desktop und Copilot.

Polycrate stellt AI-Assistenten zwei getrennte MCP-Server bereit. Diese Seite beschreibt den lokalen CLI-MCP (polycrate mcp): Hub, Dokumentation, Schemas und der komplette SDD-/Release-Flow für Workspaces und Blocks.

Für Live-Daten der Plattform (Workspaces, Alerts, Cluster, Logs) brauchen Sie den API-MCP — anderer Endpunkt, API-Key.

Beide Einträge können parallel in Cursor stehen. Der Assistant-Chat in der Polycrate-UI ist ein drittes Produkt und kein MCP.

Was der CLI-MCP kann

Das Model Context Protocol (MCP) ist ein offener Standard, über den AI-Modelle externe Tools aufrufen. Der lokale Polycrate-MCP führt dieselben Operationen aus wie die CLI — jeder Tool-Aufruf ist ein polycrate-Kommando mit identischen Gates:

• Blocks im Hub suchen, inspizieren, Versionen listen
• Dokumentation lesen: lokale Schemas (workspace.poly, block.poly, …), eingebettete Guides, öffentliche Docs von ayedo.de
• Specs anlegen, lesen, Sektionen schreiben, Status setzen, linten
• Workspace-Releases anlegen, Changelog/Release Note schreiben, finalisieren
• Block-Releases eintragen, finalisieren, pushen, downstream pullen
• Actions ausführen

Der Prozess, den diese Ops abbilden, steht in Entwickeln und deployen und Spec-Driven Development.

Server starten

polycrate mcp

Konfiguration

Cursor IDE

~/.cursor/mcp.json (global) oder .cursor/mcp.json im Projekt:

{
  "mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

Nach dem Speichern: Cursor neu starten. Zusätzlich polycrate spec rules generate --force -w /abs/pfad ausführen, damit .cursor/rules/sdd.mdc den Agent auf den kanonischen Flow festlegt.

Claude Desktop

{
  "mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

GitHub Copilot (VS Code)

.vscode/mcp.json im Workspace:

{
  "servers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

Die sechs Tools

Ein Server, sechs Tools. Jedes Tool nimmt op (Pflicht) und dispatcht darauf. Keine Aliase, keine session_id. Mutierende Ops brauchen workspace als absoluten Pfad — relativ ist ein Hard Fail.

hub

docs

sdd

workspace

block

Es gibt kein release_create für Blocks — der Aufruf liefert einen Fehler mit Hinweis auf release_update → release_finalize. Blocks haben keine Specs.

action

Beispiele

Block-Discovery

Tool: hub   {"op": "list_blocks", "filter": "postgres", "limit": 10}
Tool: hub   {"op": "inspect_block", "block_name": "ayedo/k8s/postgres", "content_type": "readme"}
Tool: hub   {"op": "list_versions", "block_name": "ayedo/k8s/postgres"}

Workspace generieren

Tool: docs  {"op": "schema", "name": "workspace"}
Tool: hub   {"op": "inspect_block", "block_name": "ayedo/k8s/cluster"}
→ Der Assistent erzeugt eine vollständige workspace.poly

Spec bis Release

Tool: sdd        {"op": "create", "workspace": "/abs/ws", "name": "Hub-Token rotieren", "type": "feat"}
Tool: sdd        {"op": "update_section", "workspace": "/abs/ws", "id": 7, "section": "solution", "body": "### Plan\n…"}
Tool: sdd        {"op": "lint", "workspace": "/abs/ws", "id": 7}
Tool: sdd        {"op": "update_meta", "workspace": "/abs/ws", "id": 7, "status": "done"}
Tool: workspace  {"op": "release_create", "workspace": "/abs/ws", "version": "1.4.0", "spec": "7"}
Tool: workspace  {"op": "release_update", "workspace": "/abs/ws", "version": "1.4.0", "type": "feat", "message": "Hub-Token-Rotation", "highlights": "- Rotation ohne Downtime"}
Tool: workspace  {"op": "release_finalize", "workspace": "/abs/ws", "version": "1.4.0"}

Block releasen und deployen

Tool: block   {"op": "release_update", "workspace": "/abs/core", "block": "hardening", "version": "0.5.6", "type": "fix", "message": "PerSourcePenalties konfigurierbar"}
Tool: block   {"op": "release_finalize", "workspace": "/abs/core", "block": "hardening", "version": "0.5.6"}
Tool: block   {"op": "pull", "workspace": "/abs/prod", "block": "cargo.ayedo.cloud/ayedo/linux/hardening", "version": "0.5.6"}
Tool: action  {"op": "run", "workspace": "/abs/prod", "block": "hardening", "action": "install"}

Dokumentation nachschlagen

Tool: docs  {"op": "guide", "name": "dev_and_deploy"}
Tool: docs  {"op": "get", "path": "/docs/polycrate/spec-driven-development/", "locale": "de"}
Tool: docs  {"op": "search", "q": "workspace verschlüsselung"}

Fehlerbehebung

„MCP Server not found“

which polycrate && polycrate version
cat ~/.cursor/mcp.json

Liegt polycrate nicht im PATH, den vollen Pfad als command eintragen (z. B. /usr/local/bin/polycrate).

„unknown op“ oder „workspace must be absolute“

Die Fehlermeldung nennt die erlaubten Ops bzw. verlangt einen absoluten Pfad. Beides sind Gates der CLI, nicht des MCP — die CLI-Doku zum jeweiligen Command gilt.

„Connection to Hub failed“

polycrate hub inspect ayedo/k8s/cluster
curl -I https://hub.polycrate.io

„No tools available“

Nach Änderungen an der MCP-Konfiguration den Client komplett neu starten.

Sicherheit

• Der Server läuft lokal; Hub und Public API werden per HTTPS angesprochen
• Es werden keine Credentials an den Assistenten übermittelt; docs nutzt keinen Token
• Mutierende Ops (sdd, workspace, block, action) wirken auf lokale Dateien, die Registry und Zielsysteme — mit denselben Gates wie die CLI
• Registry-Auth für Action-Container kommt aus DOCKER_REGISTRY_HOST / _USER / _PASSWORD der Prozessumgebung; ~/.docker/config.json wird nicht gemountet

Siehe auch

• Entwickeln und deployen — die Prozesskette mit MCP-Ops je Schritt
• Spec-Driven Development
• PolyHub — Block-Registry
• CLI-Referenz
• MCP Protocol — Offizielle MCP-Dokumentation