crime-frontend-developer-mcp

# `@hmcts/crime-frontend-developer-mcp` > An MCP server that connects Claude Code to live HMCTS Crime Platform > Design Kit source. Eighteen tools, AST-driven extraction, OAuth-per-developer > authentication, automatic knowledge updates, structured Gate 1 intake. > Built on `@hmcts/crime-mcp-register`. [](#status) [](#) ## Status `v0.1.0-beta.0`. Pre-1.0 -- minor versions may introduce breaking changes until the API stabilises around at least one external consumer. ## What this is `@hmcts/crime-frontend-developer-mcp` is an MCP server that gives Claude Code live, structured access to the HMCTS Crime Platform Design Kit (`hmcts/cpp-ui-pdk2`). It surfaces every PDK component, validator, type, input, output, template and example as MCP tools. It also seeds the developer's machine with rule files, agents, slash commands, and a SessionStart hook on first connection, and refreshes that knowledge whenever PDK source changes upstream. The plugin solves a specific problem: Claude's training data drifts out of date with the live PDK. Without this plugin, Claude generates PDK code that compiles against a-PDK-that-existed-when-the-model-was-trained but not against the current PDK. With this plugin, Claude queries the live source every turn -- the trust gap closes. ## Read these next - **[PROJECT-OVERVIEW.md](./PROJECT-OVERVIEW.md)** -- the *why*. What problem this solves, the OAuth security position, the AST extraction pipeline as a defining technical claim, the iteration roadmap. - **[ARCHITECTURE.md](./ARCHITECTURE.md)** -- the *how*. Every tool, every file, every flow. The `setup_workspace` and `update_knowledge` lifecycles. The SessionStart hook. The dev-mode-vs-prod-mode split. - **[RUN-LOCALLY.md](./RUN-LOCALLY.md)** -- step-by-step setup. Get the plugin running on your machine in dev mode, connected to your Claude Code, with a working knowledge base. - **[EXERCISE-WITNESS-REGISTER.md](./EXERCISE-WITNESS-REGISTER.md)** -- the canonical demo prompt. A self-contained feature spec the plugin has been validated against. Run it to see the plugin produce real working code end-to-end. ## Install The plugin ships pre-bundled with the register tarball it depends on -- you don't need to build the register yourself for normal use. Future iterations will publish the register to npm under the `@hmcts` scope, at which point this dependency becomes a regular npm install. ```bash git clone https://github.com/hmcts/crime-frontend-developer-mcp.git cd crime-frontend-developer-mcp npm install && npm run build npm run generate:pdk ``` If you would rather build the register from source -- to inspect or contribute to it -- clone it as a sibling directory and either `npm pack` it for the local install, or point the plugin at its `dist/` folder by adjusting the `crime-mcp-register` dependency in `package.json`. See [RUN-LOCALLY.md](./RUN-LOCALLY.md) for details. Then start the dev server: ```bash CRIME_MCP_MODE=dev npm run dev # server listens on http://127.0.0.1:3000/sse ``` Register the server with Claude Code: ```bash claude mcp add crime-frontend-developer-mcp \ --scope user \ --transport sse \ http://localhost:3000/sse ``` `--scope user` registers the server in your user-level Claude Code configuration, so it's available across every project you open. Without `--scope user`, the registration is project-local and won't follow you into other projects. The exact CLI flag form may differ slightly by Claude Code version; if `claude mcp add` rejects the flags, run `claude mcp add --help` for your version's syntax. Restart Claude Code and start a session inside a CP Angular project. For full step-by-step instructions, see [RUN-LOCALLY.md](./RUN-LOCALLY.md). ## Production deployment Hosted production deployments enable OAuth and enforce per-developer authentication. A **GitHub OAuth App** must be registered first -- typically a single OAuth App per HMCTS Crime deployment, registered once under the HMCTS organisation. Custom-environment deployments (e.g. preview, staging) may register their own. Each OAuth App provides a client ID and a client secret. Three environment variables on the server use those values: ```bash GITHUB_OAUTH_CLIENT_ID=<from the GitHub OAuth App> GITHUB_OAUTH_CLIENT_SECRET=<from the GitHub OAuth App> OAUTH_BASE_URL=https://your-public-mcp-url.example.com CRIME_MCP_MODE=prod PORT=8080 ``` The OAuth App's authorisation callback URL must be set to `<OAUTH_BASE_URL>/callback` in its GitHub settings. The proxy handles the rest -- developers authenticate through their browser on first connection; from then on, every GitHub call inside a tool handler runs as the developer's GitHub identity. For the security model in detail (per-developer audit, automatic revocation, no shared service-account credential, no PATs), see [PROJECT-OVERVIEW.md section 4](./PROJECT-OVERVIEW.md#4-the-oauth-security-position) and [ARCHITECTURE.md section 11](./ARCHITECTURE.md#11-the-oauth-security-model). ## What the plugin provides **18 MCP tools** for live PDK queries and Gate 1 structured intake: - 5 component query tools (`pdk_list_components`, `pdk_get_component`, `pdk_get_components`, `pdk_get_template`, `pdk_get_exports`) - 1 type query (`pdk_get_types`) - 1 validator query (`pdk_get_validators`) - 2 search queries (`pdk_search`, `pdk_diff_components`) - 5 documentation/application queries (`docs_*`, `app_*`) - 1 composite query (`pdk_feature_context` -- bulk fetch in one round-trip) - 2 lifecycle tools (`setup_workspace`, `update_knowledge`) - 1 structured intake tool (`gate_intake`) -- captures Gate 1 specs via elicitation (interactive form on CLI Claude Code) with Markdown fallback for clients that don't render the form (e.g. VS Code at the time of writing) - 1 elicitation diagnostic (`_test_elicitation`) -- verifies your client environment renders elicitation correctly **~24 files** seeded onto each developer's machine on first connection: rule files for cp-angular, 7 task-specific agents (form-builder, layout, image-analyser, pdk-checker, etc.), 7 slash commands, the SessionStart hook scripts, and an install marker. **Per-developer GitHub auth** in production via OAuth 2.1 + PKCE proxy. No shared service-account tokens. **Automatic knowledge updates** when PDK source moves upstream. A SessionStart hook detects the hash mismatch; on the next session start, Claude tells the developer "an update is available" and asks whether to apply. ## Limitations to know about The current `0.1.0-beta` release covers exactly: - One framework: Angular (cp-angular) - One UI library: PDK - One project shape: Angular projects with `package.json` at the workspace root, where `setup_workspace` can detect ngrx flags Setup must be run inside such a project. A developer connecting to the plugin from outside one will not be able to complete first-time setup correctly. v0.2 splits setup into a universal phase (always ships) and a project-conditional phase (ships when the developer opens a session inside a matching project), removing this constraint. For the full limitation list and roadmap, see [PROJECT-OVERVIEW.md section 12](./PROJECT-OVERVIEW.md#12-honest-limitations) and [section 10](./PROJECT-OVERVIEW.md#10-iteration-roadmap). ## Repository [`hmcts/crime-frontend-developer-mcp`](https://github.com/hmcts/crime-frontend-developer-mcp). Issues and contributions welcome. ## Licence To be confirmed. The initial public push is unlicensed pending HMCTS legal review of the appropriate licence for new public Crime repositories.