Cloudcraft MCP

cloudcraft-mcp

非官方的 Cloudcraft 模型上下文协议（MCP）服务，可通过 Claude Desktop 和其他 MCP 客户端列出、读取、导出并构建云架构蓝图。

功能

向 MCP 主机提供 13 种工具：

工具	描述
whoami	返回配置密钥对应的 Cloudcraft 用户资料。
list_blueprints	列出账户中的所有蓝图。
get_blueprint	获取蓝图完整的节点 / 边 JSON。
create_blueprint	根据 JSON 载荷创建新蓝图。
update_blueprint	替换现有蓝图的载荷。
delete_blueprint	删除蓝图（不可撤销）。
export_blueprint_image	将蓝图渲染为 PNG / SVG / PDF / mxgraph 并保存到磁盘。
export_blueprint_budget	将蓝图成本估算导出为 CSV / XLSX 并保存到磁盘。
list_teams	列出关联到该账户的团队。
list_aws_accounts	列出已连接、可用于实时扫描快照的 AWS 账户。
snapshot_aws	实时扫描一个 AWS 区域并生成蓝图 JSON（可选 filter / exclude）。
list_azure_accounts	列出已连接、可用于实时扫描快照的 Azure 账户。
snapshot_azure	实时扫描一个 Azure 区域并生成蓝图 JSON（可选 filter / exclude）。

要求

• uv：用于推荐的 uvx 和 npm 启动器
• 仅在使用 npm 启动器时需要 Node.js 22+
• Cloudcraft API 密钥——前往 https://app.cloudcraft.co/ → User settings → API keys 生成

安装

在客户端配置中使用不可变版本，以便有计划地升级。

渠道	命令
PyPI / uvx	uvx --from cloudcraft-mcp==0.1.8 cloudcraft-mcp
pipx	pipx run --spec cloudcraft-mcp==0.1.8 cloudcraft-mcp
npm / npx	npx -y @hypark5540/[email protected]
Docker / GHCR	docker run --rm -i -e CLOUDCRAFT_API_KEY ghcr.io/hypark5540/cloudcraft-mcp:0.1.8
Claude Desktop	从对应的 GitHub release 下载 cloudcraft-mcp.mcpb

uvx 由 PyPI 软件包提供；没有单独的 uvx 注册表。 npm 软件包内含字节完全一致的 Python wheel，并通过 uv 调用，因此使用 npm 方式需要同时安装 Node.js 和 uv。它不会在 postinstall 钩子中下载代码。

从代码检出目录进行开发：

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

Claude Desktop 集成

安装 uv，然后将此条目添加到 Claude Desktop 的配置中。若可用，请优先使用 Claude 的密钥存储；下方的明文仅为便于移植的示例。

{
  "mcpServers": {
    "cloudcraft": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--isolated",
        "--from",
        "cloudcraft-mcp==0.1.8",
        "cloudcraft-mcp"
      ],
      "env": {
        "CLOUDCRAFT_API_KEY": "your-key-here",
        "CLOUDCRAFT_ENABLE_WRITES": "false",
        "CLOUDCRAFT_ENABLE_DELETES": "false"
      }
    }
  }
}

重启 Claude Desktop。Developer 选项卡中应显示 cloudcraft 已连接。

有关 Cursor、Gemini CLI、npm、Docker 和 MCPB 示例，请参阅客户端设置。

环境变量

名称	必填	默认值	用途
CLOUDCRAFT_API_KEY	是	—	API 密钥（Bearer）。在 Cloudcraft 用户设置中生成。
CLOUDCRAFT_BASE_URL	否	https://api.cloudcraft.co	用于代理或未来 API 版本的覆盖地址。
CLOUDCRAFT_LOG_LEVEL	否	WARNING	Stderr 日志详细程度（DEBUG / INFO / WARNING / ERROR）。
CLOUDCRAFT_EXPORT_DIR	否	私有临时子目录	export_blueprint_image 可写入的目录。
CLOUDCRAFT_ENABLE_WRITES	否	false	允许使用 create_blueprint 和 update_blueprint。
CLOUDCRAFT_ENABLE_DELETES	否	false	在同时启用写入时允许删除。
CLOUDCRAFT_MAX_RESPONSE_BYTES	否	26214400	在 Cloudcraft 响应耗尽内存或磁盘前拒绝过大的响应。

用法示例（在 Claude 中）

连接服务后，可以向 Claude 提出以下请求：

“列出我的 Cloudcraft 蓝图，并总结每个蓝图代表的内容。”

“将蓝图 f0086b32-... 导出为 PNG 并保存到我的桌面。”

“把我刚设计的架构创建为一个名为 ‘Prod 2026’ 的新 Cloudcraft 蓝图。”

“对我已连接的 AWS 账户执行 ap-northeast-2 快照，并排除安全组。”

“将蓝图 f0086b32-... 的月度预算导出为 EUR 格式的 CSV。”

蓝图负载结构

create_blueprint / update_blueprint 接受完整的 Cloudcraft data 对象。最小负载示例：

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

完整的节点类型目录和特定服务字段，请参阅 Cloudcraft 的 API 文档。

开发

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

测试使用 respx 模拟 HTTP 层，因此无需 API 密钥。

覆盖率

CI 会将 Python 3.12 矩阵任务中的 coverage.xml 上传至 Codecov。项目门槛为 80% 或更高——如果 PR 导致整体覆盖率或补丁覆盖率比该门槛低 超过 1 个百分点，便会导致 Codecov 检查失败 （codecov.yml）。

在本地运行相同的报告：

uv run pytest --cov=cloudcraft_mcp --cov-report=term-missing --cov-report=xml

项目结构

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
├── bin/cloudcraft-mcp.mjs # npm-to-uv launcher
├── mcpb/manifest.json     # Claude Desktop bundle metadata
├── server.json            # official MCP Registry metadata
├── package.json           # npm distribution
├── server.py               # back-compat shim -> cloudcraft_mcp.server:main
├── pyproject.toml
├── LICENSE
└── README.md

设计说明

• 传输 / 逻辑分离。 client.py 是一个纯异步 HTTP 客户端，可从脚本或命令行工具中导入，而无需引入 MCP 运行时。server.py 仅负责 MCP 工具接口。
• Bearer 令牌身份验证。 Cloudcraft 的 API 要求使用 Authorization: Bearer <key>（而非 Apikey）。客户端会自动设置此项。
• 进程参数中不包含机密信息。 API 密钥从 CLOUDCRAFT_API_KEY 读取；切勿通过命令行传递。
• 单一实现。 PyPI、npm、MCPB 和容器均启动同一版本的 Python 软件包，而不是维护特定语言的分支。
• 错误处理。 非 2xx 响应会抛出 CloudcraftError，并保留状态和响应正文；在 MCP 边界处会重新包装为 RuntimeError，以便 Claude 显示易于理解的消息。

安全性

• API 密钥拥有对 Cloudcraft 账户的完整读写权限。请将其视为机密信息并定期轮换。
• MCP 工具注释会标记只读工具和会修改数据或具有破坏性的工具，以便兼容的宿主提供更完善的审批提示。这些注释仅供参考，并非强制执行机制。
• 环境开关和精确 ID 删除确认属于纵深防御，并非交互式审批工作流；请保持启用 MCP 宿主的工具审批体验。
• 默认禁用 Cloudcraft 修改操作。仅对需要创建/更新权限的客户端设置 CLOUDCRAFT_ENABLE_WRITES=true。删除操作还需要设置 CLOUDCRAFT_ENABLE_DELETES=true，并且每次调用都必须重复提供完全匹配的蓝图 ID。
• delete_blueprint 操作不可撤销——让 Claude 删除时，请明确指定目标 ID。
• export_blueprint_image 的写入操作受限于 CLOUDCRAFT_EXPORT_DIR（默认位于进程私有的临时子目录），并且除非设置 overwrite=True，否则不会覆盖现有文件。
• 对于以读取为主的配置，请创建专用的 Cloudcraft 用户并授予只读范围（如果/当 Cloudcraft 添加范围限定密钥时），并将该密钥用于 MCP。
• 支持的版本和私密问题报告说明见 SECURITY.md；数据流记录在 PRIVACY.md 中。

贡献

欢迎在 https://github.com/hypark5540/cloudcraft-mcp 提交问题和 PR。提交前请运行 ruff、mypy 和 pytest。

许可证

MIT — 详见 LICENSE。

相关资源

• Cloudcraft API 文档
• 模型上下文协议规范
• awslabs/mcp — AWS 的 MCP 服务集合
• modelcontextprotocol/servers — MCP 服务参考实现