README.md

---
title: CrossBeam MCP Server
emoji: 🔌
colorFrom: indigo
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
---

# CrossBeam MCP Server — municipal plan review for agentic AI

Exposes the CrossBeam plan-review engine as **MCP tools** for any agent platform:
Claude, ChatGPT, Gemini, n8n, HF UI, local clients, or through a tunnel.

**Endpoint:** `https://<user>-<space>.hf.space/mcp`  (both `/mcp` and `/mcp/` work)

## Tools

| Tool | What it does |
|---|---|
| `list_municipalities` | Configured jurisdictions and their code/bylaw frameworks |
| `list_review_tracks` | Review types (suites, multi-residential, institutional…) + available models |
| `list_knowledge` | The knowledge base reviews are grounded in |
| `review_plan_set` | Review a plan set (PDF, base64) → structured findings, technical screening report, and City-style Detailed Review |
| `analyze_corrections_letter` | Interpret a corrections letter → item-by-item analysis + draft response |
| `generate_checklist` | Pre-submission checklist for a project type |

The first three need no API key. The rest call an LLM provider — pass `api_key`
per call, or set a Space secret (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
`GEMINI_API_KEY`, `GROQ_API_KEY`) and pass just `provider`.

**The agent's own model does not perform the review.** These tools run the
deterministic engine — scope gate, grounded citations, verdict reconciliation — so
the guarantees hold no matter which client calls them. In particular the corrections
draft never claims a correction is resolved; every resolution is an
`[APPLICANT: …]` placeholder.

### City of Calgary Detailed Review output

For Calgary reviews, pass municipal metadata when it is available:

- `application_number`, `site_address`, `applicant`, and `community`
- `land_use_district` and `use_type`
- `planning_contact`, `date_dr_sent`, and `response_due_date`
- `municipal_records_context` for verified City facts not shown on the drawings,
  such as an existing registered or permitted secondary suite

The returned `city_review_letter_markdown` follows the City's Development Permit
sequence: application header, General Comments, Bylaw Discrepancies
(`Regulation | Standard | Provided`), Prior to Decision Requirements, applicant
options, and Advisory Comments. Building-code and engineer-of-record observations
remain in the separate technical report and are not presented as City DP conditions.

The Calgary suite track deterministically reconciles parcel coverage, parking for
each dwelling unit, backyard-suite rear setback, closest-façade separation, private
amenity space, and same-parcel suite density. A missing check becomes a verification
item; the engine does not silently omit it or invent compliance.

## Running locally (STDIO, e.g. Claude Desktop)

```bash
pip install -r requirements.txt
python mcp_server.py          # STDIO
MCP_HTTP=1 MCP_PORT=7860 python mcp_server.py   # HTTP for remote clients
```

See `mcp_config_examples.md` for per-client configuration.

## Any municipality

Same as the UI Space: add `jurisdictions/<city>.yaml` and that city's `skills/`.
Callers select it with the `municipality` argument. See `FORKING.md`.