# nhs-frontend-mcp

An [MCP](https://modelcontextprotocol.io) server for the [NHS.UK frontend](https://github.com/nhsuk/nhsuk-frontend) design system. Plug it into Claude, Cursor, or any MCP-compatible client and your AI assistant can look up real component templates, SCSS, macro options, and usage examples directly from the source — no hallucinated class names.

## Tools

| Tool | What it does |
|------|-------------|
| `list_nhs_components` | Lists all 43 components |
| `get_nhs_component` | Full component details: template, styles, API, examples, and JS |
| `get_nhs_component_html` | Nunjucks template only |
| `get_nhs_component_styles` | SCSS only |
| `get_nhs_component_api` | Macro options reference with types, required flags, and descriptions |
| `get_nhs_component_examples` | Fixture examples for all variants |
| `get_nhs_base_template` | The base HTML page template |
| `search_nhs_components` | Keyword search across component names and descriptions |
| `sync_nhs_frontend` | Manual git pull + cache clear |

## Resources

Every component is also exposed as an MCP resource at `nhs://component/{name}`.

## Auto-sync

On startup the server runs `git pull` on the nhsuk-frontend repo, then repeats every 6 hours (configurable). No manual pulls needed.

## Setup

### 1. Clone nhsuk-frontend

```sh
git clone https://github.com/nhsuk/nhsuk-frontend.git
```

### 2. Clone this repo next to it

```sh
git clone https://github.com/EmmaExcel/nhs-frontend-mcp.git
cd nhs-frontend-mcp
npm install
npm run build
```

### 3. Add to your MCP client

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "nhs-frontend": {
      "command": "node",
      "args": ["/path/to/nhs-frontend-mcp/dist/index.js"],
      "env": {
        "NHS_FRONTEND_PATH": "/path/to/nhs-frontend"
      }
    }
  }
}
```

**Or via npx (no clone needed):**

```json
{
  "mcpServers": {
    "nhs-frontend": {
      "command": "npx",
      "args": ["nhs-frontend-mcp"],
      "env": {
        "NHS_FRONTEND_PATH": "/path/to/nhs-frontend"
      }
    }
  }
}
```

## Environment variables

| Variable | Description | Default |
|----------|-------------|---------|
| `NHS_FRONTEND_PATH` | Path to your nhsuk-frontend clone | `../nhs-frontend` |
| `NHS_SYNC_INTERVAL_HOURS` | How often to pull updates. Set to `0` to disable. | `6` |

## Development

```sh
npm run build   # compile
npm start       # run
node test.mjs   # run tests (65 assertions)
```

## Project structure

```
src/
  index.ts        # server entry, tool handlers, resource handlers
  components.ts   # component discovery, file reading, macro option parsing
  format.ts       # markdown output formatting
  sync.ts         # git pull on startup + interval
  types.ts        # shared interfaces
```

## Licence

MIT