# GOV.UK Design System MCP

TypeScript MCP server that serves locally-crawled GOV.UK Design System guidance from SQLite FTS5.

## Features

- Manual crawler restricted to approved GOV.UK Design System sections.
- SQLite-backed storage at `data/govuk-design-system.db`.
- FTS5 search with deterministic ranking and snippets.
- MCP tools:
  - `search(query: string)`
  - `fetch(id: string)`
  - `version()`
- STDIO transport adapter isolated from core logic.

## Setup

```bash
bun install
cp .env.example .env
```

## Build the Local Dataset

```bash
bun run crawl
```

## Run MCP Server

```bash
bun run start
```

## Add This MCP to Developer Tools

The server uses **STDIO transport**, so most MCP-compatible tools can run it with a command.

Use this command in your MCP client configuration:

```bash
bun run /absolute/path/to/govuk-frontend-mcp/src/index.ts
```

If your client supports separate `command` and `args`, use:

- command: `bun`
- args: `["run", "/absolute/path/to/govuk-frontend-mcp/src/index.ts"]`
- cwd: `/absolute/path/to/govuk-frontend-mcp`

### Example: Claude Code (MCP config)

```json
{
  "mcpServers": {
    "govuk-design-system": {
      "command": "bun",
      "args": [
        "run",
        "/absolute/path/to/govuk-frontend-mcp/src/index.ts"
      ],
      "cwd": "/absolute/path/to/govuk-frontend-mcp"
    }
  }
}
```

### Example: Cursor / VS Code style MCP config

```json
∏
  "mcpServers": {
    "govuk-design-system": {
      "type": "stdio",
      "command": "bun",
      "args": [
        "run",
        "/absolute/path/to/govuk-frontend-mcp/src/index.ts"
      ],
      "cwd": "/absolute/path/to/govuk-frontend-mcp"
    }
  }
}
```

### Example: Docker command for clients that run shell commands

```bash
docker compose run --rm govuk-design-system-mcp bun run src/index.ts
```

After connecting, the MCP should expose:

- `search(query: string)`
- `fetch(id: string)`
- `version()`

Tip: run `bun run crawl` whenever you want to refresh the local GOV.UK data before using the MCP in your tool.

## Docker Compose

```bash
docker compose up --build
```

## Test

```bash
bun test
bun run typecheck
```