Prototype Kit MCP Server

An MCP server that creates and manages GOV.UK 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 (required for npx govuk-prototype-kit create and npm run dev)
• uv recommended

1. Install the server

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:

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

2. Run the MCP server

make local                   # http://localhost:5001

Check it is up:

curl http://localhost:5001/health

Manual run (without Make)

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

3. Connect Cursor

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

{
  "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.

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 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	System diagrams and tool layout
Development	Setup, testing, code quality
Deployment	Container / OpenShift
Authentication	Optional OAuth
Tutorial	Add a page via create_page
Examples	FastMCP and LangGraph clients

License

Apache 2.0