# Northstar Clinic MCP Apps demo

This branch extends the existing appointment application with text-first MCP
tools and an interactive MCP App that compatible hosts such as Claude Desktop
can render inside the conversation.

The teaching demo uses an in-memory `AppointmentStore` so it can be reset
instantly. In a production application, this module would be replaced by a
database-backed repository without changing the browser-to-API contract.

## Run it

Start the clinic API and keep it running:

```bash
uv sync
uv run uvicorn clinic_api:app --host 127.0.0.1 --port 8765
uv run uvicorn clinic_api:app --host 127.0.0.1 --port 8765
```

The browser version is at [http://127.0.0.1:8765](http://127.0.0.1:8765). API docs are at
[http://127.0.0.1:8765/docs](http://127.0.0.1:8765/docs).

## Architecture

- `clinic_browser.html` is the browser UI.
- `clinic_api.py` exposes appointment and booking HTTP endpoints.
- `clinic_store.py` owns availability and atomic booking state.
- `clinic_mcp.py` adapts those HTTP capabilities into MCP tools and exposes the
widget resource.
- `clinic_widget.html` is the interactive UI rendered by the MCP host. It calls
MCP tools through the MCP Apps SDK; it does not bypass the MCP server to call
FastAPI directly.

Claude Desktop starts `clinic_mcp.py` as a local stdio MCP server. After changing
the MCP server or widget, fully quit and reopen Claude Desktop so it reconnects
and reloads the resource.

## Configure the MCP server from Claude Desktop

1. Open the Claude Desktop app.
2. Press **Command + ,** to open **Settings**.
3. In the settings sidebar, find **Desktop app** and select **Developer**.
4. Under **Local MCP servers**, click **Edit Config**. Claude opens its
   `claude_desktop_config.json` file in the default editor.
5. Add the `northstar-clinic` entry under `mcpServers`:

```json
{
  "mcpServers": {
    "northstar-clinic": {
      "command": "/Users/yashpatil/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/yashpatil/Developer/AI/mcp_apps",
        "python",
        "clinic_mcp.py"
      ],
      "env": {
        "CLINIC_API_URL": "http://127.0.0.1:8765"
      }
    }
  }
}
```

If the file already contains other MCP servers, add `northstar-clinic` inside
the existing `mcpServers` object instead of replacing the entire file.

Save the file, fully quit Claude Desktop with **Command + Q**, and reopen it.
Return to **Settings → Desktop app → Developer** and confirm that
`northstar-clinic` appears under **Local MCP servers** with a running status.

The FastAPI backend must be running separately before using the MCP tools:

```bash
uv run uvicorn clinic_api:app --host 127.0.0.1 --port 8765
```

## Rehearsed demo

1. Ask: `Use Northstar Clinic to find all available appointments and show the interactive dashboard.`
2. Filter to Dermatology in the rendered widget.
3. Click **Book visit** and review the appointment.
4. Enter the required contact number and reason, then click **Confirm appointment**.
5. Show that the appointment disappears from availability and that the receipt
  contains its reference.
6. Verify the same change with `GET /api/appointments` or the browser frontend.



## Branch-based lesson

```bash
git switch main           # existing FastAPI + browser application
git switch codex/mcp-app  # MCP server + Claude-rendered widget
git diff main..codex/mcp-app
```



## Quick checks

```bash
curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/api/appointments
```

The API is intentionally in-memory. Restarting it restores the six seeded slots.