cloudcraft-mcp

Model Context Protocol (MCP)-Server für Cloudcraft.co — Auflisten, Lesen, Exportieren und Erstellen von Cloud-Architektur-Blueprints über Claude Desktop und andere MCP-Clients.

Funktionen

Neun Tools, die dem MCP-Host zur Verfügung gestellt werden:

Related MCP server: AWS MCP Server

Anforderungen

• Python 3.10+

• uv (brew install uv)

• Cloudcraft API-Schlüssel — generieren Sie einen unter https://app.cloudcraft.co/ → User settings → API keys

Installation

Klonen Sie das Repo und lassen Sie uv die Abhängigkeiten beim ersten Ausführen auflösen — kein expliziter Installationsschritt erforderlich.

git clone https://github.com/hypark5540/cloudcraft-mcp.git
cd cloudcraft-mcp
export CLOUDCRAFT_API_KEY='your-key-here'
uv run cloudcraft-mcp   # smoke test — Ctrl+C to exit

Claude Desktop-Integration

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder das Äquivalent auf Ihrer Plattform:

{
  "mcpServers": {
    "cloudcraft": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/cloudcraft-mcp",
        "run",
        "cloudcraft-mcp"
      ],
      "env": {
        "CLOUDCRAFT_API_KEY": "your-key-here"
      }
    }
  }
}

Starten Sie Claude Desktop neu. Der Entwickler-Tab sollte cloudcraft als verbunden anzeigen.

Umgebungsvariablen

Nutzungsbeispiele (in Claude)

Sobald der Server verbunden ist, können Sie Claude Dinge fragen wie:

"List my Cloudcraft blueprints and summarize what each represents."

"Export blueprint f0086b32-... as PNG and save it to my Desktop."

"Take the architecture I just designed and create a new Cloudcraft blueprint called 'Prod 2026'."

"Snapshot the EC2 instances in ap-northeast-2 for my connected AWS account."

Blueprint-Payload-Struktur

create_blueprint / update_blueprint akzeptieren das vollständige Cloudcraft data-Objekt. Ein minimaler Payload:

{
  "grid": "infinite",
  "projection": "isometric",
  "theme": {"base": "light"},
  "version": 6,
  "nodes": [
    {"id": "...", "type": "ec2", "mapPos": [3, 3], "region": "ap-northeast-2",
     "instanceType": "m7g", "instanceSize": "large", "platform": "linux"},
    {"id": "...", "type": "s3",  "mapPos": [1, 8], "region": "ap-northeast-2",
     "volumeType": "Standard", "dataGb": 100}
  ],
  "edges": [
    {"from": "...ec2-id...", "to": "...s3-id...", "type": "edge",
     "width": 2, "dashed": false, "endCap": "arrow"}
  ],
  "groups": [], "surfaces": [], "text": [], "icons": [],
  "connectors": [], "images": [], "disabledLayers": [],
  "shareDocs": false
}

Informationen zum vollständigen Knotentyp-Katalog und dienstspezifischen Feldern finden Sie in der Cloudcraft API-Dokumentation.

Entwicklung

uv sync --extra dev
uv run pytest            # unit tests (no network)
uv run ruff check .      # lint
uv run mypy src          # type check

Tests simulieren die HTTP-Ebene mit respx, sodass kein API-Schlüssel erforderlich ist.

Projektlayout

cloudcraft-mcp/
├── src/cloudcraft_mcp/
│   ├── __init__.py
│   ├── __main__.py         # python -m cloudcraft_mcp
│   ├── server.py           # MCP tool definitions (FastMCP)
│   ├── client.py           # CloudcraftClient — async httpx wrapper
│   ├── types.py            # TypedDicts for blueprint payloads
│   └── py.typed
├── tests/
│   └── test_client.py
├── server.py               # back-compat shim -> cloudcraft_mcp.server:main
├── pyproject.toml
├── LICENSE
└── README.md

Design-Hinweise

• Transport-/Logik-Trennung. client.py ist ein einfacher asynchroner HTTP-Client, den Sie aus Skripten oder CLI-Tools importieren können, ohne die MCP-Laufzeitumgebung zu laden. server.py verwaltet nur die MCP-Tool-Oberfläche.

• Bearer-Token-Authentifizierung. Die API von Cloudcraft erwartet Authorization: Bearer <key> (nicht Apikey). Der Client setzt dies automatisch.

• Keine Geheimnisse in Prozessargumenten. Der API-Schlüssel wird aus CLOUDCRAFT_API_KEY gelesen; übergeben Sie ihn niemals über die Befehlszeile.

• Fehlerbehandlung. Nicht-2xx-Antworten lösen einen CloudcraftError aus, wobei Status und Body erhalten bleiben und an der MCP-Grenze als RuntimeError neu verpackt werden, damit Claude eine lesbare Nachricht erhält.

Sicherheit

• API-Schlüssel gewähren vollen Lese-/Schreibzugriff auf Ihr Cloudcraft-Konto. Behandeln Sie sie als Geheimnisse und rotieren Sie sie regelmäßig.

• delete_blueprint ist nicht umkehrbar — wenn Sie Claude bitten, etwas zu löschen, seien Sie präzise bezüglich der Ziel-ID.

• Erstellen Sie für leseintensive Setups einen dedizierten Cloudcraft-Benutzer mit schreibgeschütztem Bereich (falls/sobald Cloudcraft bereichsbezogene Schlüssel hinzufügt) und verwenden Sie diesen Schlüssel für MCP.

Mitwirken

Issues und PRs sind willkommen unter https://github.com/hypark5540/cloudcraft-mcp. Bitte führen Sie ruff, mypy und pytest aus, bevor Sie etwas einreichen.

Lizenz

MIT — siehe LICENSE.

Verwandtes

• Cloudcraft API-Dokumentation

• Model Context Protocol Spezifikation

• awslabs/mcp — AWS-Sammlung von MCP-Servern

• modelcontextprotocol/servers — Referenzimplementierungen für MCP-Server