# govuk-frontend-mcp

[![npm version](https://img.shields.io/npm/v/govuk-frontend-mcp.svg)](https://www.npmjs.com/package/govuk-frontend-mcp)

An MCP server that exposes GOV.UK Frontend components and GOV.UK Design System patterns and styles as resources.

> **Note:** This is an unofficial, third-party tool and is not affiliated with or endorsed by GOV.UK or the UK Government.

## What's covered

Data is pulled from two independent sources, each with its own release cadence:

- **Components** come from the [`govuk-frontend`](https://www.npmjs.com/package/govuk-frontend) npm package.
- **Patterns and styles** come from the [`alphagov/govuk-design-system`](https://github.com/alphagov/govuk-design-system) GitHub repository, from the `v5` branch by default.

These are separate projects with separate versioning — do not expect a single version number to describe both.

## Available resources

- `govuk://components` — list all components
- `govuk://component/{name}` — get a specific component (macro signature, options, example)
- `govuk://patterns` — list all Design System patterns
- `govuk://pattern/{name}` — get a specific pattern
- `govuk://styles` — list all Design System styles
- `govuk://style/{name}` — get a specific style. `govuk://style/page-template` additionally includes the annotated GOV.UK Frontend Nunjucks page template.

## What's not covered

Sass design tokens, component JavaScript behaviours and GOV.UK Service Manual content are out of scope.

## Setup

```bash
npm install
npm run build
```

The build step fetches data from both sources and compiles TypeScript, so it must be run before starting the server.

## Building against a different version or branch

By default, `npm run build` uses the `govuk-frontend` version pinned in `package.json` and the `v5` branch of `govuk-design-system`. You can override either independently:

```bash
npm run build:data -- 6.1.0       # build components from govuk-frontend@6.0.0
npm run build:patterns -- main    # fetch patterns from the main branch
npm run build:styles -- main      # fetch styles from the main branch
```

`build:data` installs the requested version with `npm install --no-save --no-package-lock`, so your `package.json` is not modified.

Heads-up: the `--` separator before the argument is required. Without it, npm swallows the value and the script never sees it.

## MCP client configuration

Add the server to your MCP client's config file (for Claude Desktop this is `claude_desktop_config.json`; other clients use the same shape):

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

Replace the path with the absolute path to `dist/index.js` in your checkout. Restart your client after saving.

## Other commands

```bash
npm run dev         # run the server with tsx, no build step
npm run start       # run the compiled server from dist/
npm run typecheck   # type-check src/ and scripts/ without emitting
```

## Licence

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with 💻 by Gabriel Guimaraes