{
"markdown": "\n\n# cloudcraft-mcp\n\n[](https://github.com/hypark5540/cloudcraft-mcp/actions/workflows/ci.yml)\n[](https://codecov.io/gh/hypark5540/cloudcraft-mcp)\n[](https://pypi.org/project/cloudcraft-mcp/)\n[](https://www.npmjs.com/package/@hypark5540/cloudcraft-mcp)\n[](LICENSE)\n[](https://www.python.org/downloads/)\n\nUnofficial Model Context Protocol (MCP) server for\n[Cloudcraft](https://cloudcraft.co) — list, read, export, and build cloud\narchitecture blueprints from Claude Desktop and other MCP clients.\n\n## Features\n\nNine tools exposed to the MCP host:\n\n| Tool | Description |\n| ---- | ----------- |\n| `whoami` | Return the Cloudcraft user profile for the configured key. |\n| `list_blueprints` | List every blueprint in the account. |\n| `get_blueprint` | Fetch a blueprint's full node / edge JSON. |\n| `create_blueprint` | Create a new blueprint from a JSON payload. |\n| `update_blueprint` | Replace an existing blueprint's payload. |\n| `delete_blueprint` | Delete a blueprint (irreversible). |\n| `export_blueprint_image` | Render a blueprint to PNG / SVG / PDF / mxgraph on disk. |\n| `list_aws_accounts` | List AWS accounts connected for live-scan snapshots. |\n| `snapshot_aws` | Take a live-scan snapshot of one AWS service. |\n\n## Requirements\n\n- [uv](https://docs.astral.sh/uv/getting-started/installation/) for the\n recommended `uvx` and npm launchers\n- Node.js 22+ only when using the npm launcher\n- Cloudcraft API key — generate one at → User settings → API keys\n\n## Install\n\nUse an immutable version in client configuration so upgrades are deliberate.\n\n| Channel | Command |\n| ------- | ------- |\n| PyPI / uvx | `uvx --from cloudcraft-mcp==0.1.6 cloudcraft-mcp` |\n| pipx | `pipx run --spec cloudcraft-mcp==0.1.6 cloudcraft-mcp` |\n| npm / npx | `npx -y @hypark5540/cloudcraft-mcp@0.1.6` |\n| Docker / GHCR | `docker run --rm -i -e CLOUDCRAFT_API_KEY ghcr.io/hypark5540/cloudcraft-mcp:0.1.6` |\n| Claude Desktop | Download `cloudcraft-mcp.mcpb` from the matching GitHub release |\n\n`uvx` is delivered by the PyPI package; there is no separate uvx registry.\nThe npm package embeds the byte-identical Python wheel and invokes it through\n`uv`, so the npm path requires both Node.js and uv. It does not download code\nin a `postinstall` hook.\n\nFor development from a checkout:\n\n```bash\ngit clone https://github.com/hypark5540/cloudcraft-mcp.git\ncd cloudcraft-mcp\nexport CLOUDCRAFT_API_KEY='your-key-here'\nuv run --frozen cloudcraft-mcp # Ctrl+C to exit\n```\n\n## Claude Desktop integration\n\nInstall [uv](https://docs.astral.sh/uv/getting-started/installation/), then add\nthis entry to Claude Desktop's configuration. Prefer Claude's secret storage\nwhen available; the literal below is only a portable example.\n\n```json\n{\n \"mcpServers\": {\n \"cloudcraft\": {\n \"command\": \"uv\",\n \"args\": [\n \"tool\",\n \"run\",\n \"--isolated\",\n \"--from\",\n \"cloudcraft-mcp==0.1.6\",\n \"cloudcraft-mcp\"\n ],\n \"env\": {\n \"CLOUDCRAFT_API_KEY\": \"your-key-here\",\n \"CLOUDCRAFT_ENABLE_WRITES\": \"false\",\n \"CLOUDCRAFT_ENABLE_DELETES\": \"false\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop. The Developer tab should show `cloudcraft` as connected.\n\nSee [client setup](docs/clients.md) for Cursor, Gemini CLI, npm, Docker, and\nMCPB examples.\n\n### Environment variables\n\n| Name | Required | Default | Purpose |\n| ---- | -------- | ------- | ------- |\n| `CLOUDCRAFT_API_KEY` | yes | — | API key (Bearer). Generated in Cloudcraft User settings. |\n| `CLOUDCRAFT_BASE_URL` | no | `https://api.cloudcraft.co` | Override for proxies or future API versions. |\n| `CLOUDCRAFT_LOG_LEVEL` | no | `WARNING` | Stderr log verbosity (`DEBUG` / `INFO` / `WARNING` / `ERROR`). |\n| `CLOUDCRAFT_EXPORT_DIR` | no | private temp subdirectory | Directory that `export_blueprint_image` may write under. |\n| `CLOUDCRAFT_ENABLE_WRITES` | no | `false` | Permit `create_blueprint` and `update_blueprint`. |\n| `CLOUDCRAFT_ENABLE_DELETES` | no | `false` | Permit deletes when writes are also enabled. |\n| `CLOUDCRAFT_MAX_RESPONSE_BYTES` | no | `26214400` | Reject oversized Cloudcraft responses before they exhaust memory or disk. |\n\n## Usage examples (in Claude)\n\nOnce the server is connected, ask Claude things like:\n\n> *\"List my Cloudcraft blueprints and summarize what each represents.\"*\n\n> *\"Export blueprint `f0086b32-...` as PNG and save it to my Desktop.\"*\n\n> *\"Take the architecture I just designed and create a new Cloudcraft blueprint called 'Prod 2026'.\"*\n\n> *\"Snapshot the EC2 instances in `ap-northeast-2` for my connected AWS account.\"*\n\n## Blueprint payload shape\n\n`create_blueprint` / `update_blueprint` accept the full Cloudcraft `data` object. A minimal payload:\n\n```json\n{\n \"grid\": \"infinite\",\n \"projection\": \"isometric\",\n \"theme\": {\"base\": \"light\"},\n \"version\": 6,\n \"nodes\": [\n {\"id\": \"...\", \"type\": \"ec2\", \"mapPos\": [3, 3], \"region\": \"ap-northeast-2\",\n \"instanceType\": \"m7g\", \"instanceSize\": \"large\", \"platform\": \"linux\"},\n {\"id\": \"...\", \"type\": \"s3\", \"mapPos\": [1, 8], \"region\": \"ap-northeast-2\",\n \"volumeType\": \"Standard\", \"dataGb\": 100}\n ],\n \"edges\": [\n {\"from\": \"...ec2-id...\", \"to\": \"...s3-id...\", \"type\": \"edge\",\n \"width\": 2, \"dashed\": false, \"endCap\": \"arrow\"}\n ],\n \"groups\": [], \"surfaces\": [], \"text\": [], \"icons\": [],\n \"connectors\": [], \"images\": [], \"disabledLayers\": [],\n \"shareDocs\": false\n}\n```\n\nRefer to [Cloudcraft's API docs](https://developers.cloudcraft.co/) for the full node-type catalog and service-specific fields.\n\n## Development\n\n```bash\nuv sync --extra dev\nuv run pytest # unit tests (no network)\nuv run ruff check . # lint\nuv run mypy src # type check\n```\n\nTests mock the HTTP layer with [respx](https://lundberg.github.io/respx/) so no API key is required.\n\n#### Coverage\n\nCI uploads `coverage.xml` from the Python 3.12 matrix cell to\n[Codecov](https://codecov.io/gh/hypark5540/cloudcraft-mcp). The project gate\nis **80% or higher** — a PR that drops overall or patch coverage by more\nthan 1 percentage point below that line fails the Codecov check\n(`codecov.yml`).\n\nRun the same report locally:\n\n```bash\nuv run pytest --cov=cloudcraft_mcp --cov-report=term-missing --cov-report=xml\n```\n\n### Project layout\n\n```\ncloudcraft-mcp/\n├── src/cloudcraft_mcp/\n│ ├── __init__.py\n│ ├── __main__.py # python -m cloudcraft_mcp\n│ ├── server.py # MCP tool definitions (FastMCP)\n│ ├── client.py # CloudcraftClient — async httpx wrapper\n│ ├── types.py # TypedDicts for blueprint payloads\n│ └── py.typed\n├── tests/\n│ └── test_client.py\n├── bin/cloudcraft-mcp.mjs # npm-to-uv launcher\n├── mcpb/manifest.json # Claude Desktop bundle metadata\n├── server.json # official MCP Registry metadata\n├── package.json # npm distribution\n├── server.py # back-compat shim -> cloudcraft_mcp.server:main\n├── pyproject.toml\n├── LICENSE\n└── README.md\n```\n\n## Design notes\n\n- **Transport / logic split.** `client.py` is a plain async HTTP client you can import from scripts or CLI tools without pulling the MCP runtime. `server.py` only owns the MCP tool surface.\n- **Bearer-token auth.** Cloudcraft's API expects `Authorization: Bearer ` (not `Apikey`). The client sets this automatically.\n- **No secrets in process args.** The API key is read from `CLOUDCRAFT_API_KEY`; never pass it on the command line.\n- **One implementation.** PyPI, npm, MCPB, and the container all launch the\n same versioned Python package rather than maintaining language-specific forks.\n- **Error surface.** Non-2xx responses raise `CloudcraftError` with status and body preserved, re-wrapped as `RuntimeError` at the MCP boundary so Claude sees a readable message.\n\n## Security\n\n- API keys grant full read / write over your Cloudcraft account. Treat them as secrets and rotate regularly.\n- MCP tool annotations mark read-only tools and mutating/destructive tools so compatible hosts can present better approval prompts. These annotations are hints, not an enforcement layer.\n- Environment gates and exact-ID delete confirmation are defense in depth, not\n an interactive approval workflow; keep the MCP host's tool approval UX enabled.\n- Cloudcraft mutations are disabled by default. Set `CLOUDCRAFT_ENABLE_WRITES=true`\n only for clients that need create/update access. Deletes additionally require\n `CLOUDCRAFT_ENABLE_DELETES=true` and an exact repeated blueprint ID on every call.\n- `delete_blueprint` is irreversible — when asking Claude to delete, be explicit about the target id.\n- `export_blueprint_image` writes are sandboxed under `CLOUDCRAFT_EXPORT_DIR`\n (a process-private temporary subdirectory by default) and refuse to overwrite\n existing files unless `overwrite=True`.\n- For read-heavy setups, create a dedicated Cloudcraft user with read-only scope (if/when Cloudcraft adds scoped keys) and use that key for MCP.\n- Supported versions and private reporting instructions are in\n [SECURITY.md](SECURITY.md); data flow is documented in [PRIVACY.md](PRIVACY.md).\n\n## Contributing\n\nIssues and PRs welcome at . Please run `ruff`, `mypy`, and `pytest` before submitting.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Related\n\n- [Cloudcraft API documentation](https://developers.cloudcraft.co/)\n- [Model Context Protocol specification](https://modelcontextprotocol.io/)\n- [awslabs/mcp](https://github.com/awslabs/mcp) — AWS's collection of MCP servers\n- [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) — reference MCP server implementations\n",
"bytes": 10094,
"sha": "7412cbb0253496464b2e62a9d602388c2093ff95644710a0166c51762302ec65",
"repo_slug": "hypark5540/cloudcraft-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_hypark5540_cloudcraft_mcp_08694c6a/readme"
}