mmcgrotty/govuk-prototype-mcp

GOV.UK Prototype Kit MCP Server

An MCP (Model Context Protocol) server that helps you create and manage GOV.UK Prototype Kit projects. The Prototype Kit runs in Node.js, is built on Express, and uses GOV.UK Frontend.

Features

• Create Prototypes: Initialize new GOV.UK Prototype Kit projects
• Manage Prototypes: List, start, and stop prototype servers
• Add Pages: Quickly add new pages with GOV.UK templates
• Component Library: Access all GOV.UK Frontend components with examples
• Documentation: Get help with routing, sessions, layouts, and deployment
• Node Version Check: Verify you have Node.js 22.x.x LTS installed

Requirements

• Node.js v22.x.x LTS (required by GOV.UK Prototype Kit)
• npm (comes with Node.js)
• Internet connection (to download prototype kit on first create)

Installation

npm install
npm run build

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "govuk-prototype-kit": {
      "command": "node",
      "args": ["/path/to/govuk-prototype-kit-mcp-server/build/index.js"]
    }
  }
}

With VS Code AI Agents (Cline, Continue, Roo Coder)

Cline: Edit cline_mcp_settings.json Continue: Edit ~/.continue/config.json

{
  "mcpServers": {
    "govuk-prototype-kit": {
      "command": "node",
      "args": ["/absolute/path/to/govuk-prototype-kit-mcp-server/build/index.js"]
    }
  }
}

Available Tools

check_node_version

Verifies you have Node.js v22.x.x LTS installed.

Example: "Check if my Node version is compatible"

create_prototype

Creates a new GOV.UK Prototype Kit project.

Parameters:

• name (string): Name of the prototype
• directory (string): Parent directory where prototype will be created

Example: "Create a new GOV.UK prototype called 'apply-for-passport' in ~/projects"

list_prototypes

Lists all GOV.UK Prototype Kit projects in a directory.

Parameters:

• directory (string): Directory to search

Example: "List all my prototypes in ~/projects"

start_prototype

Starts a prototype (runs npm run dev).

Parameters:

• path (string): Full path to the prototype directory

Example: "Start the prototype at ~/projects/apply-for-passport"

stop_prototype

Stops a running prototype server.

Parameters:

• path (string): Full path to the prototype directory

Example: "Stop the prototype at ~/projects/apply-for-passport"

get_prototype_structure

Shows the file structure of a prototype project.

Parameters:

• path (string): Full path to the prototype directory

Example: "Show me the structure of my passport prototype"

add_page

Creates a new page in your prototype with GOV.UK template.

Parameters:

• prototypePath (string): Path to the prototype directory
• pageName (string): Name of the page (e.g., 'start', 'check-answers')
• route (string): Route path (e.g., '/start', '/check-your-answers')

Example: "Add a 'personal-details' page to my prototype at /personal-details"

list_components

Lists all available GOV.UK Frontend components.

Example: "What components are available?"

get_component_example

Gets Nunjucks code example for a specific component.

Parameters:

• component (string): Component name (e.g., 'button', 'text-input', 'radios')

Example: "Show me an example of the radios component"

get_prototype_kit_docs

Provides documentation on specific topics.

Parameters:

• topic (string): Topic name ('routing', 'sessions', 'layouts', 'deployment')

Example: "How do I use routing in the prototype kit?"

Quick Start Guide

1. Check Your Node Version

Ask: "Check if my Node version is compatible with GOV.UK Prototype Kit"

2. Create a New Prototype

Ask: "Create a GOV.UK prototype called 'benefits-calculator' in ~/projects"

3. Start Your Prototype

Ask: "Start the prototype at ~/projects/benefits-calculator"

Then open http://localhost:3000 in your browser.

4. Add Pages

Ask: "Add a start page to my benefits-calculator prototype at /start"

5. Use Components

Ask: "Show me examples of radio buttons"
Ask: "Show me how to use a date input"

Common Workflows

Building a Form Journey

1. Create the prototype

   "Create a new prototype called 'licence-application' in ~/projects"
   

2. Add pages in sequence

   "Add a 'start' page at /start"
   "Add a 'personal-details' page at /personal-details"
   "Add a 'check-answers' page at /check-your-answers"
   "Add a 'confirmation' page at /confirmation"
   

3. Get component examples

   "Show me the text-input component"
   "Show me the radios component"
   "Show me the summary-list component"
   

4. Learn about routing

   "How do I use routing in the prototype kit?"
   "How do sessions work?"
   

Managing Multiple Prototypes

1. List all prototypes

   "List all prototypes in ~/projects"
   

2. Start specific prototype

   "Start the licence-application prototype"
   

3. View structure

   "Show me the structure of the licence-application prototype"
   

4. Stop when done

   "Stop the licence-application prototype"
   

Project Structure

When you create a prototype, you'll get:

your-prototype/
├── app/
│   ├── views/          # Your HTML/Nunjucks templates
│   │   └── index.html  # Start page
│   ├── routes.js       # Custom routes and logic
│   ├── assets/         # CSS, JavaScript, images
│   │   ├── sass/
│   │   └── javascripts/
│   └── data/           # Session data store
├── docs/               # Documentation
├── public/             # Static files
└── package.json

Key Directories

• app/views/ - Put your page templates here (.html files)
• app/routes.js - Add custom routing logic and branching
• app/assets/sass/ - Custom styles (if needed)
• app/data/ - Session data storage

Components Reference

All GOV.UK Frontend components are available:

• Accordion
• Back link
• Breadcrumbs
• Button
• Character count
• Checkboxes
• Cookie banner
• Date input
• Details
• Error message
• Error summary
• Fieldset
• File upload
• Inset text
• Notification banner
• Pagination
• Panel
• Phase banner
• Radios
• Select
• Summary list
• Table
• Tabs
• Tag
• Text input
• Textarea
• Warning text

Use get_component_example to see code examples for any component.

Troubleshooting

"Node version not compatible"

Install Node.js v22.x.x LTS from https://nodejs.org

"Port 3000 already in use"

Stop other prototypes or services using port 3000.

"Cannot find module"

Run npm install in your prototype directory.

"Permission denied"

Ensure you have write permissions to the directory where you're creating prototypes.

Development Tips

1. Use session data - Form data is automatically stored in req.session.data
2. Add routing logic - Edit app/routes.js for branching journeys
3. Extend layouts - All pages extend layouts/main.html
4. Password protect - Set USERNAME and PASSWORD environment variables
5. Don't use for production - Prototypes are for testing ideas only

Example Conversation

You: "Check my Node version"
AI: ✓ Node.js v22.11.0 is compatible with GOV.UK Prototype Kit

You: "Create a prototype called 'pet-passport' in ~/projects"
AI: ✓ GOV.UK Prototype Kit created successfully! Location: ~/projects/pet-passport

You: "Start the pet-passport prototype"
AI: ✓ Starting GOV.UK Prototype Kit. Available at: http://localhost:3000

You: "Add a start page at /start"
AI: ✓ Created page: ~/projects/pet-passport/app/views/start.html

You: "Show me a button example"
AI: {{ govukButton({ text: "Save and continue" }) }}

You: "How do I add routing?"
AI: [Shows routing documentation with examples]

Resources

• GOV.UK Prototype Kit Documentation
• GOV.UK Design System
• GOV.UK Frontend

License

MIT

Related Links

• GOV.UK Prototype Kit
• GOV.UK Design System
• Model Context Protocol