Architecture Diagrams

架构图 MCP 服务

arch-diagram-mcp 是一个 MCP 服务，可生成、审查和导入 AWS、Azure 和 Google Cloud 的云架构图。它使用官方提供商图标，约有 1,800 个，涵盖 Kubernetes、本地部署以及 PostgreSQL、Redis、Kafka 和 Nginx 等 SaaS 服务。图表通过 Graphviz 渲染为 PNG、独立 SVG、PDF 或 JPG。

你可以设计新的架构，也可以将现有架构绘制成图：既可以从 Terraform 绘制，也可以直接从正在运行的 Google Cloud 项目自带的资源清单绘制，并保留真实的资源名称，无论这些资源是如何创建的。

快速开始。 安装 Graphviz，然后通过以下任一方式将服务添加到 MCP 客户端：

来源	命令
PyPI，使用 uv	uvx arch-diagram-mcp
PyPI，使用 pipx	pipx install arch-diagram-mcp，然后运行 arch-diagram-mcp
npm（通过 uv 或 pipx 启动 PyPI 软件包）	npx -y arch-diagram-mcp

例如，在 Claude Code 中：claude mcp add architecture-diagrams -s user -- uvx arch-diagram-mcp。 它也已收录在 MCP Registry 中，名称为 io.github.apatilgtn/architecture-diagrams。

作为开发者使用？ 请从开发者指南开始。指南介绍了如何在你的计算机上或连接到共享团队服务时，连接 Claude Code、VS Code、Cursor 或 Claude Desktop，并提供示例提示词。本 README 的其余部分介绍如何运行和配置服务。

示例

这些是捆绑的模板和 Terraform 示例，呈现效果与服务端生成的完全一致。 评分来自 review_architecture。点击图表可查看全尺寸图片。

Azure Web 应用，中心辐射式，带温备灾备 azure_webapp_hub_spoke，评分 94（A）	Azure AKS 微服务 azure_aks_microservices，评分 97（A）
AWS 三层 Web 应用 aws_three_tier，评分 86（B）	AWS 无服务器事件驱动架构 aws_serverless_event_driven，评分 100（A）
GCP GKE 微服务 gcp_gke_microservices，评分 97（A）	GCP 无服务器与数据平台 gcp_serverless_data，评分 81（B）
从 Terraform 导入 diagram_from_terraform，基于 examples/aws_plan.json，评分 73（C）	根据清单绘制的运行中 GCP 平台 diagram_from_inventory，基于真实导出数据（已替换标识符），评分 67（C）

如需重新生成，请运行 python scripts/render_samples.py。

该服务还在 Google Cloud 上通过端到端测试：使用带签名 URL 的私有存储桶，以及带两层身份验证的私有 Cloud Run 服务。请参阅 docs/CLOUD_TESTING.md，了解测试方法、检查内容以及发现的 bug。

工具

工具	功能
search_icons(query, provider?, limit?)	按服务名称或别名（ecs、s3、aks、cloud run、redis）搜索图标并排序
list_icon_categories(provider)	列出某个提供商的所有类别和服务
list_templates(provider?) / get_template(id)	以可编辑规格的形式返回内置参考架构
validate_diagram(spec)	无需渲染即可检查规格：图标 ID（含建议）、引用、嵌套循环和限制
generate_architecture_diagram(spec)	渲染图表；返回文件路径、JSON 摘要和内嵌 PNG 预览
review_architecture(spec)	执行基于启发式规则的 Well-Architected 评审，并返回 0–100 分的评分、等级，以及包含建议的发现
diagram_from_terraform(title, terraform_json | path, ...)	根据 terraform show -json 输出（计划或状态）或原始 .tfstate 文件生成图表
diagram_from_inventory(title, inventory_json | path, projects?, regions?, labels?, ...)	根据 Cloud Asset Inventory 导出文件，绘制 Google Cloud 中已在运行的资源，并显示实际名称
server_info()	报告版本、Graphviz 状态、图标数量、输出目录和限制

此外还有一个提示词：design_architecture(provider, workload, requirements)。它会引导模型选择模板、搜索图标、验证、渲染和评审。

内置模板

• aws_three_tier
• aws_serverless_event_driven
• azure_webapp_hub_spoke
• azure_aks_microservices
• gcp_serverless_data
• gcp_gke_microservices

每个模板都经过测试，可通过验证和渲染，且评审结果中没有严重或高严重性发现。

图表规格

{
  "title": "My App",
  "direction": "LR",
  "theme": "light",
  "output_formats": ["png", "svg"],
  "clusters": [{"id": "vpc", "label": "VPC 10.0.0.0/16"}, {"id": "app", "label": "Private subnet", "parent": "vpc"}],
  "nodes": [{"id": "api", "type": "aws.compute.ECS", "label": "orders-api", "cluster": "app"}],
  "edges": [{"source": "alb", "target": "api", "label": "HTTPS", "style": "dashed"}]
}

评审规则

支柱	规则
安全性	互联网 → 数据存储（严重）；互联网 → 无网关的计算资源（高）；没有 WAF；没有密钥/KMS；没有身份提供商；数据存储位于网络边界之外；没有出口控制
可靠性	VM 没有负载均衡器；单一区域；没有备份；同步调用链过深
卓越运营	没有监控；没有 CI/CD；组件未连接
性能效率	公共流量没有 CDN；没有缓存层

这些规则只能识别图表中显示的内容。请将评审发现视为评审提示，而非配置错误的证明。

Terraform 导入

terraform show -json plan.out > plan.json 的效果最佳，因为计划包含配置中的引用。

• 已映射资源： 约 140 种 AWS、Azure 和 GCP 资源类型会转换为节点。
• 边界： VPC/VNet、子网、资源组和 Container Apps 环境资源会转换为嵌套集群。节点会放置在它们所引用的最具体边界中，可以是直接引用，也可以通过 NIC 引用。
• 边： 资源之间的引用会转换为边，并解析模块输出。
• 推断的边： 经过管线资源的链接会转换为虚线边，方向为 edge → compute → messaging → data。管线资源包括侦听器、目标组、NIC、角色分配、Front Door 来源和后端服务。
• 未映射类型： 结果会列出这些类型，方便你查看哪些内容未纳入。

库存导入（Google Cloud）

对于已经运行的基础设施，无论它是通过何种方式创建的（控制台、gcloud、脚本、 Terraform、Pulumi），都可以导出项目的库存并传递给 diagram_from_inventory：

gcloud asset list --project <project-id> --content-type resource \
  --asset-types "$(arch-diagram-mcp --gcp-asset-types)" --format json > assets.json

--gcp-asset-types 会列出导入器使用的 54 种资产类型。只请求这些类型可以缩小导出文件：某个测试项目的导出文件从 4.4 MB 缩减到 535 KB，生成的图表保持不变。调用方需要具备 roles/cloudasset.viewer 角色，并启用 Cloud Asset API。

• **名称：**每个节点都会保留其真实名称。第二行会补充详细信息，例如数据库版本、 机器类型、入口设置、副本数或 cron 计划。
• **边界：**项目 › VPC › 子网 › GKE 集群 › Namespace。由其他项目拥有的共享 VPC 网络会绘制在该项目下。使用直接 VPC 出口的 Cloud Run 会显示在其子网中。
• 根据配置生成的边：
  • 注释和环境变量中引用的 Cloud SQL、密钥、KMS、Pub/Sub、存储桶和 Redis；
  • 与其所属 Cloud Run 服务或函数匹配的 URL（推送订阅、Scheduler 目标、环境变量）；
  • 负载均衡器链（转发规则 › 代理 › URL 映射 › 后端 › NEG、存储桶或 MIG），以及路径规则、CDN 和 Cloud Armor；
  • Eventarc 触发器、死信主题、BigQuery 和 Cloud Storage 订阅、VPC 连接器。
• **省略的杂项：**GKE 系统 Namespace 和节点、MIG 成员 VM（绘制为一个 MIG）、Cloud Functions 自带的 Run 服务、构建和暂存存储桶、路由、防火墙和 RBAC 对象。
• 筛选器：projects 和 regions 是硬性限制。labels（例如 {"app": "payments"}） 会筛选资源及其关联资源（默认启用 include_neighbors）。
• **限制：**无法识别仅存在于应用代码中的调用。结果会返回规范，因此你可以添加这些边并重新渲染。环境变量中发现的外部主机会列在 external_hosts 中。

接受的格式：gcloud asset list JSON（推荐）、gcloud asset export 换行分隔的 JSON，以及 gcloud asset search-all-resources --read-mask='*' JSON。Azure Resource Graph 和 AWS 库存支持计划中。

安装

需要 Python 3.11+ 和 Graphviz。

winget install Graphviz.Graphviz        # Linux: apt install graphviz   macOS: brew install graphviz
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
.venv\Scripts\python -m pytest            # 85 tests

注册到 Claude Code（stdio）

claude mcp add architecture-diagrams -s user `
  -e ARCH_DIAGRAM_OUTPUT_DIR=C:\Devops-Projects\Architecture-diagram-mcp\output `
  -- C:\Devops-Projects\Architecture-diagram-mcp\.venv\Scripts\python.exe -m arch_diagram_mcp

作为共享 HTTP 服务运行

docker build -t arch-diagram-mcp:1.2.0 .
docker run -d -p 8000:8000 -v diagrams:/data \
  -e ARCH_DIAGRAM_AUTH_TOKENS="ci=$(openssl rand -hex 32),platform-team=$(openssl rand -hex 32)" \
  -e ARCH_DIAGRAM_PUBLIC_BASE_URL=https://diagrams.internal.example.com \
  -e ARCH_DIAGRAM_URL_SIGNING_KEY=$(openssl rand -hex 32) \
  -e ARCH_DIAGRAM_ALLOWED_HOSTS="diagrams.internal.example.com:*" \
  arch-diagram-mcp:1.2.0

客户端使用 Authorization: Bearer <token> 连接到 https://<host>/mcp。GET /healthz 无需身份验证，可用作探测端点。服务以无状态方式运行，因此可以在负载均衡器后水平扩展。所有副本必须共用 ARCH_DIAGRAM_URL_SIGNING_KEY，这样任何副本都可以提供任何链接。

身份验证

模式	设置	审计日志中的身份	角色
token	ARCH_DIAGRAM_AUTH_TOKENS="name=secret,..."	令牌名称	完全访问权限
oidc	ARCH_DIAGRAM_OIDC_ISSUER + ARCH_DIAGRAM_OIDC_AUDIENCE	preferred_username / upn / email，以 oid/sub 为键	ARCH_DIAGRAM_READER_ROLE、ARCH_DIAGRAM_AUTHOR_ROLE

令牌模式。 可同时启用多个命名令牌。轮换令牌时，先添加新令牌、部署客户端，然后移除旧令牌。每个令牌必须至少包含 16 个字符。

OIDC 模式。 服务会根据签发方发布的签名密钥（JWKS，可通过发现机制查找，或使用 ARCH_DIAGRAM_OIDC_JWKS_URI 设置）验证 JWT。它会检查：

• 签名（仅限非对称算法：不允许 HS*，也不允许 none）；
• iss 和 aud；
• exp 和 nbf，允许 60 s 的误差；
• 可选的 ARCH_DIAGRAM_OIDC_REQUIRED_SCOPES。

角色取自 roles 声明（Entra 应用角色）和 scp 范围声明：

• 读取者： 搜索、模板、验证、审核。
• 作者： 还可以渲染，以及导入 Terraform 或云资源清单。作者角色包含读取者权限。
• 如果未设置这两个角色变量中的任何一个，则任何有效令牌都拥有完全访问权限。

服务会在 /.well-known/oauth-protected-resource 发布 RFC 9728 元数据，并在每个 401 响应中提供该地址，以便 MCP 客户端发现授权服务器。

Entra ID 示例：

1. 注册一个 API 应用，其应用程序 ID URI 为 api://arch-diagrams。
2. 在其清单中设置 accessTokenAcceptedVersion: 2。
3. 添加应用角色 Diagrams.Reader 和 Diagrams.Author，并将它们分配给组。
4. 配置服务：

ARCH_DIAGRAM_OIDC_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
ARCH_DIAGRAM_OIDC_AUDIENCE=api://arch-diagrams      # v2 tokens may carry the app's client id instead; list both
ARCH_DIAGRAM_READER_ROLE=Diagrams.Reader
ARCH_DIAGRAM_AUTHOR_ROLE=Diagrams.Author

Entra ID 不支持动态客户端注册。客户端可以使用预先注册的客户端应用，也可以传入已有令牌，例如 az account get-access-token --resource api://arch-diagrams。

构件存储

通过 HTTP 访问时，响应中包含下载链接，而不是服务端文件路径：

ARCH_DIAGRAM_STORAGE	链接	凭据
local（默认）	https://<PUBLIC_BASE_URL>/artifacts/<file>?exp=..&sig=..，由此服务提供并使用 HMAC 签名	ARCH_DIAGRAM_URL_SIGNING_KEY
s3	SigV4 预签名 GET；对象使用 SSE-S3 加密，或在设置 ARCH_DIAGRAM_S3_KMS_KEY_ID 时使用 SSE-KMS 加密	标准 AWS 凭据链（IRSA、实例角色、环境变量、配置文件）
azure	只读、仅限 HTTPS 的 SAS。通过 Entra ID 和 ARCH_DIAGRAM_AZURE_ACCOUNT_URL 使用用户委托密钥，或通过 AZURE_STORAGE_CONNECTION_STRING 使用帐户密钥	托管身份 / 工作负载身份需要 Storage Blob Data Contributor
gcs	V4 签名 URL。使用服务帐户密钥在本地签名，或通过工作负载身份使用 IAM signBlob	需要 Storage Object Creator 和 Service Account Token Creator

• 对象键： <prefix>/<yyyy>/<mm>/<dd>/<sha256(caller)[:16]>/<file>。文件按调用方隔离，对象键中绝不包含用户名。
• 链接有效期： 由 ARCH_DIAGRAM_URL_TTL_S 设置，默认为 1 h，最长为 7 天。
• 清理： 设置 ARCH_DIAGRAM_DELETE_LOCAL_AFTER_UPLOAD=true 后，云端上传成功时会删除本地副本。对于云对象，请使用存储桶生命周期规则。
• 提供的 SVG： 使用 Content-Security-Policy: sandbox 和 nosniff 发送。
• Terraform 路径： diagram_from_terraform(path=...) 在 HTTP 访问时处于禁用状态，因此远程调用方无法读取服务端文件。

配置（环境变量）

变量	默认值	用途
ARCH_DIAGRAM_OUTPUT_DIR	~/architecture-diagrams	图表的写入位置
ARCH_DIAGRAM_INPUT_ROOTS	cwd + 输出目录	以 os.pathsep 分隔的目录，diagram_from_terraform(path=...) 可从中读取
ARCH_DIAGRAM_MAX_NODES / _MAX_EDGES / _MAX_CLUSTERS	300 / 800 / 100	规格大小限制
ARCH_DIAGRAM_RENDER_TIMEOUT_S	60	Graphviz 运行超过此秒数后会被终止
ARCH_DIAGRAM_MAX_TERRAFORM_BYTES	25 MB	Terraform 输入大小限制
ARCH_DIAGRAM_RETENTION_DAYS	0（永久保留）	删除早于 N 天的生成文件
ARCH_DIAGRAM_KEEP_DOT_SOURCE	true	保留 .dot 文件以供手动编辑
ARCH_DIAGRAM_INLINE_PNG_MAX_BYTES	4 MB	超出此大小的 PNG 仅返回路径
ARCH_DIAGRAM_FONT	auto	字体系列；auto 在 Windows 上选择 Segoe UI，在 macOS 上选择 Helvetica Neue，在 Linux 上选择 DejaVu Sans
ARCH_DIAGRAM_PNG_DPI	144	PNG/JPG 分辨率（72–300）
ARCH_DIAGRAM_LOG_LEVEL	INFO	JSON 日志写入 stderr，每次工具调用记录一行审计日志
ARCH_DIAGRAM_HTTP_HOST / _HTTP_PORT	127.0.0.1 / 8000	HTTP 绑定地址和端口
ARCH_DIAGRAM_AUTH_MODE	auto	none / token / oidc；根据下方变量推断
ARCH_DIAGRAM_AUTH_TOKENS	–	命名的 bearer token，格式为 name=secret,...（仍支持旧版单一变量 ARCH_DIAGRAM_AUTH_TOKEN）
ARCH_DIAGRAM_OIDC_ISSUER / _OIDC_AUDIENCE / _OIDC_JWKS_URI / _OIDC_REQUIRED_SCOPES	–	OIDC 验证
ARCH_DIAGRAM_READER_ROLE / _AUTHOR_ROLE	–	RBAC 的角色名称（OIDC）
ARCH_DIAGRAM_PUBLIC_BASE_URL	–	外部 URL；用于下载链接和 OAuth 元数据
ARCH_DIAGRAM_STORAGE	local	local / s3 / azure / gcs
ARCH_DIAGRAM_STORAGE_BUCKET / _STORAGE_PREFIX	– / diagrams/	存储桶或容器，以及键前缀
ARCH_DIAGRAM_S3_REGION / _S3_KMS_KEY_ID / _AZURE_ACCOUNT_URL	–	后端特定配置
ARCH_DIAGRAM_URL_TTL_S	3600	下载链接有效期（60 s–7 天）
ARCH_DIAGRAM_URL_SIGNING_KEY	每个进程随机生成	本地链接的 HMAC 密钥；至少 32 个字符；多个副本之间应共享
ARCH_DIAGRAM_DELETE_LOCAL_AFTER_UPLOAD	false	云端上传后删除本地文件
ARCH_DIAGRAM_ALLOWED_HOSTS / _ALLOWED_ORIGINS	–	以逗号分隔的 Host/Origin 允许列表（防范 DNS 重绑定）
ARCH_DIAGRAM_ALLOW_UNAUTHENTICATED	false	允许在没有 token 的情况下绑定到非环回地址（仅限位于具有身份验证功能的代理之后）

安全模型

• 规格验证： 对 ID、颜色和样式进行模式检查，并应用大小限制。
• 文本转义： 标题、节点标签和集群标签始终作为字面字符串写入， 从不作为 Graphviz HTML 标签。边标签会进行 HTML 转义。因此，标签无法注入 DOT 语句，例如读取本地文件的 image= 属性。
• 渲染： Graphviz 作为子进程运行，并设有硬性超时；失败时会删除部分输出。
• 输出文件： 文件名经过清理，带有时间戳并附加唯一后缀。保留策略清理只会处理服务器生成的文件。
• Terraform 输入： 文件读取范围限制在 ARCH_DIAGRAM_INPUT_ROOTS 内，并受大小限制。
• HTTP：
  • 每个已配置 token 都会参与静态 token 的恒定时间比较。
  • OIDC JWT 会经过完整验证，并拒绝密钥混淆和 alg: none token（两者均经过测试）。
  • 每种工具均应用 RBAC，且每条审计日志都会记录调用方。
  • 未启用身份验证时，服务器拒绝绑定到公共地址。
  • DNS 重绑定防护使用 Host/Origin 允许列表。
  • 容器以非 root 用户身份运行。
• SVG 输出： 图标会嵌入文件，因此文件不会泄露本地路径，并且可在任何地方渲染。

目录结构

src/arch_diagram_mcp/
  server.py        MCP tools, prompt, error mapping, audit logging
  catalog.py       icon index, alias resolution, ranked search, suggestions
  models.py        spec schema + semantic validation
  renderer.py      Graphviz source build, timed subprocess render, themes, SVG inlining, retention
  review.py        Well-Architected heuristic rules and scoring
  terraform.py     Terraform plan/state -> spec
  gcp_inventory.py Cloud Asset Inventory export of running GCP resources -> spec
  template_library.py + templates/*.json   reference architectures
  auth.py          principals, static-token + OIDC authenticators, RBAC
  storage.py       local signed links, S3 / Azure Blob / GCS uploads with signed URLs
  http_app.py      streamable-HTTP app, auth middleware, OAuth resource metadata, /artifacts, /healthz
  config.py, logs.py, __main__.py
tests/             85 tests: catalog, validation, rendering, label injection, review, Terraform, GCP
                   inventory (real export fixture), MCP tools, HTTP auth, OIDC (incl. attack tokens), RBAC,
                   signed links, S3 (moto), Azure SAS, GCS V4
docs/USER_GUIDE.md      developer guide: connecting clients, example prompts, troubleshooting
docs/CLOUD_TESTING.md   how the server was tested on real Google Cloud
docs/samples/      rendered sample diagrams shown above
scripts/render_samples.py   regenerates docs/samples/
scripts/e2e_cloud.py, run_impersonated.py   real-cloud end-to-end test tools

许可证

Apache-2.0。捆绑的提供商图标来自 diagrams 库，仍受其所有者的条款约束。