Hermes Architectural MCP

An open-source, Docker-first MCP service that converts existing architectural plans into dimension-verified millimetre geometry, IFC models, and consistent CPU-rendered views for Hermes Studio.

What it guarantees

The service separates visual interpretation from deterministic geometry. It will not export IFC or render a project until its explicit PlanSpec passes boundary, expected-area, containment, and overlap checks.

PDF dimensions are treated as candidates only. Exact geometry must be represented in millimetres and validated. This prevents a 100 m2 plan from being presented as a visually enlarged but dimensionally unsupported design.

Capabilities

• inspect vector or raster PDF plans and render a review preview;
• detect dimension text candidates without trusting them automatically;
• validate site boundaries, spaces, total area, containment, and overlaps;
• reject visual-only geometry and boundaries resized merely to match a stated area;
• export validated walls as IFC using IfcOpenShell;
• queue CPU Blender render jobs so long renders do not hold the MCP connection open;
• persist source files, reports, IFC, .blend, and PNG outputs;
• expose internal download URLs so Hermes can copy deliverables into its workspace;
• expose tools through MCP Streamable HTTP at /mcp.

This is an early engineering release. It does not replace architectural, structural, life-safety, accessibility, or local-code review by licensed professionals.

Deploy with Dockhand

The provided compose.yaml joins an existing external Docker network named proxy and does not publish a host port.

1. Create or update a Dockhand stack using compose.yaml.

2. Confirm the proxy network already exists.

3. Deploy the stack.

4. From another container on proxy, verify:

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

5. In Hermes Studio, add an HTTP MCP server with:

   http://architectural-mcp:8000/mcp
   

6. Import hermes-skill/SKILL.md as a Hermes skill.

The container stores projects in the named volume architectural_projects.

Internal PDF upload

The MCP tool accepts base64 PDFs, but local files are more efficiently uploaded over the internal Docker network:

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'

No upload route is published to the host in the supplied stack.

Development

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

MCP tools

• service_info
• analyze_plan_pdf
• create_or_update_plan
• validate_project
• export_project_ifc
• render_project_views
• get_render_job
• list_project_outputs

See examples/restaurant-100m2.json for the PlanSpec shape.

Container publishing

Pushes to main run tests and publish linux/amd64 images to:

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

License

MIT