MCP Server Integration¶

Polycrate enthält einen integrierten MCP-Server (Model Context Protocol), der AI-Assistenten wie Claude, Cursor oder GitHub Copilot direkten Zugriff auf den Polycrate Hub und die Dokumentation ermöglicht.

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 Polycrate MCP-Server 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.

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¶

• PolyHub - Block-Registry
• CLI-Referenz - Vollständige Command-Referenz
• Integrationen - Übersicht aller Integrationen
• MCP Protocol - Offizielle MCP-Dokumentation