Hexanorm MCP

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"
  }
}

边表示语义关系：

• DEFINES
• IMPLEMENTED_BY
• VERIFIES
• EXECUTES
• CALLS

这是 金线.

______________________________________________________________________

🏛️ 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安装

1. 克隆存储库：

   git clone https://github.com/modelcontextprotocol/go-sdk.git
   cd examples/server/hexanorm

1. 构建服务器：

   go build -o hexanorm-server

4.2运行MCP服务器

go run . /path/to/project

Hexanorm在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.可用工具

______________________________________________________________________

📡 7.可用资源

______________________________________________________________________

🎨 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代理：

• 理解意图，
• 加强结构，
• 验证行为，
• 检测回归，
• 并指导开发人员完成复杂的变更操作。

这是一个 _智能建筑守护器_，一个“认知骗子”，一座连接 人类建筑 和 自动推理.