Hexanorm MCP——架构守护者和语义可追溯引擎
Hexanorm MCP是一种 MCP(模型上下文协议)服务器 旨在作为现代软件系统的架构哨兵。
它结合了:
- 静态分析
- 语义图建模
- 六边形架构执行
- BDD可追溯性
- 冲击分析(爆炸半径)
- LLM友好的MCP资源和工具
它的目的是允许AI代理(Claude、Gemini、GPT)对 意图, 结构 和 行为 Martin Fowler将其描述为“使建筑可见“——同时保持 领域驱动设计 (Evans,2004)和 举例说明 (Adzic,2012)。
📘 1.目的
Hexanorm构造了一个 语义知识图 该项目。
此图模拟:
- 需求 (外部意图)
- 特性 (逻辑模块)
- 代码元素 (类、函数、文件)
- 测试 (单元测试、集成测试、BDD场景)
- 小黄瓜规格 (给定/何时/然后语义)
这使LLM能够:
✔ 识别架构违规
“域层取决于基础架构”→ 关键的.
✔ 检测BDD不一致(BDD漂移)
场景已更改,但步骤定义未更改。
✔ 跟踪实施要求(金线)
REQ → 特性→ Code → Test.
✔ 计算功能 爆炸半径
“如果我修改此文件,哪些要求和场景可能会中断?”
✔ 用结构洞察力指导重构
例如,“从基础结构中移动此文件→ 应用程序”。
🧠 2.核心概念
2.1语义图模型
每个实体(需求、功能、代码、测试、场景、步骤定义)都成为 类型结点,遵循多态模式:```json
{
"id": "code:src/domain/User.ts",
"kind": "Code",
"labels": ["Domain", "Entity"],
"properties": {
"name": "User",
"filepath": "src/domain/User.ts"
},
"metadata": {
"layer": "domain",
"status": "OK"
}
}
边表示语义关系:
- `DEFINES`
- `IMPLEMENTED_BY`
- `VERIFIES`
- `EXECUTES`
- `CALLS`
这是 **金线**.
______________________________________________________________________
## 🏛️ **3.特点**
### **3.1架构分析**
Hexanorm执行Alistair Cockburn(六边形架构)描述的规则:
- **领域** → 只能导入域
- **应用** → 可以依赖于域和端口
- **基础设施** → 可以依赖任何东西
- **接口/适配器** → 束缚外界
AST解析(通过 **树保姆**)提供精确的导入和依赖关系提取。
违规行为被报告为结构化对象:```json
{
"severity": "CRITICAL",
"message": "Domain Rule Broken: User.ts imports S3Bucket (Infrastructure)",
"file": "src/domain/User.ts",
"kind": "ARCH_LAYER_VIOLATION"
}
3.2 BDD可追溯性和漂移检测
Hexanorm解析:
.feature文件→GherkinFeature,GherkinScenario- 代码中的步骤定义→ 通过AST(
@Given,@When,@Then图案) - 链接场景→ 步骤定义→ Code → 需求
它可以检测:
BDD漂移
当Gherkin文本发生变化(步骤文本哈希不匹配)但StepDefinition没有变化时。
这实现了中描述的一致性层 BDD在行动 (Smart,2014)。
3.3爆炸半径分析
给定任何代码元素:```json
blast_radius("src/domain/VatService.ts")
Hexanorm返回所有可能受影响的节点:
- 使用它的功能
- 它所执行的要求
- 间接执行代码路径的Gherkin场景
这将架构影响转化为可查询的结构——美国宇航局的IV&V设施称之为 _功能完整性_.
______________________________________________________________________
### **3.4文件监视/实时更新**
使用 `fsnotify`,Hexanorm更新:
- 解析AST
- 图形节点
- 违规
- 跟踪矩阵
一旦开发人员保存文件。
这实现了“主动架构治理”。
______________________________________________________________________
## 🚀 **4.使用方法**
### **4.1安装**
1. **克隆存储库:**```bash
git clone https://github.com/modelcontextprotocol/go-sdk.git
cd examples/server/hexanorm
- 构建服务器:```bash
go build -o hexanorm-server
### **4.2运行MCP服务器**```bash
go run . /path/to/project
Hexanorm在STDIO上运行,并与任何MCP客户端(Claude Desktop、模型服务器、代理运行时)集成。
🧩 5.与克劳德桌面集成
添加到 claude_desktop_config.json:```json
{
"mcpServers": {
"hexanorm": {
"command": "/absolute/path/to/hexanorm-server",
"args": ["/absolute/path/to/target/project"]
}
}
}
_注:更换 `/absolute/path/to/target/project` 使用您要分析的目录。_
______________________________________________________________________
## 🛠️ **6.可用工具**
|工具|目的|
| -------------------------- | --------------------------------------------------- |
| **脚手架特征** |为新特征生成完整的六边形骨架|
| **链接要求** |手动链接代码→ 要求|
| **爆炸半径** |查询影响分析|
| **index_step_dentions** |解析和重建BDD步骤定义|
______________________________________________________________________
## 📡 **7.可用资源**
|资源|描述|
| ------------------------------------ | -------------------------------------- |
| `mcp://hexanorm/status` |图健康状况+节点计数|
| `mcp://hexanorm/violations` |所有架构+BDD违规|
| `mcp://hexanorm/traceability_matrix` |完整的金线地图|
| `mcp://hexanorm/live_docs` |建筑Markdown文档|
______________________________________________________________________
## 🎨 **8.排样可视化**
Hexanorm通过允许您弥合代码和图表之间的差距 **将您的架构直接导出到Excalidraw**.
### **特性**
- **自动布局**:自动排列域、应用程序和基础架构层。
- **实时同步**:代码的更改反映在图表中(通过重新导出)。
- **语义着色**:
- 🟦 **领域**:蓝色(核心逻辑)
- 🟩 **应用**:绿色(用例)
- 🟨 **基础设施**:黄色(适配器)
- 🟥 **违规**:红色(非法依赖关系)
### **用法**
要生成图表,请执行以下操作:```bash
hexanorm export --format=excalidraw --out=architecture.excalidraw
然后,您可以打开 architecture.excalidraw 在 excalidraw.com 或者使用VS Code Excalidraw扩展来直观地检查系统的“金线”。
🖥️ 9.终端接口(TUI)
Hexanorm包括丰富的 终端用户界面(TUI) 建造于 珍珠奶茶.
特性
- 可视化图形:在基于列的视图中探索您的架构层(域、应用程序、基础设施、接口)。
- 交互式导航:使用箭头键在图层和节点之间导航。
- 即时反馈:查看节点详细信息、连接和 建筑违规 实时。
用法
要启动TUI:```bash
hexanorm tui [rootDir]
例子:```bash
./hexanorm-server tui .
🧭 10.文献基础
Hexanorm的概念设计符合:
- 埃里克·埃文斯-- 领域驱动设计 (2004)
- 阿利斯泰尔·科伯恩-- 六边形体系结构 (2005)
- Jez Humble-- 持续交付 (2011)
- Gojko Adzic-- 举例说明 (2012)
- 萨姆·纽曼-- 构建微服务 (2015)
🎯 9.总结
Hexanorm MCP将架构转换为 实时、可查询的知识图.
它允许LLM代理:
- 理解意图,
- 加强结构,
- 验证行为,
- 检测回归,
- 并指导开发人员完成复杂的变更操作。
这是一个 智能建筑守护器,一个“认知骗子”,一座连接 人类建筑 和 自动推理.
