MCP Server Integration¶

Polycrate stellt AI-Assistenten zwei getrennte MCP-Server bereit. Diese Seite beschreibt den lokalen CLI-MCP (polycrate mcp): Hub, Dokumentation und Schemas für die Workspace-Entwicklung.

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

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

Der CLI-MCP gibt Assistenten wie Claude, Cursor oder GitHub Copilot Zugriff auf den Polycrate Hub und docs.ayedo.de.

Was ist MCP?¶

Das Model Context Protocol (MCP) ist ein offener Standard, der AI-Modellen ermöglicht, mit externen Tools und Datenquellen zu interagieren. Mit dem lokalen CLI-MCP können AI-Assistenten:

• Blocks im Hub durchsuchen und filtern
• Block-Details abrufen (README, Konfiguration, Versionen)
• Polycrate-Dokumentation abfragen für kontextbezogene Hilfe
• Schema-Spezifikationen abrufen für korrekte workspace.poly/block.poly Generierung
• Bei der Workspace-Entwicklung helfen durch kontextbezogene Block-Empfehlungen

graph LR
    AI[AI-Assistent<br/>Claude/Cursor/Copilot] -->|MCP Protocol| Server[Polycrate MCP Server]
    Server -->|API Calls| Hub[Polycrate Hub]
    Server -->|HTTP Scraping| Docs[docs.ayedo.de]
    Hub -->|Block-Daten| Server
    Docs -->|Dokumentation| Server
    Server -->|Strukturierte Antworten| AI
    AI -->|Empfehlungen| User[Entwickler]

Server starten¶

Der MCP-Server wird automatisch von konfigurierten AI-Clients gestartet:

polycrate mcp

Konfiguration¶

Cursor IDE¶

Erstellen oder bearbeiten Sie ~/.cursor/mcp.json:

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

Nach dem Speichern: Cursor neu starten.

Claude Desktop (macOS)¶

Erstellen oder bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Claude Desktop (Linux)¶

Erstellen oder bearbeiten Sie ~/.config/Claude/claude_desktop_config.json:

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

Claude Desktop (Windows)¶

Erstellen oder bearbeiten Sie %APPDATA%\Claude\claude_desktop_config.json:

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

GitHub Copilot (VS Code)¶

Für GitHub Copilot in VS Code erstellen oder bearbeiten Sie .vscode/mcp.json in Ihrem Workspace:

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

Alternativ global in den VS Code Settings (settings.json):

{
  "github.copilot.chat.mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

Verfügbare Tools¶

Der MCP-Server stellt folgende Tools bereit:

Hub-Tools¶

CLI-Tools¶

Spec-Tools (Schema-Spezifikationen)¶

Die Spec-Tools ermöglichen AI-Assistenten, korrekte Polycrate-Konfigurationen zu generieren, ohne die Dokumentation manuell lesen zu müssen.

Guide-Tools (Best Practices für LLMs)¶

Diese Tools liefern schrittweise Anleitungen und Best Practices – ideal für AI-Assistenten, die Nutzer bei der Polycrate-Entwicklung unterstützen:

Dokumentations-Tools¶

Verfügbare Topics für docs_get:

index, workspaces, blocke, actions, workflows, workspace-verschluesselung, git, registry, polyhub, best-practices, cli-referenz, api, troubleshooting, mcp, ssh, installation, dependencies, vererbung, events, configuration, recipes, cloud-migration, kubernetes, ansible, integrationen

Docs-URL konfigurieren:

Die URL für die Dokumentation kann in ~/.polycrate/polycrate.yml konfiguriert werden:

hub:
  docs_url: http://localhost:8012  # Für lokale Entwicklung
  # docs_url: https://docs.ayedo.de  # Standard (kann weggelassen werden)

Dies ist nützlich, wenn Sie:

• An der Dokumentation lokal arbeiten (mkdocs serve)
• Eine eigene Dokumentations-Instanz betreiben

hub_info¶

Zeigt die aktuelle Hub-Konfiguration:

Tool: hub_info
Parameters: {}

Response:
Polycrate Hub Configuration:
  URL: https://hub.polycrate.io
  Registry: cargo.ayedo.cloud
  Docs URL: https://docs.ayedo.de

Use 'hub_inspect_block' to get details about specific blocks.
Use 'hub_list_versions' to see available versions of a block.
Use 'hub_list_blocks' to list all available blocks.
Use 'docs_get' to fetch documentation from the configured docs URL.

hub_list_blocks¶

Durchsucht alle Blöcke im Hub:

Tool: hub_list_blocks
Parameters: {
  "filter": "postgres",
  "kind": "k8sapp",
  "limit": 10
}

Response:
[
  {
    "name": "k8s/postgres-base",
    "kind": "k8sapp",
    "versions": 5,
    "latest": "1.2.0",
    "description": "PostgreSQL on Kubernetes with CloudNativePG"
  }
]

hub_inspect_block¶

Ruft Details zu einem Block ab:

Tool: hub_inspect_block
Parameters: {
  "block_name": "ayedo/k8s/postgres-base",
  "version": "latest"
}

Response:
{
  "name": "postgres-base",
  "version": "1.2.0",
  "kind": "k8sapp",
  "description": "...",
  "readme": "# PostgreSQL Base Block\n\n...",
  "config_schema": {...},
  "actions": ["install", "uninstall", "backup", "restore"]
}

hub_list_versions¶

Listet alle Versionen eines Blocks:

Tool: hub_list_versions
Parameters: {
  "block_name": "ayedo/k8s/postgres-base"
}

Response:
{
  "block": "postgres-base",
  "versions": ["1.2.0", "1.1.0", "1.0.0"]
}

spec_workspace¶

Ruft das workspace.poly Schema ab:

Tool: spec_workspace
Parameters: {}

Response:
# workspace.poly Schema Specification

## Required Fields
name: string  # Workspace name following the pattern: <org>-<purpose>-<count>

## Optional Fields
organization: string
blocks: list
  - name: string (required)
    from: string (optional)  # Full registry path with version
    config: object (optional)
...

docs_get¶

Ruft Polycrate-Dokumentation ab:

Tool: docs_get
Parameters: {
  "topic": "best-practices"
}

Response:
# Polycrate Documentation: best-practices
# Source: https://docs.ayedo.de/polycrate/best-practices/

## Workspace-Organisation
...

Use Cases¶

1. Block-Discovery für neue Workspaces¶

Fragen Sie Ihren AI-Assistenten:

"Ich brauche Blöcke für ein Kubernetes-Deployment mit PostgreSQL, Redis und Nginx Ingress."

Der Assistent nutzt hub_list_blocks um passende Blöcke zu finden und zeigt Ihnen die Optionen.

2. Konfigurationshilfe¶

"Wie konfiguriere ich den postgres-base Block für High-Availability mit 3 Replikas?"

Der Assistent ruft mit hub_inspect_block die README und das Config-Schema ab und gibt Ihnen ein konkretes Beispiel.

3. Versionsauswahl¶

"Welche Versionen gibt es vom cert-manager-base Block und was hat sich geändert?"

Der Assistent nutzt hub_list_versions und kann bei Bedarf das Changelog abrufen.

4. Workspace-Generierung¶

"Erstelle einen Workspace mit einem K3s-Cluster und einem Monitoring-Stack (Prometheus + Grafana)."

Der Assistent: 1. Ruft das Schema ab mit spec_workspace 2. Sucht passende Blöcke mit hub_list_blocks 3. Ruft Details ab mit hub_inspect_block 4. Generiert eine vollständige workspace.poly

5. Dokumentationsabfrage¶

"Wie funktioniert die Workspace-Verschlüsselung?"

Der Assistent nutzt docs_get mit topic: workspace-verschluesselung und erklärt basierend auf der offiziellen Dokumentation.

6. Changelog erstellen¶

"Erstelle einen CHANGELOG.poly Eintrag für Version 2.0.0."

Der Assistent: 1. Ruft das Format ab mit spec_changelog 2. Generiert einen korrekten Eintrag mit Datum, Typ und Beschreibung

Beispiel-Konversation¶

Du: "Ich möchte eine WordPress-Seite auf einem Docker-Host deployen. 
     Welche Blöcke brauche ich?"

AI: [nutzt hub_list_blocks mit filter="wordpress"]

    Für ein WordPress-Deployment empfehle ich folgende Blöcke:

    1. **dockerapp/wordpress-base** (v2.1.0)
       - WordPress mit MySQL/MariaDB
       - Automatisches SSL via Traefik
       - Backup-Integration

    2. **linuxapp/docker-host-base** (v1.0.0)
       - Docker-Installation auf Linux-Host
       - Docker-Compose Setup

    Soll ich dir eine workspace.poly mit diesen Blöcken erstellen?

Du: "Ja, bitte."

AI: [nutzt hub_inspect_block für beide Blöcke]

    Hier ist deine workspace.poly:

    ```yaml
    name: wordpress-site
    organization: my-org

    blocks:
      - name: docker-host
        from: docker-host-base:1.0.0
        inventory:
          from: workspace

      - name: wordpress
        from: wordpress-base:2.1.0
        config:
          domain: blog.example.com
          ssl_enabled: true
          backup:
            enabled: true
            schedule: "0 2 * * *"

    workflows:
      - name: deploy
        steps:
          - name: setup-docker
            block: docker-host
            action: install

          - name: deploy-wordpress
            block: wordpress
            action: install
    ```

Vorteile¶

Fehlerbehebung¶

"MCP Server not found"¶

# Prüfen ob Polycrate installiert ist
which polycrate
polycrate version

# Pfad in MCP-Config prüfen
cat ~/.cursor/mcp.json

Falls Polycrate nicht im PATH ist, verwenden Sie den vollständigen Pfad:

{
  "mcpServers": {
    "polycrate": {
      "command": "/usr/local/bin/polycrate",
      "args": ["mcp"]
    }
  }
}

"Connection to Hub failed"¶

# Hub-Verbindung testen
polycrate hub inspect ayedo/k8s/cluster

# Netzwerkverbindung prüfen
curl -I https://hub.polycrate.io

"No tools available"¶

Nach Änderungen an der MCP-Konfiguration:

1. Cursor: IDE komplett neu starten
2. Claude Desktop: Anwendung neu starten

Sicherheit¶

• Der MCP-Server läuft lokal auf Ihrem Rechner
• Kommunikation zum Hub erfolgt über HTTPS
• Keine Credentials werden an den AI-Assistenten übermittelt
• Nur öffentliche Hub-Daten werden abgerufen

Siehe auch¶

• MCP — AI-Zugang zur Plattform — Remote-MCP der Polycrate API
• PolyHub — Block-Registry
• CLI-Referenz — Vollständige Command-Referenz
• Integrationen — Übersicht aller Integrationen
• MCP Protocol — Offizielle MCP-Dokumentation