MCP 集成（AI 工具访问）

Canopy 内置了一个 MCP 服务器（Model Context Protocol），允许 AI 工具（如 Claude Desktop、GitHub Copilot、Cursor 和 VS Code）直接查询并更新您的 EA 数据。AI 工具还可以上传工件（电子表格、BPMN 图、DrawIO 图、自由文档），并将其转化为符合现有元模型的卡片、关系和图表。用户通过现有的 SSO 提供商进行身份验证，每个操作都遵循其个人权限。

此功能是可选的，不会自动启动。它要求 SSO 已配置、MCP 配置文件在 Docker Compose 中已激活，并且管理员在设置界面中启用了它。

工作原理

AI 工具（Claude、Copilot 等）
    │
    │  MCP 协议（HTTP + SSE）
    ▼
Canopy MCP 服务器（:8001，内部）
    │
    │  OAuth 2.1 + PKCE
    │  委托给 SSO 提供商
    ▼
Canopy 后端（:8000）
    │
    │  按用户 RBAC
    ▼
PostgreSQL

用户将 MCP 服务器 URL 添加到其 AI 工具中。
首次连接时，AI 工具会打开浏览器窗口进行 SSO 身份验证。
登录后，MCP 服务器会颁发自己的访问令牌（基于用户的 Canopy JWT）。该令牌会在到期前大约一小时被主动刷新。
AI 工具将使用此令牌进行所有后续请求。
每个查询都通过 Canopy 的正常权限系统——用户只能看到他们有权访问的数据。

前提条件

启用 MCP 之前，您必须具备：

已配置且正常运行的 SSO —— MCP 将身份验证委托给您的 SSO 提供商（Microsoft Entra ID、Google Workspace、Okta 或通用 OIDC）。请参阅认证与 SSO 指南。
具有公共域名的 HTTPS —— OAuth 流程需要稳定的重定向 URI。请将 Canopy 部署在 TLS 终止反向代理（Caddy、Traefik、Cloudflare Tunnel 等）后面。

设置

步骤 1：启动 MCP 服务

MCP 服务器是一个可选启用的 Docker Compose 配置文件。在启动命令中添加 --profile mcp：

docker compose --profile mcp up -d

这会在后端和前端旁边启动一个轻量级 Python 容器（端口 8001，仅限内部）。Nginx 会自动将 /mcp/ 请求代理到该服务——如果容器未运行，请求会得到一个干净的 502 响应，而不会导致边缘代理崩溃。

步骤 2：配置环境变量

将以下内容添加到您的 .env 文件中：

CANOPY_PUBLIC_URL=https://your-domain.example.com
MCP_PUBLIC_URL=https://your-domain.example.com/mcp

变量	默认值	描述
`CANOPY_URL`	`http://backend:8000`	MCP 容器所访问的内部后端 URL（Docker 服务名——很少需要更改）。
`CANOPY_PUBLIC_URL`	`http://localhost:8920`	您的 Canopy 实例的公共 URL。
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	MCP 服务器的公共 URL（用于 OAuth 重定向 URI 和元数据）。
`MCP_PORT`	`8001`	MCP 容器的内部端口（很少需要更改）。

步骤 3：将 OAuth 重定向 URI 添加到 SSO 应用

在 SSO 提供商的应用注册中（与您为 Canopy 登录设置的相同），添加此重定向 URI：

https://your-domain.example.com/mcp/oauth/callback

这是用户从 AI 工具连接时 OAuth 认证流程所必需的。

步骤 4：在管理设置中启用 MCP

前往管理区域的设置，并选择 AI 选项卡。
滚动到 **MCP 集成（AI 工具访问）**部分。
切换开关以启用 MCP。
界面将显示 MCP 服务器 URL 和设置说明，供您与团队共享。

注意

如果未配置 SSO，开关将被禁用。请先设置 SSO。

连接 AI 工具

启用 MCP 后，将 MCP 服务器 URL 分享给您的团队。每个用户将其添加到自己的 AI 工具中：

Claude Desktop

打开设置 > 连接器 > 添加自定义连接器。
输入 MCP 服务器 URL：https://your-domain.example.com/mcp
点击连接 —— 浏览器窗口将打开进行 SSO 登录。
认证后，Claude 即可查询并更新您的 EA 数据。

VS Code（GitHub Copilot / Cursor）

添加到工作区的 .vscode/mcp.json：

{
  "servers": {
    "canopy": {
      "type": "http",
      "url": "https://your-domain.example.com/mcp/mcp"
    }
  }
}

双重 /mcp/mcp 是有意为之——第一个 /mcp/ 是 Nginx 代理路径，第二个是 MCP 协议端点。

本地测试（stdio 模式）

对于不需要 SSO/HTTPS 的本地开发或测试，可以在 stdio 模式下运行 MCP 服务器——Claude Desktop 会将其直接作为本地进程启动。

1. 安装 MCP 服务器包：

pip install ./mcp-server

2. 添加到 Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "canopy": {
      "command": "python",
      "args": ["-m", "canopy_mcp", "--stdio"],
      "env": {
        "CANOPY_URL": "http://localhost:8000",
        "CANOPY_EMAIL": "[email protected]",
        "CANOPY_PASSWORD": "your-password"
      }
    }
  }
}

在此模式下，服务器会直接使用邮箱/密码进行身份验证（无需 OAuth），并在后台自动刷新 Canopy JWT。

可用功能

MCP 服务器共提供 47 个工具：涵盖九个集群的 30 个读取工具，以及 17 个写入工具（13 个附加型，4 个破坏性）。每个工具都携带 ToolAnnotations（readOnlyHint / destructiveHint / idempotentHint），因此像 Claude Desktop 这样的连接器可以在用户批准调用之前，在其界面上呈现该操作的破坏性程度。

写入操作的演练安全机制

每个写入工具默认使用 dry_run=true。在此模式下，后端会运行每一个校验器和解析器，构建完整计划，然后回滚事务，因此不会持久化任何内容。AI 工具会将预览返回给用户；只有在用户明确确认后，才应再次以 dry_run=false 调用该工具进行提交。这可以防止过于热心的代理在解读错误的电子表格基础上，悄悄创建数百张卡片。

对于较大规模的提交，还有第二道关卡：任何超过 MCP_BATCH_CONFIRMATION_THRESHOLD（默认 20 行）的提交，都必须回传由上一次演练所颁发的一次性 confirm_token。该令牌的有效期为 15 分钟。这一规则会被强制执行两次——一次是在调用后端之前由 MCP 封装层执行，另一次是在提交端点上由后端自身执行——因此即便客户端跳过了演练步骤，也无法悄悄提交一个未经审查的大批量变更。

变更批次（审计轨迹）

每次写入调用——无论是否为演练——都会在触碰任何数据之前先创建一条 mutation_batches 记录，其发出的每个事件（卡片创建、关系创建/更新、评论发布……）都会被打上该批次 ID、调用的工具名称以及已认证用户的标记。get_change_history 工具可以根据批次 ID 还原该批次逐个事件的完整差异，rollback_batch 则可以撤销某个批次的写入操作（见下文）。这意味着任何由 MCP 驱动的更改，都可以精确追溯到究竟是谁在何时运行了哪个工具——这与通过 Web 界面执行的同一操作是可以区分的。

读取工具

服务器提供分布在九个集群中的 30 个读取工具。

卡片与元模型

工具	描述
`search_cards`	按类型、状态或自由文本搜索和筛选卡片
`get_card`	通过 UUID 获取卡片的完整详细信息
`get_card_relations`	获取连接到卡片的所有关系
`get_card_hierarchy`	获取卡片的祖先与子级
`list_card_types`	列出元模型中的所有卡片类型，包括字段与配置
`get_relation_types`	列出关系类型，可按卡片类型筛选
`resolve_card_refs`	在批量导入前预校验基于名称的卡片引用（例如「Sales / Customer Mgmt / CRM」）——显示已解析 / 存在歧义 / 缺失的匹配结果
`analyze_impact`	多跳影响分析——从某张卡片出发沿关系图向外遍历最多 3 跳，按深度分组，并可选按关系类型和卡片类型筛选

仪表盘

工具	描述
`get_dashboard`	KPI 仪表盘（计数、数据质量、审批、活动）
`get_landscape`	某一类型的卡片按相关类型分组

GRC — 风险登记册

工具	描述
`list_risks`	分页可筛选的 EA 风险列表（TOGAF G 阶段）
`get_risk`	单条风险详情，含关联卡片与审计轨迹
`get_risk_metrics`	KPI 指标 + 初始与残余 4×4 概率 × 影响矩阵
`get_card_risks`	当前与某卡片关联的所有风险

GRC — 合规

工具	描述
`list_compliance_findings`	按法规分组的合规发现（EU AI Act、GDPR、NIS2、DORA、SOC 2、ISO 27001）
`get_compliance_overview`	合规评分 + 各法规状态矩阵 + 最近扫描元数据

治理与交付

工具	描述
`list_principles`	已发布的 EA 原则（陈述、依据、影响）
`list_adrs`	架构决策记录（ADR），可按举措 / 卡片 / 状态 / 搜索词筛选
`get_adr`	单条 ADR，含各章节、关联卡片、相关 ADR 与签署记录
`list_soaws`	某项举措的架构工作说明书（SoAW）

报告

工具	描述
`get_portfolio_report`	某卡片类型的气泡图数据（默认：功能契合度 × 技术契合度）
`get_cost_treemap`	卡片成本树形图，可选按相关类型分组
`get_capability_heatmap`	层级化的业务能力热图
`get_data_quality_report`	按卡片类型划分的数据完整度明细

卡片上下文

工具	描述
`get_card_stakeholders`	卡片上分配的用户与角色
`get_card_comments`	卡片的评论线程
`get_card_documents`	附加到卡片的文档链接

图表

工具	描述
`list_diagrams`	列出自由绘制图，可选筛选到某张卡片
`get_diagram`	通过 ID 获取单个图，包含其 DrawIO XML

审计与变更历史

工具	描述
`get_change_history`	通过 ID 查询某个变更批次（返回该批次及其下按顺序发出的每个事件），或按操作者、工具名称或来源（`mcp` / `web` / `api`）浏览近期批次

所有读取工具都受已认证用户 RBAC 的约束——查看者在其无权访问的领域只会得到空列表（或 403）；MCP 层无需针对每个工具单独配置。

写入工具

服务器提供 17 个写入工具：13 个附加型（不会破坏数据的创建/更新操作）和 4 个破坏性（可能覆盖或删除数据，尽管其中几个本身是可恢复的——详见下文说明）。

卡片与生命周期

工具	标注	描述
`create_cards_bulk`	附加型	在一次调用中根据从工件中提取的行（例如电子表格的多行）批量创建多张卡片。支持在同一批次内按名称引用父卡片，并由服务端执行拓扑排序。
`update_cards_bulk`	附加型	在一次调用中批量更新多张卡片——字段级补丁，演练模式下会给出每行的修改前/后对比。`attributes` 按行整体替换；`strict_attributes=true` 会拒绝未知字段键并给出修复提示。
`transition_card_lifecycle`	附加型	推进卡片的审批操作（`approve` / `reject` / `reset`）、生命周期阶段（`phaseIn` / `active` / `phaseOut` / `endOfLife`）或状态值（`ACTIVE` / `PHASING_IN` / `PHASING_OUT` / `END_OF_LIFE` / `ARCHIVED`）。若调用者缺少相应权限，会返回带有 UI 深链接的 `pending` 响应，而非直接失败。
`archive_cards`	破坏性	对一张或多张卡片执行软删除（归档），演练模式下会给出级联预览（子卡片、孤立关系）。已归档的卡片在自动清除前有 30 天的可恢复期。MCP 有意不暴露硬删除/永久删除功能。

关系与图表

工具	标注	描述
`upsert_relations_bulk`	破坏性	在卡片之间创建或删除关系。默认拒绝 `action: "delete"`（详见下文防护栏）——这也是尽管创建关系是常见用例，该工具仍被标注为破坏性的原因。
`create_diagram`	附加型	创建一个自由形式的 DrawIO 图，可选通过 UUID 链接到已有卡片。
`update_diagram`	破坏性	更新已有图的 XML、名称、描述或关联卡片——`drawio_xml` 会原样替换整个画布。
`import_bpmn`	附加型	将 BPMN 2.0 图保存到已存在的业务流程卡片上，并走完草稿 → 提交 → 审批的工作流。如果没有匹配的卡片，会返回 `card_not_found` 错误并指向 `create_cards_bulk`，而不是悄悄创建一张内容稀薄的卡片。

GRC — 风险登记册

工具	标注	描述
`create_risks`	附加型	创建一条或多条风险，可在同一次调用中关联受影响的卡片。
`update_risks`	附加型	按 ID 修改已有风险；若提供 `linked_card_ids`，将替换受影响卡片的关联集合。

治理与交付

工具	标注	描述
`create_soaw`	附加型	为某项举措创建架构工作说明书（SoAW）。
`create_adr`	附加型	创建一条架构决策记录（默认落入 `draft` 状态）。
`update_adr`	附加型	更新已有 ADR 的标题、章节、状态或关联卡片。
`sign_adr`	附加型	签署一条 ADR。若调用者缺少 `adr.sign` 权限，会返回带深链接的 `pending` 响应。

协作

工具	标注	描述
`add_card_comment`	附加型	在卡片上发表评论（可选作为线程回复）。
`assign_stakeholders`	附加型	为卡片分配或移除利益相关者角色。后端没有针对此操作的批量端点，因此该工具会在单个变更批次内逐条分发执行。

审计

工具	标注	描述
`rollback_batch`	破坏性	撤销某个变更批次下执行的写入操作，方法是反向遍历其事件并对每个事件执行相应的逆操作。覆盖 `card.created` / `card.updated` / `card.archived` / `card.restored` / `relation.created` / `relation.upserted`；其他事件类型会在演练计划中标记为 `unsupported_events`。回滚操作本身会被记录为一个新的批次，因此历史记录永远不会被抹除。如果有更晚的批次触碰了相同的实体，则默认拒绝执行，除非设置 `force=true`（需要 `admin.events` 权限）。

这些工具存储的内容（评论正文、ADR/SoAW 章节文本）在后续读取时被视为不受信任的数据——服务器绝不会将其解释为指令，只会原样展示。

典型的工件导入工作流

当用户与 AI 代理共享电子表格时：

代理调用 list_card_types 和 get_relation_types 以理解元模型。
代理解析电子表格（在其自身上下文中完成，而非在 MCP 中），并构建行字典。
代理可选地调用 resolve_card_refs，以检查任何基于名称的父级/关系引用是否能唯一解析。
代理调用 create_cards_bulk(cards=…, dry_run=True)，并向用户展示预览。
用户确认后，代理再次以 dry_run=False 调用（若批次超过确认阈值，需回传 confirm_token）以完成提交。
如果存在关系列，代理随后以相同的演练/确认循环调用 upsert_relations_bulk。

MCP 服务器本身从不解析上传的文件——调用方 AI 工具会在其自身上下文中读取源工件（电子表格、BPMN XML、DrawIO XML、PDF、图像），并发送已结构化的行数据。

写入工具防护栏

在演练机制之上的纵深防御，确保 LLM 的失误不会造成大规模损害：

每次调用的大小上限。 MCP 写入工具强制施加比底层 Excel 导入端点小得多的上限：create_cards_bulk / update_cards_bulk / archive_cards 为 200 张卡片，upsert_relations_bulk 为 500 次操作。这个上限足以应对任何实际的单一工件上传，又足够小，使演练预览仍然易于快速查看。后端端点本身对合法的 Web 界面 Excel 导入器接受多达 2000/5000 的规模。
超过阈值需确认令牌。 触及超过 MCP_BATCH_CONFIRMATION_THRESHOLD 行数（默认 20）的提交，必须回传上一次演练所颁发的 confirm_token。该规则由 MCP 封装层和后端共同强制执行。
默认不允许删除关系。 upsert_relations_bulk 拒绝 action: "delete" 操作——若要删除关系，请使用 Web 界面，那里的操作会以用户身份被记录，并留有明确的审计轨迹。运营者可通过设置 MCP_ALLOW_RELATION_DELETE=true 选择启用。
不支持硬删除。 工具集刻意省略了永久删除卡片的功能。archive_cards（软删除，30 天可恢复期）和 rollback_batch 是通过 MCP 移除数据的唯一途径，二者都受演练机制约束，并被标注为破坏性操作。未来任何执行不可逆变更的工具都需要先经过 RFC 讨论。
紧急开关。 MCP_WRITES_ENABLED=false 可在无需重新部署代码的情况下关闭全部 17 个写入工具。30 个读取工具仍可正常使用。
审计来源标记。 来自 MCP 服务器的每个后端请求都携带 X-Canopy-Origin: mcp 头（服务端仅允许 {mcp, web, api} 三个白名单值——其他任何值都会被丢弃）。由这些请求触发的事件在审计载荷中被标记为 origin: "mcp"，以便管理员可以将 MCP 驱动的写入从时间线中筛选出来。X-Canopy-Batch 头会在单次工具调用中的每个请求之间传递当前的变更批次 ID。

MCP 容器上的六个防护栏环境变量：

变量	默认值	作用
`MCP_WRITES_ENABLED`	`true`	写入工具的总开关。`false` → 只读 MCP。
`MCP_MAX_CARDS_PER_CALL`	`200`	`create_cards_bulk`、`update_cards_bulk`、`archive_cards` 每次调用的行数硬性上限。
`MCP_MAX_RELATIONS_PER_CALL`	`500`	`upsert_relations_bulk` 每次请求操作数的硬性上限。
`MCP_ALLOW_RELATION_DELETE`	`false`	当为 `true` 时，`upsert_relations_bulk` 接受 `action: "delete"` 操作。
`MCP_BATCH_CONFIRMATION_THRESHOLD`	`20`	超过此行数的提交必须回传上一次演练颁发的 `confirm_token`。
`MCP_REQUIRE_DRYRUN_FIRST`	`true`	为 `true` 时，若超过阈值的提交在同一会话中没有匹配的先前演练，将被拒绝。运营者可为受信任的自动化流水线禁用此项。

资源

URI	描述
`turbo-ea://types`	元模型中的所有卡片类型
`turbo-ea://relation-types`	所有关系类型
`turbo-ea://dashboard`	仪表盘 KPI 和汇总统计

引导提示

提示	描述
`analyze_landscape`	多步分析：仪表盘概览、类型、关系
`find_card`	按名称搜索卡片，获取详细信息和关系
`explore_dependencies`	映射某张卡片依赖什么，以及什么依赖于它

权限

角色	访问权限
管理员	配置 MCP 设置（`admin.mcp` 权限）。通过 MCP 拥有完整的读取 + 写入权限。
所有已认证用户	读取权限由其现有 RBAC 控制。写入工具需要与所执行操作相匹配的后端权限。

通过 MCP 访问数据——无论是读取还是写入——都遵循与 Web 界面相同的 RBAC 模型。如果用户无法在库存界面中创建卡片，那么也无法通过 MCP 创建；不存在单独的 MCP 专属数据权限。按工具划分的部分权限如下：

权限	作用范围
`inventory.create`	`create_cards_bulk`
`inventory.edit`	`update_cards_bulk`，以及通过 `transition_card_lifecycle` 进行的生命周期/状态转换
`inventory.approval_status`	通过 `transition_card_lifecycle` 进行的审批转换（`approve` / `reject` / `reset`）
`inventory.archive`	`archive_cards`
`relations.manage`	`upsert_relations_bulk`
`diagrams.manage`	`create_diagram`、`update_diagram`
`bpm.edit`	`import_bpmn`（起草）；发布还需要该流程上的 `card.approval_status` 权限，可通过 `process_owner` 利益相关者角色、admin 或 bpm_admin 持有
`risks.manage`	`create_risks`、`update_risks`
`comments.create`	`add_card_comment`
`stakeholders.manage`	`assign_stakeholders`
`soaw.create`	`create_soaw`
`adr.create`	`create_adr`、`update_adr`
`adr.sign`	`sign_adr`
`admin.events`	`rollback_batch(force=True)` —— 用于覆盖与更晚批次冲突的回滚操作

admin.mcp 权限控制谁可以管理 MCP 设置。默认情况下仅对管理员角色可用。可以通过角色管理页面向自定义角色授予此权限。

部分写入工具在调用者缺少权限时会优雅降级而非直接失败：transition_card_lifecycle 和 sign_adr 会返回带有 Web 界面深链接的 pending 响应，以便拥有相应权限的人员前往完成该操作。

安全性

SSO 委托认证：用户通过企业 SSO 提供商进行身份验证。MCP 服务器从不接触或存储密码（在 HTTP 模式下）。
OAuth 2.1 + PKCE：认证流程使用代码交换证明密钥（PKCE，S256）来防止授权码拦截。
按用户 RBAC：每次 MCP 查询——无论是读取还是写入——都使用已认证用户的权限执行。没有共享服务账户。
写入默认演练：写入工具默认采用「校验后回滚」的预览模式。AI 工具必须再次显式以 dry_run=false 调用后，更改才会被持久化，且每次更改都会在用户身份下作为某个变更批次的一部分被审计记录。
大额提交的确认令牌门槛：超过可配置行数阈值的提交需要一个由此前演练颁发的令牌，该令牌会由 MCP 封装层和后端分别独立校验。
具备回滚能力的完整审计轨迹：get_change_history 可根据批次 ID 还原该批次的完整差异；rollback_batch 可撤销某批次中受支持的事件类型，该回滚本身也会被记录为一个新的、可审计的批次。
MCP 中不解析文件：MCP 服务器本身不接收 PDF、Excel 文件、图像或其他二进制工件。调用方 AI 工具会在其自身上下文中解析它们，并发送结构化的行数据。这样可以缩小攻击面，避免服务器暴露于格式不规范的二进制输入。
MCP 不提供硬删除：永久删除卡片的功能没有作为工具暴露。唯一的数据移除途径是 archive_cards（30 天可恢复的软删除）和 rollback_batch。
令牌轮换：访问令牌在 1 小时后过期，并会被主动刷新。刷新令牌有效期为 30 天。授权码为一次性使用，10 分钟后过期。
仅内部端口：MCP 容器仅在 Docker 内部网络上暴露端口 8001。所有外部访问都通过 Nginx 反向代理。
单实例令牌存储：OAuth 令牌保存在 MCP 容器的内存中。如果您在负载均衡器后运行多个副本，请将会话固定到单个实例，或者预期用户在发生故障转移后需要重新进行身份验证——令牌不会在多个副本之间共享。

故障排除

问题	解决方案
设置中 MCP 开关被禁用	必须先配置 SSO。前往设置 > 认证选项卡并设置 SSO 提供商。
Nginx 日志中出现「host not found」	MCP 服务未运行。使用 `docker compose --profile mcp up -d` 启动它。Nginx 配置会优雅地处理此情况（返回 502 响应，不会崩溃）。
OAuth 回调失败	验证是否已将 `https://your-domain.example.com/mcp/oauth/callback` 添加为 SSO 应用注册中的重定向 URI。
AI 工具无法连接	检查 `MCP_PUBLIC_URL` 是否与用户机器可访问的 URL 匹配。确保 HTTPS 正常工作。
用户获得空结果	MCP 遵循 RBAC 权限。如果用户访问受限，他们只能看到其角色允许的卡片。
写入工具返回 `writes_disabled`	此部署上设置了 `MCP_WRITES_ENABLED=false`。读取工具仍可正常使用；如需写入，请联系运营者重新启用。
提交被拒绝并返回 `confirm_token_required`	该批次的行数超过了 `MCP_BATCH_CONFIRMATION_THRESHOLD`。请先以 `dry_run=true` 重新运行，然后在提交调用中回传返回的 `confirm_token`。
连接在 1 小时后断开	AI 工具应自动处理令牌刷新。如果不行，请重新连接。

工作原理​

前提条件​

设置​

步骤 1：启动 MCP 服务​

步骤 2：配置环境变量​

步骤 3：将 OAuth 重定向 URI 添加到 SSO 应用​

步骤 4：在管理设置中启用 MCP​

连接 AI 工具​

Claude Desktop​

VS Code（GitHub Copilot / Cursor）​

本地测试（stdio 模式）​

可用功能​

写入操作的演练安全机制​

变更批次（审计轨迹）​

读取工具​

写入工具​

典型的工件导入工作流​

写入工具防护栏​

资源​

引导提示​

权限​

安全性​

故障排除​