# sap-arch-mcp

MCP server that exposes the **sap-architecture** skill pipeline as tools, so an
LLM agent can generate SAP Architecture Center-style `.drawio` diagrams using
the full deterministic pipeline (template scaffolding, icon extraction,
autofix, validation, corpus scoring) instead of fetching raw files per request.

## Tools exposed

| Tool | Purpose |
|---|---|
| `list_templates` | Browse/filter the 71 bundled official SAP templates |
| `scaffold` | Rank templates against a request, copy best match, return XML + design recipe (mandatory first step) |
| `extract_icon` | Official BTP service icon → ready-to-paste mxCell (32×32, grid-snapped) |
| `extract_asset` | Any starter-kit asset: connectors, area shapes, numbers, brand names |
| `autofix` | Mechanical fixes: grid, hex case, absoluteArcSize, strokeWidth, fonts |
| `validate` | Full SAP-style validator (bent arrows, palette, overlap, pill verbs...) |
| `score` | Corpus similarity / SAP-likeness gate (PASS ≥ 90) |
| `compare` | Fingerprint diff against one named template |
| `render_png` | Headless PNG export (optional, needs drawio + xvfb) |
| `get_reference_doc` | Read skill reference docs (gotchas, palette, layout...) |

## Quick start (Docker, recommended)

```yaml
# docker-compose.yml
services:
  sap-arch-mcp:
    image: python:3.12-slim
    container_name: sap-arch-mcp
    restart: unless-stopped
    ports:
      - "8600:8600"
    volumes:
      - ./sap-architecture:/opt/sap-architecture:ro
      - sap-arch-work:/work
    environment:
      SKILL_DIR: /opt/sap-architecture
      WORK_DIR: /work
    command: >
      sh -c "pip install --quiet 'mcp[cli]' mcpo &&
             mcpo --host 0.0.0.0 --port 8600 --
             python3 /opt/sap-architecture/mcp-server/server.py"
volumes:
  sap-arch-work:
```

```bash
git clone https://git.alexzaw.dev/alexz/sap-architecture.git
docker compose up -d
```

Put the container on the same Docker network as OpenWebUI if you want to
reference it by service name.

## Wire into OpenWebUI

**Admin Settings → Tools → Add Connection** → `http://sap-arch-mcp:8600`
(or `http://<host>:8600`). The tools appear automatically; mcpo serves
OpenAPI docs at `/docs`.

## Optional: PNG rendering

Inside the container (or bake into an image):

```bash
apt-get update && apt-get install -y wget xvfb libgbm1 libasound2 libnss3 libgtk-3-0
wget -O /tmp/drawio.deb https://github.com/jgraph/drawio-desktop/releases/download/v28.0.6/drawio-amd64-28.0.6.deb
apt-get install -y /tmp/drawio.deb
printf '#!/bin/bash\nexec xvfb-run -a /usr/bin/drawio "$@" --no-sandbox --disable-gpu\n' > /usr/local/bin/drawio-headless
chmod +x /usr/local/bin/drawio-headless
export DRAWIO_CLI=/usr/local/bin/drawio-headless
```

Without it, everything except `render_png` works — the validator and scorer
are the real quality gates.

## Agent workflow (what the LLM should do)

1. `scaffold(request)` → pristine SAP template XML + design recipe
2. Surgical relabel of the XML (never draw from scratch)
3. `extract_icon` / `extract_asset` for any new cards
4. `autofix(xml)` → `validate(xml)` → fix errors → repeat
5. `score(xml)` → PASS ≥ 90, else `compare` against the source template and restore drift
6. Deliver `.drawio` (+ `render_png` if requested), narrate the flow below the diagram