Hermes Architectural MCP

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

它保证什么

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

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

功能

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

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

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

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

• 构建一个 Blender 模型并在 CPU 上渲染可重复的室内/室外视图；

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

• 通过 /mcp 上的 MCP Streamable HTTP 公开工具。

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

使用 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

• list_project_outputs

有关 PlanSpec 的结构，请参阅 examples/restaurant-100m2.json。

容器发布

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

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

许可证

MIT