# 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`](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:

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

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

   ```text
   http://architectural-mcp:8000/mcp
   ```

6. Import [`hermes-skill/SKILL.md`](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:

```bash
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

```bash
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`](examples/restaurant-100m2.json) for the `PlanSpec` shape.

## Container publishing

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

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

## License

MIT