# Claims desk — MCP Apps

Personal demo by [Andrew Espira](https://github.com/espirado).

A claims reviewer **MCP App**: one tool returns structured prior-auth / attachment / filing guidance plus `doc://` citation URIs (never document bytes). The App streams the live CMS LCD or claims-manual pages beside that answer.

Implements the current [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) extension (`io.modelcontextprotocol/ui`).

## What a reviewer should see

| Check | Where |
|------|--------|
| Tool bound to a UI | `tools/list` → `review_claim_requirements._meta.ui.resourceUri` = `ui://claims-desk/app.html` |
| UI resource | `resources/read` of that URI, MIME `text/html;profile=mcp-app` |
| Capability | `initialize` → `capabilities.extensions["io.modelcontextprotocol/ui"]` |
| App-only tools | `read_document_bytes` and `preview_pdf_pages` have `_meta.ui.visibility: ["app"]` |
| Split | Tool JSON has citation URIs only; the App fetches bytes via app-only tools |

## Run (local Apps host)

Python **3.10+** (3.12 recommended). Needs network for live `cms.gov` fetches. PDF page preview uses `pdftoppm` (poppler).

```bash
python3.12 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
python scripts/serve_app.py
```

Open http://127.0.0.1:8765

1. Leave **Medicare / 27447**, click **Ask MCP tool**.
2. Confirm First Coast **Jurisdiction N** + **12-month / 1 calendar year** filing on the left, LCD L33618 on the right.
3. Try **70553** (claims-manual PDF), **E0601** (no DMEPOS PA; CMNs discontinued), and UHC commercial outpatient MRI (UHC PA list, not a Medicare manual).

The local host `resources/read`s the `ui://` HTML, loads it in an iframe, and proxies `tools/call` over `postMessage`. The view never `POST`s `/mcp`.

### Stdio (Claude Desktop or any Apps-capable client)

```bash
python -m mcp_pdf_demo.server
```

Point the client at that command. Optional Streamable HTTP: `python -m mcp_pdf_demo.server --http` → `http://127.0.0.1:3001/mcp`.

Optional enrichment (not required to review the Apps wiring):

```bash
export RCI_API_KEY=...
export RCI_API_URL=https://api-dev.rcintell.com
```

## How to replicate the implementation

Always two parts: a **tool** that returns data, and a **`ui://` resource** the host renders.

1. **Python SDK Apps extension** — `Apps()` + `MCPServer(..., extensions=[apps])` so the server advertises `io.modelcontextprotocol/ui`.
2. **Bind the result tool** — `@apps.tool(resource_uri="ui://claims-desk/app.html", meta={"ui/resourceUri": "..."})` on `review_claim_requirements`.
3. **Serve the view** — `FunctionResource` / `add_html_resource` at that URI with MIME `text/html;profile=mcp-app`. Bundle CSS + JS into one HTML file (`app_html.py` + `app/view.js`).
4. **App-only helpers** — same `resource_uri`, `visibility=["app"]`, for chunked reads and PDF rasterization.
5. **View talks to the host, not the server** — `ui/initialize` then `tools/call` over `window.parent.postMessage` (`app/view.js`).
6. **Host is the MCP client** — fetch `ui://` HTML, iframe it, handle `ui/initialize`, proxy `tools/call` / `resources/read` (`app/host.js` + `scripts/serve_app.py`). Production hosts (Claude, VS Code, `ext-apps` basic-host) do this step for you.

Policy URLs live in `fixtures/catalog.json`. Fetch/cache is `src/mcp_pdf_demo/live.py`.

## Layout

| Path | Role |
|------|------|
| `src/mcp_pdf_demo/server.py` | MCP server: Apps tools, `ui://` resource, `doc://` policy docs |
| `src/mcp_pdf_demo/live.py` | Live CMS fetch + optional RCI |
| `src/mcp_pdf_demo/app_html.py` | Bundles the view into one HTML document |
| `app/view.js` | MCP App view (`postMessage`) |
| `app/host.js`, `app/index.html` | Local Apps host |
| `scripts/serve_app.py` | Runs that host on `:8765` |
| `fixtures/catalog.json` | CPT → CMS URL map |

## License

MIT