内容
# mcp-archimate
[](https://github.com/byrondelgado/mcp-archimate/actions/workflows/ci.yml)
[](https://pypi.org/project/mcp-archimate/)
[](https://pypi.org/project/mcp-archimate/)
[](https://github.com/byrondelgado/mcp-archimate/blob/main/LICENSE)
MCP服务器，允许AI代理构建、验证和导出真正的ArchiMate模型 - 可以在Archi中打开并支持往返。
它通过stdio提供了45种工具、9种资源和4种引导式提示。代理描述架构；服务器强制执行ArchiMate允许的操作、布局图并写入文件。
```
"为我们的订单到现金流建模，然后导出以便我可以在Archi中打开它。"
```
## 为什么存在
直接要求模型输出ArchiMate XML会产生看起来似是而非的文件，但无法在Archi中打开。关系类型被发明，ID无法解析，图表没有坐标。
该服务器弥补了这一差距。它将模型保存在内存中，拒绝具有有效替代方案的无效关系，定位每个节点并路由每个连接，并通过pyArchimate序列化，而不是字符串模板。**它不拥有自己的ArchiMate规则** - 每个有效性裁决都被委托给pyArchimate的关系矩阵（兼容ArchiMate 3.2），因此它不会演变成私有方言。
劳动分工是刻意的：服务器是一个*约束引擎*，代理是架构师。它会告诉您`BusinessProcess`无法提供`ApplicationService`以及可以提供什么；它不会决定您的架构应该是什么。
## 安装
无需克隆。使用[uv](https://docs.astral.sh/uv/)：
```bash
uvx mcp-archimate
```
这会通过stdio运行服务器，这是MCP客户端想要的。手动在终端中运行它只会等待JSON-RPC - 这是正确的。
替代方案：
```bash
pipx run mcp-archimate
pip install mcp-archimate
```
需要Python 3.10或更新版本。
## 连接到客户端
**Claude 代码：
```bash
claude mcp add archimate -- uvx mcp-archimate
```
**Claude 桌面版** - 在`claude_desktop_config.json`中：
```json
{
"mcpServers": {
"archimate": {
"command": "uvx",
"args": ["mcp-archimate"]
}
}
}
```
**Codex** - 在`~/.codex/config.toml`中：
```toml
[mcp_servers.archimate]
command = "uvx"
args = ["mcp-archimate"]
```
**MCP 检验器：
```bash
npx @modelcontextprotocol/inspector uvx mcp-archimate
```
无需API密钥、无需环境变量、无需配置文件。服务器不需要它们。
## 示例提示
您用日常语言与代理交流；它选择工具。下面工具名称只是它要查找的内容，以便您可以跟随。
这里的所有内容都可以直接复制粘贴。首先从第一个开始。
### 构建小模型
```
创建一个客户入职流程的ArchiMate模型。涵盖业务层（客户、入职流程、身份验证）和应用层（入职门户和身份验证服务）。正确连接它们，放入一个视图、布局并导出，以便我可以在Archi中打开它。
```
*使用`create_empty_model` → `add_element` → `add_relationship` → `create_view` → `auto_layout_view` → `export_model_to_file`。*
### 探索已有模型
```
加载 ~/models/enterprise.archimate 并告诉我它包含什么：大小、每个层的內容以及是否有损坏的内容。
```
`load_model_from_file` 加载 **并** 检查，一次调用即可获取计数、验证状态和视图摘要。
后续跟进值得询问：
```
哪些元素未在任何视图中使用？
```
```
显示依赖于支付服务的所有内容。
```
### 编辑现有模型
首次构建后常见的情况。明确说明要更改的内容，代理将进行有针对性的编辑，而不是重建。
```
在模型中添加一个“欺诈筛查”应用程序服务，使其为结账流程提供服务，并将其托管在与支付服务相同的节点上。然后重新布局它出现的视图。
```
```
将所有“客户管理服务”重命名为“客户管理服务”，并添加一个解释其功能的正确描述。
```
```
订单服务和库存服务通过服务关系连接，但应为异步关系。将其更改为流关系，并告诉我这是否有效的ArchiMate。
```
最后一个值得尝试 - 服务器将告诉您哪些关系类型在两个元素类型之间是合法的，并提供替代方案，而不是默默接受Archi拒绝的内容。
### 改进模型
```
检查此模型是否存在质量问题，并修复那些可以安全修复的问题。解释无法自动修复的内容以及原因。
```
*使用`build_quality_report` → `repair_semantic_issues`。服务器仅自动修复确定性案例；任何需要架构决策的内容都会被报告给您，而不是被猜测。*
```
```
每张图表都是一个方框。添加层带，重新布局，并添加注释以解释每个图表的用途。
```
```
有些关系在任何视图中都未显示。找到它们并添加一个覆盖视图，以便没有任何内容被隐藏。
```
### 验证和导出
```
检查模型是否存在问题，然后以Archi的原生格式将模型导出到 ~/Desktop/architecture.archimate，具有严格的质量门控，确保不会写入损坏的文件。
```
`quality_gate="strict"` 在视觉、语义或覆盖失败时阻止导出 - 在文件交给他人时很有用。
要 *查看* 图表而不打开Archi：
```
将应用程序协作视图渲染到桌面上的SVG文件。
```
### 完整构建
一个单独的提示，调用大部分服务器。预计需要几分钟，并调用许多工具。
```
创建一个代表现实的综合电子商务架构的ArchiMate模型（与真实公司无关）。使用archimate MCP工具。范围：
- 业务层：客户 / 仓库员工 / 支持代表的角色，具有核心流程（浏览，购物车，结账，支付，履行，支持），业务服务和关键业务对象（订单，客户帐户）。
- 应用层：微服务 - Storefront Web应用程序，API网关和每个功能（目录，搜索，购物车，结账，支付，订单管理，库存，运输，通知，客户支持）的组件+服务对，以及它们的数据对象。
- 技术层：云基础设施 - 容器编排，每个需要一个的服务数据库，缓存，消息代理用于异步事件，负载均衡器/ CDN和外部支付网关节点。
- 关系：标准ArchiMate约定（ApplicationService服务BusinessProcess，Component实现Service，Node服务Component进行托管，Access用于数据读取/写入，Flow用于异步事件）。使用semantic_validation='strict'验证并修复任何无效组合，使用建议的修复。
- 视图：业务流程视图，应用程序协作视图，技术部署视图和显示一个跨层切片（结账旅程端到端）的分层概述。自动布局每个视图并添加层带。
- 运行ensure_all_relationships_in_views，build_quality_report和validate_model，然后导出。导出时使用quality_gate='strict'。
在整个过程中添加描述和注释。
跳过澄清问题 - 直接开始构建。
```
最后一行很重要。没有它，一个好的代理会停止并要求您缩小范围，这通常是正确的本能，但这不是您想要的。
### 代理说明
首先调用`get_usage_guide`。它返回操作规则、常见反模式和推荐的调用序列 - 它的存在是为了让代理不必阅读此服务器的源代码来了解如何使用它。
## 内容
| | |
| --- | --- |
| **模型** (17 工具) | 创建、加载、导出、元数据、质量报告、TOGAF 准备就绪 |
| **视图** (12 工具) | 创建视图、添加节点、自动布局、层带、图表注释、SVG 渲染 |
| **关系** (7 工具) | 创建、验证、兼容性查找、意图推荐、确定性修复 |
| **元素** (4 工具) | 添加、更新、删除、查询 |
| **工作流** (3 工具) | 使用指南、加载和检查、检查活动模型 |
| **查询** (2 工具) | 模型的筛选搜索 |
| **资源** (6 + 3 模板) | 在 `pyarchimate://activemodel/...` 下的模型只读视图；三个模板化资源由 `resources/templates/list` 返回 |
| **提示** (4) | 引导式加载 → 检查 → 编辑 → 验证 → 导出工作流 |
完整的参数和响应文档在 **用户指南** 中。
### 两种导出格式 - 它们不可互换
| `output_format` | 生成 | 在 Archi 中 |
| --- | --- | --- |
| `"archi"` | Archi 的原生 `.archimate` | **直接打开** |
| `"archimate"` *(默认)* | 开放组交换 XML | 必须 **导入** |
SVG 不是第三种格式。`render_view_to_svg_file` 编写一个人类查看的图片；它不携带模型语义，无法加载回来。
### 布局
图表被布局，而不是简单地填充：节点按 ArchiMate 层顺序放置，具有车道包装和重心对齐，多层视图具有标记的层带，连接在障碍物周围路由，而不是作为对角线绘制穿过方框。
## 安全考虑
在将代理指向此服务器之前，有两件事值得了解。完整的图片，包括如何报告漏洞，在 [SECURITY.md](https://github.com/byrondelgado/mcp-archimate/blob/main/SECURITY.md) 中。
**它具有您的文件系统权限。** `load_model_from_file` 读取您可以读取的任何路径；`export_model_to_file` 和 `render_view_to_svg_file` 写入您可以写入的任何路径，覆盖时无需提示。目前尚无允许根目录限制；这对于本地 MCP 服务器来说是常见的，但这里的调用者通常是 LLM 代理，而不是人员输入路径 - 因此像对待代理建议的 shell 命令一样对待路径参数，并将导出指向工作目录而不是不可替换的位置。如果您现在需要一个硬边界，可以在容器中运行服务器或在专用帐户下运行。
**模型文件是不可信的输入。** 加载程序拒绝 DTD 和实体声明，直接解析，禁用外部实体解析和网络访问，限制内容为 10 MB，并允许列出根元素 - 因此阻止了 XXE 和实体扩展攻击，并在 `tests/test_security.py` 中进行了对抗性验证，而不是假设。 它无法阻止提示注入：元素名称、文档和属性是攻击者可控的文本，流回您的代理。 将模型内容视为数据，而非指令。
服务器不进行网络请求，不收集任何遥测数据，也不需要任何凭证。
## 文档
| 文档 | 适用于 |
| --- | --- |
| [用户指南](https://github.com/byrondelgado/mcp-archimate/blob/main/docs/USER_GUIDE.md) | 任何人。工具参数、响应模式、工作流程、故障排除 |
| [技术架构](https://github.com/byrondelgado/mcp-archimate/blob/main/docs/TECHNICAL_ARCHITECTURE.md) | 贡献者。设计、层、pyArchimate 使用模式 |
| [布局改进计划](https://github.com/byrondelgado/mcp-archimate/blob/main/docs/LAYOUT_IMPROVEMENT_PLAN.md) | 布局工作。测量和拒绝的方法 |
| [质量和验证 PRD](https://github.com/byrondelgado/mcp-archimate/blob/main/docs/MCP_Feedback_Improvements.md) | 验证工具套件和约束引擎拆分 |
| [变更日志](https://github.com/byrondelgado/mcp-archimate/blob/main/CHANGELOG.md) | 最新更改 |
| [贡献](https://github.com/byrondelgado/mcp-archimate/blob/main/CONTRIBUTING.md) | 设置、分支模型、如何提出更改 |
| [安全](https://github.com/byrondelgado/mcp-archimate/blob/main/SECURITY.md) | 信任模型和漏洞披露 |
| [决策记录](https://github.com/byrondelgado/mcp-archimate/tree/main/.backlog/decisions) | 架构决策记录 - 事情为什么是这样的 |
## 开发
```bash
git clone https://github.com/byrondelgado/mcp-archimate.git
cd mcp-archimate
uv sync --all-groups
uv run pytest
uv run ruff check
uv run mcp dev pyarchimate_mcp_server/server.py # 使用 MCP 检验器
```
参见 [CONTRIBUTING.md](https://github.com/byrondelgado/mcp-archimate/blob/main/CONTRIBUTING.md) 了解分支模型和约定，以及 [CLAUDE.md](https://github.com/byrondelgado/mcp-archimate/blob/main/CLAUDE.md) 了解存储库的操作合同 - 它记录了几个看起来像错误但并非如此的内容。
## 致谢
该服务器基于 **pyArchimate**，由 **Xavier Mayeur** 构建，它完成了实际的ArchiMate建模工作。该服务器创建、读取、布局、验证和导出的每个模型都通过它。如果这个项目对您有帮助，那么pyArchimate就是原因。
## 许可
**GPL-3.0-or-later.** 有关完整文本，请参见 [LICENSE](https://github.com/byrondelgado/mcp-archimate/blob/main/LICENSE) 和 [NOTICE](https://github.com/byrondelgado/mcp-archimate/blob/main/NOTICE) 以了解属性。
这是继承的，而不是选择的。pyArchimate 是 GPL-3.0-only，并且是一个必需的运行时依赖项 - 服务器无法在没有它的情况下运行 - 因此您实际运行的组合工作由 GPL 管理。发布此服务器的宽松条款将误导该。
这意味着在实践中：
- **使用服务器不会将您的模型置于GPL之下。** 您生成的 `.archimate` 和交换文件是您自己的作品，就像在GPL文本编辑器中编写的文档一样。
- **它不会影响调用它的代理或客户端。** MCP服务器是一个独立进程，通过stdio JSON-RPC进行通信。版权仅适用于分发 *此程序*，而不适用于通过该边界与之交互的软件。
- **如果您分发此服务器的修改版本或将其包含在您分发的其他内容中，则它适用。** 然后，GPL的源代码可用性条款适用于该作品。
这是纯语言摘要，而不是法律建议。请阅读许可证，如果区别对您的情况很重要，请获取您自己的建议。
---
ArchiMate是The Open Group的注册商标。该项目是独立实现的，与The Open Group或Archi项目无关，也未获得其认可或支持。
