# Prototype Kit MCP Server

[![Python 3.12+](https://img.shields.io/badge/python-3.12,3.13-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

An MCP server that creates and manages [GOV.UK Prototype Kit](https://github.com/alphagov/govuk-prototype-kit) projects. Agents can scaffold kits, plan and generate multi-page journeys as Nunjucks macros, manage version folders, and run `npm run dev` — following the embedded AI guidelines in `ai-context.md` (GOV.UK Design System conventions, content design, and accessibility).

## Getting started

### Prerequisites

- Python 3.12+
- [Node.js LTS](https://nodejs.org/) (required for `npx govuk-prototype-kit create` and `npm run dev`)
- [uv](https://github.com/astral-sh/uv) recommended

### 1. Install the server

```bash
git clone <your-repo-url> prototypekit-mcp
cd prototypekit-mcp
make install                 # creates .venv, installs deps + pre-commit hooks
cp .env.example .env
```

Optional: edit `.env` and set where prototypes should be created:

```bash
PROTOTYPE_ROOT=~/Documents/prototypes
PROTOTYPE_DEFAULT_PORT=3000
ENABLE_AUTH=False
```

### 2. Run the MCP server

```bash
make local                   # http://localhost:5001
```

Check it is up:

```bash
curl http://localhost:5001/health
```

<details>
<summary>Manual run (without Make)</summary>

```bash
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env
prototypekit-mcp
```

</details>

### 3. Connect Cursor

Add this to your Cursor MCP settings (replace paths with your machine):

```json
{
  "mcpServers": {
    "prototypekit": {
      "command": "/Users/YOU/Documents/prototypekit-mcp/.venv/bin/prototypekit-mcp",
      "env": {
        "ENABLE_AUTH": "False",
        "COMPATIBLE_WITH_CURSOR": "True",
        "PROTOTYPE_ROOT": "/Users/YOU/Documents/prototypes",
        "MCP_HOST": "localhost",
        "MCP_PORT": "5001"
      }
    }
  }
}
```

If the server is already running via `make local`, you can point Cursor at the HTTP endpoint instead: `http://localhost:5001/mcp`.

Restart Cursor (or reload MCP servers) and confirm the `prototypekit` tools appear.

### 4. Create your first prototype

In Cursor chat, ask the agent to use the tools, for example:

> Using the prototypekit MCP tools: create a prototype named `juggling-licence` for “Apply for a juggling licence”, plan a journey that asks how many balls you can juggle, generate it as v1, then start it.

The agent should roughly:

1. `get_ai_guidelines` — load GOV.UK / ai-context rules  
2. `create_prototype` — scaffold the kit under `PROTOTYPE_ROOT`  
3. `plan_journey` → `generate_journey` — write `app/views/v1/` pages and routes  
4. `start_prototype` — open `http://localhost:3000`

Then open the returned URL in a browser. Later iterations: `create_version`, `create_page`, `add_route`.

For a step-by-step page example, see the [tutorial](docs/tutorial.md).

## MCP tools

| Tool | Purpose |
| ---- | ------- |
| `get_ai_guidelines` | Return ai-context conventions (full or by section) |
| `create_prototype` | Scaffold a new Prototype Kit project |
| `list_prototypes` | List projects under `PROTOTYPE_ROOT` |
| `plan_journey` | Draft structured journey JSON from a description |
| `generate_journey` | Write versioned Nunjucks pages and Express routes |
| `create_page` | Add one page (start / question / check-answers / …) |
| `add_route` | Append simple or branching POST routes |
| `create_version` | Copy `vN` → `vN+1` (never deletes old versions) |
| `list_pages` | Inventory views and routes |
| `start_prototype` | Run `npm run dev` |
| `stop_prototype` | Stop a tracked process |
| `prototype_status` | Running status / ports |

Generators emit only Nunjucks macros and `govuk-*` classes. Unsupported custom UI returns an explicit gap error (ai-context rule 5).

## Configuration

| Variable | Default | Description |
| -------- | ------- | ----------- |
| `MCP_HOST` | `localhost` | Server bind address |
| `MCP_PORT` | `5001` | Server port |
| `MCP_TRANSPORT_PROTOCOL` | `http` | `http`, `sse`, or `streamable-http` |
| `ENABLE_AUTH` | `False` in `.env.example` | OAuth (off for local prototyping) |
| `PROTOTYPE_ROOT` | `~/Documents/prototypes` | Where kits are created |
| `PROTOTYPE_KIT_VERSION` | `latest` | npm dist-tag / version for the kit |
| `PROTOTYPE_DEFAULT_PORT` | `3000` | Default `npm run dev` port |
| `PYTHON_LOG_LEVEL` | `INFO` | Logging level |

## AI guidelines

The server ships [`prototypekit_mcp/src/assets/ai-context.md`](prototypekit_mcp/src/assets/ai-context.md) based on HM Land Registry / MoJ GOV.UK Prototype Kit AI context. Every new prototype receives a copy at `{prototype}/ai-context.md`.

Core rules enforced by generators:

1. Pages extend `layouts/main.html`
2. Use Nunjucks macros (`govukButton`, `govukInput`, …)
3. Only GOV.UK classes — no custom CSS
4. Accessibility via Design System components
5. Flag gaps when something is not possible with existing components

## Documentation

| Guide | Description |
| ----- | ----------- |
| [Architecture](docs/architecture.md) | System diagrams and tool layout |
| [Development](docs/development.md) | Setup, testing, code quality |
| [Deployment](docs/deployment.md) | Container / OpenShift |
| [Authentication](docs/authentication.md) | Optional OAuth |
| [Tutorial](docs/tutorial.md) | Add a page via `create_page` |
| [Examples](examples/) | FastMCP and LangGraph clients |

## License

[Apache 2.0](LICENSE)