Enterprise Architect

Enterprise Architect MCP 服务

一个只读的 Model Context Protocol（MCP）服务，用于读取 Sparx Enterprise Architect .qea 导出文件。让 AI Agent 能够访问 EA 分析模型——搜索元素、浏览包、读取用例场景并遍历连接器，无需运行中的 EA 实例。

可与任何 MCP 客户端搭配使用（VS Code / GitHub Copilot、Claude Desktop、Cursor、Windsurf）。直接读取 .qea SQLite 导出文件，绝不写入文件；每个响应都包含完整性元数据，让 Agent 能区分截断的答案和完整答案。

关键词： MCP 服务 · Sparx Enterprise Architect · .qea · UML · 用例场景 · 包树 · 连接器 · 图表 · 模型搜索 · AI Agent 工具

先决条件

• Node.js 22+（使用内置的 node:sqlite 模块）
• 从 Sparx Enterprise Architect 导出的 .qea 文件

安装

VS Code / GitHub Copilot

最快的方式是点击本页顶部的 Install in VS Code 徽章。无需填写任何内容：Agent 首次查询模型时，服务会询问你的 .qea 路径，并记住该路径以供下次使用。

如果要从终端注册，以便编写脚本或共享配置，可以使用一条 CLI 命令：

code --add-mcp '{\"name\":\"enterprise-architect\",\"command\":\"npx\",\"args\":[\"-y\",\"enterprise-architect-mcp\"]}'

这些 \" 序列用于 code shim；PowerShell 将参数传递过去后，shim 会再次解析参数。使用 PowerShell 自带的反引号进行转义，或使用 --%，最终仍会导致引号被去掉。单引号可以防止 PowerShell 修改字符串。在 bash 或 zsh 中，可以直接使用以下命令：

code --add-mcp '{"name":"enterprise-architect","command":"npx","args":["-y","enterprise-architect-mcp"]}'

如果要手动配置，请将以下内容添加到项目的 .vscode/mcp.json：

{
  "servers": {
    "enterprise-architect": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "enterprise-architect-mcp"]
    }
  }
}

此文件不包含任何个人信息，因此可以直接提交；每位开发者只需在自己的计算机上回答一次提示。如果你希望完全跳过询问，可以预先指定路径——将其作为末尾参数、放在 env 区块中，或写入工作区根目录下受 git 忽略的 .env 文件：

EA_QEA_PATH=C:\EA\exports\model.qea

Claude Desktop

相同的不指定路径配置可放入 claude_desktop_config.json（Windows 上为 %APPDATA%\Claude\，macOS 上为 ~/Library/Application Support/Claude/）：

{
  "mcpServers": {
    "enterprise-architect": {
      "command": "npx",
      "args": ["-y", "enterprise-architect-mcp"]
    }
  }
}

Claude Desktop 不会从工作区文件夹运行服务，因此其中的 .env 不可靠。如果客户端完全无法显示路径提示，服务会明确告知，而不会静默失败；你也可以在 env 区块中指定路径：

"env": { "EA_QEA_PATH": "C:\\EA\\exports\\model.qea" }

如要直接从源码运行而不是使用 npm，请使用 "args": ["-y", "github:mm6502/enterprise-architect-mcp"]。

示例提示词

连接后，可以尝试以下提示：

• "搜索与 'legal entity' 相关的元素"
• "显示根目录下的包结构"
• "UC_SUBMIT_APPLICATION 的用例场景有哪些？"
• "图表 0103 Application Processing 上有哪些元素和连接器？"
• "解析引用 {3F2A7C10-5B4D-4e8a-9C1F-27D6E8B0A4F3}"
• "t_connector 有哪些列？"
• "元素 a7680 出现在哪些图表上？"

配置

服务启动时不需要路径。Agent 首次查询模型时，服务会查找路径，并使用第一个能够实际打开的来源：

1. CLI 参数 — mcp-server-ea C:\path\to\model.qea
2. 环境变量 — EA_QEA_PATH（在 env 块或系统环境中设置）
3. .env 文件 — 在工作目录的 .env 文件中设置 EA_QEA_PATH=...
4. 记住的回答 — 你上次告诉提示词的内容
5. 提示词 — 客户端会询问，并记住可用的回答以便下次使用

如果你不想看到提示——例如在 CI 作业或共享映像中，或者只是出于个人偏好——可以将路径写入工作目录中一个已添加到 gitignore 的 .env 文件。复制模板：

Copy-Item .env.example .env

然后在 .env 中设置本地路径：

EA_QEA_PATH=C:\EA\exports\model.qea

如果路径指向的是一个目录而不是文件，服务会根据修改时间自动选择其中最新的 .qea 文件——将路径指向你的导出文件夹，即可自动使用新导出的文件，无需重新配置：

EA_QEA_PATH=C:\EA\exports\

.env 文件已添加到 gitignore——每位开发者都可以设置自己的路径，而不会影响共享配置。该文件也永远不会提交，因此每位新用户都必须手动设置这一项；回答一次提示即可免去这一步。

如果某个来源指定的路径无法打开，服务会跳过它，而不会直接报错，然后尝试下一个来源。跳过原因会写入服务日志；如果之后有来源成功打开，ea_get_model_info 会在 skipped 下列出该来源。这是有意为之——否则，留在 env 块中的示例值会优先于你给出的所有回答，而回答提示也就毫无用处。这样做的代价是，真正的拼写错误也会被悄悄降级处理，因此如果服务打开的模型与你预期不同，请检查 ea_get_model_info。

只有在可以用回答替代被跳过的来源时，跳过才有意义，因此以下两种情况仍会直接报错：你通过命令行传入的路径（这是本次运行的明确指令，而不是过时的默认值）；以及无法显示提示的客户端中的任何无效来源——否则服务会悄悄打开其他模型，而不是告知你出错。

回答会按机器记住：Windows 上位于 %APPDATA%\enterprise-architect-mcp\，macOS 上位于 ~/Library/Application Support/enterprise-architect-mcp/，其他系统上位于 $XDG_CONFIG_HOME（或 ~/.config）；设置 EA_MCP_CONFIG_DIR 可将该文件存放在其他位置。无法打开的路径不会被记住，因此只需再次询问即可更正输入错误的回答。

可用工具

工具	描述
ea_search	对元素、属性、操作和约束进行全文搜索。接受 requiredTerms，这是一个术语列表，其中每个术语都必须出现在某个元素的可搜索文本中（合取）——术语不必出现在同一字段中，但出现在同一字段时排名更高。boostAnyOf 是可选的其他术语列表，可提升结果排名，但绝不会据此排除结果。对欧洲拉丁字母不区分大小写和变音符号，并会解码实体编码文本。每个结果都包含匹配依据——匹配字段、对应的属性或操作，以及作者原文摘录。接受 packageScope（包 ID 或名称）以将结果限制在某个包及其后代中；未指定范围时，会报告包分布。
ea_search_and_any_of	匹配方式与 ea_search 相同，另有 andAnyOf：一个可选术语列表，结果必须满足 requiredTerms 且至少满足一个 andAnyOf 术语——用于缩小结果范围，而非重新排序。当备选术语应该排除结果，而不仅仅是提升排名时，请使用此工具，而非 ea_search。
ea_get_element	元素的完整详情——属性、操作、出现该元素的图表、约束（前置条件／后置条件／不变式／流程）。标记属性多重性是否具有对比性。
ea_list_elements	列出包中的元素，可按类型筛选。采用分页窗口：报告总数，并支持使用 offset 分页。
ea_get_connectors	元素的关系——包括特征链接解析（每一端关联到哪个属性／操作）。Generalization 连接器的每一端都带有 role（child／parent）；使用 connectorType: "Generalization" 和 direction: "incoming"／"outgoing" 筛选，无需图表即可列出元素的直接子项／父项。
ea_get_diagram_elements	图表上的元素和连接器，包括隐含连接器和特征链接。elements 包含自由文本 Note 图表对象，这些对象通常包含图例或缩写定义。
ea_get_scenarios	用例场景步骤及其所有属性（触发条件、使用项、结果、链接、状态）和场景注释。步骤的 uses 可能会按代码名称引用业务规则或约束——该代码无法单独搜索，需通过对同一元素调用 ea_get_element 获取。
ea_get_package_tree	按递归深度浏览包层级结构。
ea_list_diagrams	按名称、类型和包搜索图表。与上述工具一样采用分页窗口。
ea_resolve	将分析人员引用（带大括号的 GUID 或普通名称）解析为模型候选项，并提供完整包路径。对于分析人员代码，会回退到名称前缀匹配；每个候选项都带有 match，值为 guid、exact 或 prefix。
ea_get_schema	查看模型的数据库架构——表、列、索引、rowid 别名。
ea_get_model_info	打开导出的身份信息——文件名、大小、修改日期、服务版本，以及路径所来自的配置源。

响应约定

每个工具都返回结构化 JSON，其中包含：

• _meta.sourceTables — 查询过的数据库表
• totalMatched / returned / truncated — 每个集合的完整性元数据
• continuation — 结果被截断时，用于获取完整集合的精确调用
• 对于不存在的对象，返回 isError: true + { error: "not_found" }（与空结果不同）

有两个字段可防止将不精确的答案误读为已确认答案：

• ea_resolve — 始终提供 match；只有 prefix 表示匹配不精确
• ea_get_element — _meta.attributes.multiplicityIsUniform: true 表示元素属性没有多重性差异，因此 1..1 不能作为必需性的证据

结果的排序、分页和缩小范围

名称排序

匹配不受区域设置影响——搜索会对欧洲拉丁字母中的大小写和变音符号进行折叠处理，因此无论以何种形式输入或进行实体编码，都能找到 Straße、Łódź 和 Győr。

枚举工具——ea_search、ea_list_elements、ea_list_diagrams——完全不按名称排序。它们按模型的内部标识排序：稳定且可重复，但属于人为顺序，因此不应对相邻行的排列做任何解读。这是有意的取舍。在 SQLite 的二进制排序规则下，按字母排序会把所有带重音的首字母排在 Z 之后；而且由于这些工具返回的是一个窗口，而非整个集合，这不仅会改变列表顺序，还会把带重音的名称完全挤出窗口。在一次真实导出中测得，在采用二进制排序的情况下，首字母带重音的名称仅占可见条目的 1.3%；采用标识排序时则占 3.0%，而在该模型中，这类名称占全部名称的 3.9%。

只有 ea_get_scenarios 仍按区域设置对名称排序，因为它总是返回整个集合，不会截断任何名称。EA_LOCALE 可在 env 块或系统环境变量中设置为 BCP 47 标签（sk、pl、hu、de……），以固定排序规则；未设置时使用主机默认值。它不会影响匹配。

分页与缩小范围

枚举工具返回的是一个窗口，而不是抽样结果。每个响应都包含 totalMatched、returned、offset 和 truncated；若仍有剩余行，还会提供一个名为 continuation 的下一次调用。反复跟进它即可恰好遍历每个匹配项一次，并最终结束。读取大型集合时，增大 limit 并非正确做法；应递增 offset。

当匹配行数远超单个窗口的容量时，响应还会包含一个 breakdown，展示这些行的分布情况。其键为参数名称，值为参数值，因此应根据它缩小范围——使用 objectType、stereotype、diagramType，或者在 ea_search 的结果尚未限定范围时使用 packageScope（报告的值是匹配包的 id，下一次调用可直接传回）——而不是翻阅数千行。

许可证

版权所有（c）2026 Michal Mracka

依据 EUPL 许可——完整文本请参阅 LICENSE。