Hermes Architectural MCP

一个开源、Docker 优先的 MCP 服务，将现有建筑平面图转换为经过尺寸验证的毫米级几何体、IFC 模型以及为 Hermes Studio 生成一致的 CPU 渲染视图。

它保证什么

该服务将视觉解释与确定性几何体分离。在显式 PlanSpec 通过边界、预期面积、包含关系和重叠检查之前，它不会导出 IFC 或渲染项目。

PDF 尺寸仅被视为候选值。精确几何体必须以毫米表示并通过验证。这可以防止 100 m2 的平面图被呈现为视觉上放大但尺寸上无依据的设计。

Related MCP server: WalkMyPlan MCP Server

功能

• 检查矢量或栅格 PDF 平面图并渲染审查预览；

• 检测尺寸文本候选值而不自动信任它们；

• 验证场地边界、空间、总面积、包含关系和重叠；

• 拒绝仅视觉几何体以及仅为匹配声明面积而调整大小的边界；

• 使用 IfcOpenShell 将验证过的墙体导出为 IFC；

• 排队 CPU Blender 渲染任务，使长时间渲染不会占用 MCP 连接；

• 持久化源文件、报告、IFC、.blend 和 PNG 输出；

• 暴露内部下载 URL，使 Hermes 可以将交付物复制到其工作区；

• 通过 MCP Streamable HTTP 在 /mcp 暴露工具。

这是一个早期工程版本。它不能替代持证专业人士进行的建筑、结构、生命安全、无障碍或当地规范审查。

使用 Dockhand 部署

提供的 compose.yaml 加入现有的名为 proxy 的外部 Docker 网络，并且不发布主机端口。

1. 使用 compose.yaml 创建或更新 Dockhand 堆栈。

2. 确认 proxy 网络已存在。

3. 部署堆栈。

4. 从 proxy 上的另一个容器验证：

   curl http://architectural-mcp:8000/health

5. 在 Hermes Studio 中，添加一个 HTTP MCP 服务器，使用：

   http://architectural-mcp:8000/mcp

6. 将 hermes-skill/SKILL.md 导入为 Hermes 技能。

容器将项目存储在名为 architectural_projects 的命名卷中。

内部 PDF 上传

MCP 工具接受 base64 PDF，但本地文件通过内部 Docker 网络上传更高效：

curl --fail --silent --show-error \
  -H 'Content-Type: application/pdf' \
  --data-binary '@/workspace/plan.pdf' \
  'http://architectural-mcp:8000/api/projects/my-project/plan-pdf'

提供的堆栈中没有向主机发布上传路由。

开发

uv sync --extra dev
uv run ruff check src tests
uv run pytest -q
docker build -t hermes-architectural-mcp:local .

MCP 工具

• service_info

• analyze_plan_pdf

• create_or_update_plan

• validate_project

• export_project_ifc

• render_project_views

• get_render_job

• list_project_outputs

参见 examples/restaurant-100m2.json 了解 PlanSpec 的结构。

容器发布

推送到 main 会运行测试并发布 linux/amd64 镜像到：

ghcr.io/twuijri/hermes-architectural-mcp:latest

许可证

MIT