AI 助手正在改变开发者的工作方式，但它们看不到你的架构文档。MCP Server 弥合了这一差距。本指南涵盖了 MCP 是什么、为什么它对架构至关重要，以及 Archyl 的 56 个 MCP 工具如何让你直接从 Claude 或 Cursor 中查询、创建和验证架构。

如何使用 MCP Server 进行架构文档管理

AI 编码助手已经变得不可或缺。Claude Code 帮你重构复杂系统。Cursor 加速功能开发。GitHub Copilot 建议实现方案。但所有这些工具都有一个共同的盲点：它们不了解你的架构。

当你要求 AI 助手"给 User Service 添加一个新端点"时，它不知道你的 User Service 通过 gRPC 与 Auth Service 通信，使用 PostgreSQL 存储数据，向 Kafka 发布事件，并且在你的 ADR 中记录了一系列特定的安全要求。AI 靠猜测，你来纠正，一半的生产力提升就这样消失了。

MCP Server 解决了这个问题。它们让 AI 助手以结构化的方式访问你的架构文档，将你的系统设计转变为一个可查询的、可操作的数据源。本指南涵盖了你需要了解的关于使用 MCP Server 进行架构文档管理的一切——MCP 是什么、为什么它重要，以及如何用 Archyl 来设置它。

什么是 MCP (Model Context Protocol)？

MCP——Model Context Protocol——是 Anthropic 创建的一个开放标准，用于将 AI 助手连接到外部工具和数据源。它定义了一种结构化的方式，让 AI 模型可以发现、调用和接收外部能力的结果。

可以把 MCP 想象成一个通用适配器。在 MCP 之前，每个 AI 助手都有自己专有的外部工具集成方式。MCP 将其标准化，创建了一个跨不同 AI 助手通用的协议。

MCP Server 是一个通过 MCP 协议暴露一组工具的服务。每个工具有名称、描述、输入参数和输出格式。当 AI 助手连接到 MCP Server 时，它会发现可用的工具，并在对话过程中按需调用它们。

对于架构文档来说，这意味着你的架构模型变成了一组可查询的、可修改的工具，任何兼容 MCP 的 AI 助手都可以使用。AI 不需要解析文件或猜测你的系统结构——它可以直接查询权威的事实来源。

为什么架构需要 MCP

架构文档恰好处在 MCP 能完美解决的多个需求的交汇点。

上下文是 AI 辅助开发的一切

AI 生成代码的质量与 AI 拥有的上下文质量成正比。当 AI 助手理解你的架构——存在哪些服务、它们如何通信、使用什么技术、适用什么约束——它就能生成自然融入你系统的代码。

没有架构上下文，AI 助手就只能做假设。它可能建议 REST API，而你的服务使用的是 gRPC。它可能创建一个直接的数据库连接，而你的架构要求通过服务层。它可能提议一个同步调用，而你的系统使用的是事件驱动通信。

MCP 让 AI 助手访问真实的架构，消除了这些不匹配。

架构文档是结构化数据

与自由格式的文档（Wiki、Confluence 页面、README 文件）不同，以 C4 框架建模的架构文档本质上是结构化的。系统包含容器。容器包含组件。元素有技术、描述和关系。ADR 有状态和受影响的元素。

这种结构自然地映射到 MCP 工具。每种架构元素类型成为一个可查询的实体。每种操作（列表、获取、创建、更新）成为一个工具。AI 助手可以像开发者浏览文件系统一样浏览架构模型。

文档应该是双向的

大多数文档工具从 API 角度来看是只读的。你可以查看文档，但修改它们需要打开特定的应用程序。MCP 实现了双向交互：AI 助手既可以读取架构模型，也可以写入架构模型。

这意味着 AI 助手不仅可以查询你的架构，还可以提出修改建议——添加新组件、创建关系、起草 ADR。开发者审查并批准这些变更，但 AI 完成了更新文档的机械性工作。

Archyl 的 MCP Server：56 个架构工具

Archyl 提供了架构文档领域最全面的 MCP Server 实现之一。通过 56 个工具覆盖了架构建模的完整范围，从查询 C4 模型到管理发布和跟踪漂移。

以下是工具类别的概述。

查询 C4 模型

核心查询工具让 AI 助手在每个层级探索你的架构：

list_systems / get_project_c4_model——发现项目中的所有 Software System
list_containers / list_components——浏览 C4 层次结构
list_relationships——理解元素之间的连接方式
get_element_technologies——查看任何元素的技术栈
get_element_owners——了解谁拥有什么

这些工具支持关于架构的自然语言查询。当你问"Order Service 依赖哪些数据库？"时，AI 可以列出 Order Service 的关系，筛选数据库容器，并返回精确的答案。

管理架构元素

写入工具让 AI 助手修改架构模型：

create_system / update_system / delete_system——管理 Software System
create_container / update_container / delete_container——管理容器
create_component / update_component / delete_component——管理组件
create_relationship / update_relationship / delete_relationship——管理连接

这些工具在开发过程中保持文档时效性方面特别强大。当你向代码库添加新服务时，可以要求 AI 助手在架构模型中添加相应的容器、设置其技术栈并创建适当的关系——所有这些都无需离开你的 IDE。

架构决策记录

ADR 工具将决策文档纳入 AI 工作流：

list_adrs / get_adr——查询现有决策
create_adr / update_adr——创建新 ADR 或更新现有 ADR
link_adr_to_element——将决策关联到受影响的元素

当你与 AI 助手讨论技术选型时，它可以检查现有 ADR 中是否有相关决策，为当前决策起草新的 ADR，并将其链接到相关的架构元素。

API 契约和 Event Channel

集成文档工具涵盖服务边界：

list_api_contracts / create_api_contract——管理 API 规范
list_event_channels / create_event_channel——建模异步通信
link_api_contract / link_event_channel——将规范关联到元素

这些工具有助于维护架构与实现之间的联系。当你创建一个新的 API 端点时，AI 可以检查该服务是否已有 API 契约，并建议更新它。

文档与协作

更广泛的文档工具支持团队工作流：

create_documentation / update_documentation——管理项目文档
create_comment / list_comments——为架构元素添加注释
list_flows / create_flow——记录用户和系统流程
get_drift_score / compute_drift_score——检查文档准确性

发布与指标

运营工具将架构与交付联系起来：

create_release / list_releases——跟踪部署
get_dora_metrics / get_dora_trend——衡量工程效能
list_environments——了解部署目标

实际示例：MCP 的实际应用

以下是开发者在日常工作流中使用 Archyl MCP Server 的具体示例。

示例 1：在 Claude Code 中查询系统

你正在 Claude Code 中工作，需要在进行变更之前了解架构：

你：我们的项目有哪些系统和容器？

Claude：让我查看你的架构。
[调用 list_systems，然后对每个系统调用 list_containers]

你的项目"E-Commerce Platform"有 3 个系统：
1. E-Commerce Platform (software_system)
   - API Gateway (Go, Kong)
   - User Service (Go, PostgreSQL)
   - Order Service (Java, PostgreSQL)
   - Product Service (Node.js, MongoDB)
   - Notification Service (Python, Redis)
   - Event Bus (Kafka)

2. Stripe (external_system)
   - 支付处理网关

3. SendGrid (external_system)
   - 事务邮件服务

AI 返回的是来自你文档化架构的真实数据，而非幻觉。

示例 2：在 Cursor 中创建组件

你向一个服务添加了新模块并希望记录它：

你：我刚才在 API Gateway 中添加了一个 RateLimiter 组件。
     它使用 Redis 和 golang.org/x/time/rate 库。
     你能把它添加到我们的架构中吗？

Cursor：我来把它添加到你的 C4 模型中。
[调用 create_component，参数 name="RateLimiter",
 container="API Gateway", technologies=["Redis", "Go"]]
[调用 create_relationship，从 RateLimiter
 到 Redis 容器]

完成了。我已将 RateLimiter 组件添加到 API Gateway
并创建了到你的 Redis 容器的关系。

文档在几秒钟内更新完毕，无需离开 IDE。

示例 3：重构前检查漂移

在进行大规模重构之前，你想知道文档的准确程度：

你：我们当前的漂移评分是多少？有没有未记录的服务？

Claude：让我检查一下。
[调用 get_drift_score]
[调用 get_drift_details]

你的漂移评分是 78/100（良好）。

检测到的问题：
- Search Service 正在生产环境运行，但未记录在
  你的 C4 模型中
- Analytics Service 有 2 个未记录的与
  Data Warehouse 的关系
- API Gateway 的技术列表缺少"Redis"
  （最近为限流功能添加的）

需要我修复这些问题吗？

AI 精确识别出哪些内容过时了，并且可以自动修复。

示例 4：起草 ADR

在讨论将内部服务通信从 REST 切换到 gRPC 的设计方案时：

你：我们正在考虑将内部服务通信从 REST 切换到 gRPC。
     你能起草一个 ADR 并检查我们是否有相关的现有决策吗？

Claude：让我先检查现有的 ADR。
[调用 list_adrs]

我找到了一个相关的 ADR：
- ADR-007："所有内部 API 使用 REST"（状态：已接受）
  这是 18 个月前做出的决策。

我来起草一个新的 ADR 来取代它。
[调用 create_adr，标题为"将内部通信
 从 REST 迁移到 gRPC"]

已创建 ADR-015，内容包括：
- 背景：当前基于 REST 的通信增加了序列化开销...
- 决策：对所有新的内部服务通信采用 gRPC
  和 Protocol Buffers...
- 状态：已提议
- 取代：ADR-007

需要我将其关联到受影响的服务吗？

AI 检查相关决策、起草新的 ADR，并提供将其关联到相关架构元素的选项。

示例 5：变更前理解影响范围

在修改服务之前，你想了解影响范围：

你：我需要修改 Order Service 的数据库 Schema。
     还有什么依赖于 Order Service？

Claude：让我追踪依赖关系。
[调用 list_relationships，过滤 Order Service]
[调用 get_element_owners，获取依赖元素的所有者]

Order Service 的依赖方如下：
- API Gateway -> Order Service (REST, 订单管理)
- Order Service -> Payment Service (gRPC, 支付处理)
- Order Service -> Event Bus (发布 OrderCreated,
  OrderUpdated, OrderCancelled 事件)
- Notification Service 从 Event Bus 消费 Order 事件
- Analytics Service 从 Event Bus 消费 Order 事件

所有者：
- Order Service：Platform Team
- Payment Service：Payments Team
- Notification Service：Platform Team
- Analytics Service：Data Team

Schema 变更可能影响 Payment Service（直接依赖）
以及任何 Order 事件的消费者。建议与
Payments Team 和 Data Team 进行协调。

设置 Archyl 的 MCP Server

设置 Archyl 的 MCP Server 只需几分钟。以下是针对最常见 AI 助手的设置方法。

Claude Code 设置

将 Archyl MCP Server 添加到你的 Claude Code 配置中：

{
  "mcpServers": {
    "archyl": {
      "url": "https://mcp.archyl.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

配置完成后，Claude Code 会自动发现全部 56 个工具，并可以在任何对话中使用它们。

Cursor 设置

Cursor 通过其设置支持 MCP Server。在 MCP 部分添加 Archyl：

{
  "mcpServers": {
    "archyl": {
      "url": "https://mcp.archyl.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

添加配置后，重启 Cursor。Archyl 工具会出现在 MCP 工具列表中，Cursor 可以在代码生成和重构过程中使用它们。

其他 MCP 兼容工具设置

任何支持 MCP 协议的工具都可以连接到 Archyl 的 MCP Server。该 Server 暴露了一个带有工具发现功能的标准 MCP 端点，兼容的客户端会自动检测并列出可用工具。

API Key 生成

从 Archyl 仪表板生成你的 MCP API Key：

导航到你的组织设置
进入 API 部分
创建具有适当权限的新 API Key
将 Key 复制到你的 MCP Server 配置中

我们建议为不同用途创建独立的 API Key（例如，一个用于 Claude Code，一个用于 CI/CD），以便可以独立轮换。

MCP 驱动的架构文档最佳实践

从只读开始

首次设置 MCP Server 时，从只读查询开始。在启用写入操作之前，先熟悉 AI 助手探索架构的能力。这有助于建立对工具准确性和可靠性的信心。

审查 AI 生成的变更

当 AI 助手创建或修改架构元素时，在将其视为最终结果之前进行审查。Archyl 的历史和版本功能让你可以查看变更内容，并在需要时回滚。AI 是强大的助手，但架构决策应始终有人类监督。

将 MCP 与 Architecture as Code 结合

MCP 和 Architecture as Code 是互补的。使用 MCP 进行交互式查询和开发过程中的快速更新。使用 Architecture as Code（archyl.yaml 文件）进行经过代码审查的、受版本控制的权威定义。两种方法相互加强。

在代码审查中使用 MCP

在代码审查过程中，要求 AI 助手检查代码变更是否与文档化的架构一致。"这个新的 API 端点是否符合该服务文档化的 API 契约？"或者"这些数据库查询是否按照文档化要求通过服务层？"AI 可以实时验证代码是否符合架构模型。

让团队了解可用工具

MCP 采用的最大障碍是认知不足。大多数开发者没有意识到 AI 可以回答哪些关于架构的问题。分享示例，创建常用查询的速查表，并在团队会议中演示 MCP 工作流。

AI 驱动架构文档的未来

MCP Server 代表了团队与架构文档交互方式的根本性转变。文档不再是开发者阅读（或更常见地不阅读）的被动产物，而是成为开发工作流中的主动参与者。

当你的 AI 助手可以在生成代码前查询架构，在变更后检查合规性，并随系统演进更新文档时，"处理系统"和"记录系统"之间的界限就消失了。

架构文档不再是你需要单独维护的东西，而是编织进每一次开发交互中的东西。你向 AI 提出的每个问题、你做出的每次代码变更、你进行的每次设计讨论——所有这些都可以被架构模型告知并反映在其中。

这就是 Archyl 正在构建的未来。MCP Server 是 AI 驱动开发与结构化架构文档之间的桥梁。凭借 56 个覆盖架构建模完整范围的工具，它足以支持你团队所需的任何工作流。

开始使用 Archyl 的 MCP Server，给你的 AI 助手提供它一直缺失的架构上下文。

如何使用 MCP Server 进行架构文档管理 - Archyl Blog