cloudcraft-mcp

Сервер Model Context Protocol (MCP) для Cloudcraft.co — позволяет просматривать, читать, экспортировать и создавать чертежи облачной архитектуры из Claude Desktop и других MCP-клиентов.

Возможности

Девять инструментов, доступных для MCP-хоста:

Related MCP server: AWS MCP Server

Требования

• Python 3.10+

• uv (brew install uv)

• API-ключ Cloudcraft — создайте его на странице https://app.cloudcraft.co/ → User settings → API keys

Установка

Клонируйте репозиторий и позвольте uv разрешить зависимости при первом запуске — явный шаг установки не требуется.

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

Отредактируйте файл ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или его эквивалент для вашей платформы:

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

Перезапустите Claude Desktop. На вкладке Developer должно появиться подключение cloudcraft.

Переменные окружения

Примеры использования (в Claude)

После подключения сервера вы можете спрашивать Claude о следующем:

"Перечисли мои чертежи Cloudcraft и кратко опиши, что представляет каждый из них."

"Экспортируй чертеж f0086b32-... в формате PNG и сохрани его на рабочий стол."

"Возьми архитектуру, которую я только что спроектировал, и создай новый чертеж Cloudcraft под названием 'Prod 2026'."

"Сделай снимок экземпляров EC2 в регионе ap-northeast-2 для моего подключенного аккаунта AWS."

Структура полезной нагрузки чертежа

create_blueprint / update_blueprint принимают полный объект data Cloudcraft. Минимальная полезная нагрузка:

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

Обратитесь к документации API Cloudcraft для получения полного каталога типов узлов и полей, специфичных для сервисов.

Разработка

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

Тесты имитируют HTTP-слой с помощью respx, поэтому API-ключ не требуется.

Структура проекта

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

Заметки по проектированию

• Разделение транспорта и логики. client.py — это простой асинхронный HTTP-клиент, который можно импортировать из скриптов или инструментов командной строки без использования среды выполнения MCP. server.py отвечает только за интерфейс инструментов MCP.

• Авторизация через Bearer-токен. API Cloudcraft ожидает Authorization: Bearer <key> (не Apikey). Клиент устанавливает это автоматически.

• Никаких секретов в аргументах процесса. API-ключ считывается из CLOUDCRAFT_API_KEY; никогда не передавайте его в командной строке.

• Обработка ошибок. Ответы, отличные от 2xx, вызывают CloudcraftError с сохранением статуса и тела ответа, которые переупаковываются как RuntimeError на границе MCP, чтобы Claude мог отобразить понятное сообщение.

Безопасность

• API-ключи предоставляют полный доступ на чтение/запись к вашему аккаунту Cloudcraft. Относитесь к ним как к секретным данным и регулярно обновляйте их.

• delete_blueprint необратим — при запросе к Claude на удаление четко указывайте целевой ID.

• Для сценариев с интенсивным чтением создайте отдельного пользователя Cloudcraft с правами только на чтение (если/когда Cloudcraft добавит ключи с ограниченными правами) и используйте этот ключ для MCP.

Участие в разработке

Вопросы и PR приветствуются на https://github.com/hypark5540/cloudcraft-mcp. Пожалуйста, запустите ruff, mypy и pytest перед отправкой.

Лицензия

MIT — см. LICENSE.

См. также

• Документация API Cloudcraft

• Спецификация Model Context Protocol

• awslabs/mcp — коллекция MCP-серверов от AWS

• modelcontextprotocol/servers — эталонные реализации MCP-серверов