cloudcraft-mcp

Servidor del Protocolo de Contexto de Modelo (MCP) para Cloudcraft.co: permite listar, leer, exportar y crear planos de arquitectura en la nube desde Claude Desktop y otros clientes MCP.

Características

Nueve herramientas expuestas al host MCP:

Related MCP server: AWS MCP Server

Requisitos

• Python 3.10+

• uv (brew install uv)

• Clave de API de Cloudcraft: genere una en https://app.cloudcraft.co/ → User settings → API keys

Instalación

Clone el repositorio y deje que uv resuelva las dependencias en la primera ejecución; no se requiere un paso de instalación explícito.

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

Integración con Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en su plataforma:

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

Reinicie Claude Desktop. La pestaña Developer debería mostrar cloudcraft como conectado.

Variables de entorno

Ejemplos de uso (en Claude)

Una vez que el servidor esté conectado, pregunte a Claude cosas como:

"Lista mis planos de Cloudcraft y resume lo que representa cada uno."

"Exporta el plano f0086b32-... como PNG y guárdalo en mi escritorio."

"Toma la arquitectura que acabo de diseñar y crea un nuevo plano de Cloudcraft llamado 'Prod 2026'."

"Realiza una instantánea de las instancias EC2 en ap-northeast-2 para mi cuenta de AWS conectada."

Forma de la carga útil del plano

create_blueprint / update_blueprint aceptan el objeto data completo de Cloudcraft. Una carga útil mínima:

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

Consulte la documentación de la API de Cloudcraft para ver el catálogo completo de tipos de nodos y campos específicos del servicio.

Desarrollo

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

Las pruebas simulan la capa HTTP con respx, por lo que no se requiere una clave de API.

Estructura del proyecto

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

Notas de diseño

• División de transporte/lógica. client.py es un cliente HTTP asíncrono simple que puede importar desde scripts o herramientas CLI sin necesidad de cargar el tiempo de ejecución de MCP. server.py solo gestiona la superficie de herramientas de MCP.

• Autenticación con token Bearer. La API de Cloudcraft espera Authorization: Bearer <key> (no Apikey). El cliente lo configura automáticamente.

• Sin secretos en los argumentos del proceso. La clave de API se lee desde CLOUDCRAFT_API_KEY; nunca la pase por la línea de comandos.

• Superficie de error. Las respuestas que no son 2xx generan un CloudcraftError con el estado y el cuerpo preservados, reempaquetados como RuntimeError en el límite de MCP para que Claude vea un mensaje legible.

Seguridad

• Las claves de API otorgan acceso total de lectura/escritura a su cuenta de Cloudcraft. Trátelas como secretos y rótelas regularmente.

• delete_blueprint es irreversible; al pedirle a Claude que elimine algo, sea explícito sobre el ID de destino.

• Para configuraciones con mucha lectura, cree un usuario de Cloudcraft dedicado con alcance de solo lectura (si Cloudcraft añade claves con alcance) y use esa clave para MCP.

Contribución

Las incidencias y PR son bienvenidas en https://github.com/hypark5540/cloudcraft-mcp. Por favor, ejecute ruff, mypy y pytest antes de enviar.

Licencia

MIT: consulte LICENSE.

Relacionado

• Documentación de la API de Cloudcraft

• Especificación del Protocolo de Contexto de Modelo

• awslabs/mcp: colección de servidores MCP de AWS

• modelcontextprotocol/servers: implementaciones de referencia de servidores MCP