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语义图模型
每个实体（需求、功能、代码、测试、场景、步骤定义）都成为 类型结点，遵循多态模式：
{
"id": "code:src/domain/User.ts",
"kind": "Code",
"labels": ["Domain", "Entity"],
"properties": {
"name": "User",
"filepath": "src/domain/User.ts"
},
"metadata": {
"layer": "domain",
"status": "OK"
}
}边表示语义关系：
DEFINESIMPLEMENTED_BYVERIFIESEXECUTESCALLS
这是 金线.
______________________________________________________________________
🏛️ 3.特点
3.1架构分析
Hexanorm执行Alistair Cockburn（六边形架构）描述的规则：
- 领域 → 只能导入域
- 应用 → 可以依赖于域和端口
- 基础设施 → 可以依赖任何东西
- 接口/适配器 → 束缚外界
AST解析（通过 树保姆)提供精确的导入和依赖关系提取。
违规行为被报告为结构化对象：
{
"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爆炸半径分析
给定任何代码元素：
blast_radius("src/domain/VatService.ts")Hexanorm返回所有可能受影响的节点：
- 使用它的功能
- 它所执行的要求
- 间接执行代码路径的Gherkin场景
这将架构影响转化为可查询的结构——美国宇航局的IV&V设施称之为 _功能完整性_.
______________________________________________________________________
3.4文件监视/实时更新
使用 fsnotify，Hexanorm更新：
- 解析AST
- 图形节点
- 违规
- 跟踪矩阵
一旦开发人员保存文件。
这实现了“主动架构治理”。
______________________________________________________________________
🚀 4.使用方法
4.1安装
- 克隆存储库：
git clone https://github.com/modelcontextprotocol/go-sdk.git
cd examples/server/hexanorm- 构建服务器：
go build -o hexanorm-server4.2运行MCP服务器
go run . /path/to/projectHexanorm在STDIO上运行，并与任何MCP客户端（Claude Desktop、模型服务器、代理运行时）集成。
______________________________________________________________________
🧩 5.与克劳德桌面集成
添加到 claude_desktop_config.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.
特性
- 自动布局：自动排列域、应用程序和基础架构层。
- 实时同步：代码的更改反映在图表中（通过重新导出）。
- 语义着色:
- 🟦 领域：蓝色（核心逻辑） - 🟩 应用：绿色（用例） - 🟨 基础设施：黄色（适配器） - 🟥 违规：红色（非法依赖关系）
用法
要生成图表，请执行以下操作：
hexanorm export --format=excalidraw --out=architecture.excalidraw然后，您可以打开 architecture.excalidraw 在 excalidraw.com 或者使用VS Code Excalidraw扩展来直观地检查系统的“金线”。
______________________________________________________________________
🖥️ 9.终端接口（TUI）
Hexanorm包括丰富的 终端用户界面（TUI） 建造于 珍珠奶茶.
特性
- 可视化图形：在基于列的视图中探索您的架构层（域、应用程序、基础设施、接口）。
- 交互式导航：使用箭头键在图层和节点之间导航。
- 即时反馈：查看节点详细信息、连接和 建筑违规 实时。
用法
要启动TUI：
hexanorm tui [rootDir]例子：
./hexanorm-server tui .______________________________________________________________________
🧭 10.文献基础
Hexanorm的概念设计符合：
- 埃里克·埃文斯-- _领域驱动设计_ (2004)
- 阿利斯泰尔·科伯恩-- _六边形体系结构_ (2005)
- Jez Humble-- _持续交付_ (2011)
- Gojko Adzic-- _举例说明_ (2012)
- 萨姆·纽曼-- _构建微服务_ (2015)
______________________________________________________________________
🎯 9.总结
Hexanorm MCP将架构转换为 实时、可查询的知识图. 它允许LLM代理：
- 理解意图，
- 加强结构，
- 验证行为，
- 检测回归，
- 并指导开发人员完成复杂的变更操作。
这是一个 _智能建筑守护器_，一个“认知骗子”，一座连接 人类建筑 和 自动推理.