# Angular Storybook MCP Server

An MCP (Model Context Protocol) server that brings an **Angular design system built on Storybook** into Claude Code and Cursor, enabling AI-assisted development with real-time access to component metadata, APIs, and documentation.

This server only works against a design system whose Storybook build emits the `manifests/components.json` and `manifests/docs.json` files described below — it is not a generic Angular DS integration.

## Overview

This MCP server exposes an Angular Storybook design system as a set of tools available to Claude. It fetches component metadata from a live Storybook instance and provides tools for:

- **Listing all components** — get a complete inventory of the design system
- **Searching components** — find components by name or keyword
- **Component imports** — get correct import paths for any component
- **Component props** — view all props, types, and defaults for a component
- **Type details** — inspect complex TypeScript types used by components
- **Foundations** — access design tokens (colors, typography, spacing, etc.)
- **Peer dependencies** — pointer to where required package versions can be found (not yet in the manifests)

## Before you start: two things are required

This project has two independent halves, and **both must be set up** — one without the other doesn't work:

1. **Install and configure this MCP server locally** — see [Setup](#setup) below. This is the client-side piece that Claude Code or Cursor talks to.
2. **Make your Storybook emit `manifests/components.json` and `manifests/docs.json`** — see [Bringing up a new design system repo](#bringing-up-a-new-design-system-repo-for-storybook-owners). This is a one-time change to the *Storybook project itself* (Compodoc + the manifest addon), and it must re-run on every Storybook rebuild so the manifests stay current. Without it, there's nothing for this MCP server to fetch, no matter how correctly step 1 is configured.

## Setup

Both Claude Code and Cursor talk to this MCP server using the same `mcpServers` config shape — only the config file location differs. Pick your editor below.

### Setup for Cursor

Once the Storybook owner deploys with the `manifests/components.json` and `manifests/docs.json` files included, configure Cursor to use the live URL.

**Edit `.cursor/mcp.json`** (project-level, in your repo root) **or `~/.cursor/mcp.json`** (global, applies to all projects):

```json
{
  "mcpServers": {
    "angular-ds": {
      "command": "node",
      "args": ["<path-to-angular-ds-mcp-server>/dist/server.js"],
      "env": {
        "STORYBOOK_URL": "https://your-storybook-host.example.com"
      }
    }
  }
}
```

Then reload Cursor (Command Palette → "Reload Window", or fully restart Cursor). Open **Cursor Settings → MCP** to confirm the `angular-ds` server shows as connected.

### Setup for Claude Code

Once the Storybook owner deploys with the `manifests/components.json` and `manifests/docs.json` files included, configure Claude Code to use the live URL.

**Edit `~/.claude/claude.json`:**

```json
{
  "mcpServers": {
    "angular-ds": {
      "command": "node",
      "args": ["<path-to-angular-ds-mcp-server>/dist/server.js"],
      "env": {
        "STORYBOOK_URL": "https://your-storybook-host.example.com"
      }
    }
  }
}
```

Then restart Claude Code. The tools will be available in all sessions.



## Testing

After configuring Claude Code or Cursor, start a new chat and ask:

```
List all components in the design system
```

The assistant should call `list_components` and return the full component list. If it works, the MCP server is properly configured.

## Building

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

The built server will be at `dist/server.js`.

## Development

Run the server in dev mode (with hot reload via `tsx`):

```bash
npm run dev
```

Or start the built server directly:

```bash
npm start
```

## Architecture

- **`src/server.ts`** — Main MCP server entry point; registers all tools
- **`src/fetcher.ts`** — Handles fetching and caching `manifests/components.json` and `manifests/docs.json` from Storybook
- **`src/tools/`** — Individual tool implementations:
  - `list-components.ts` — List all components
  - `search-components.ts` — Search by name/keyword
  - `get-import.ts` — Get import path
  - `get-component-props.ts` — Get component props
  - `get-type-details.ts` — Inspect TypeScript types
  - `get-foundations.ts` — Get design tokens
  - `get-peer-dependencies.ts` — Get version requirements

## Environment Variables

- **`STORYBOOK_URL`** — Base URL where the manifest files are served. Required; the server throws on startup if it is not set.

## Troubleshooting

**"Failed to fetch component metadata"**
- Check that `STORYBOOK_URL` points to a valid URL
- Verify `manifests/components.json` and `manifests/docs.json` exist at `{STORYBOOK_URL}/manifests/components.json` and `{STORYBOOK_URL}/manifests/docs.json`
- For local testing, ensure the http-server is running on the correct port

**Tools not appearing in Claude Code / Cursor**
- Verify `~/.claude/claude.json` (Claude Code) or `.cursor/mcp.json` / `~/.cursor/mcp.json` (Cursor) is properly formatted JSON
- Check that the `dist/server.js` file exists and is executable
- Restart Claude Code, or reload/restart Cursor, after updating the config

**Slow first query**
- The server caches metadata on startup. First query may take a few seconds while it fetches from Storybook.

## Integration with your Design System

This server depends on your Angular Design System's Storybook build including two manifest files, `manifests/components.json` and `manifests/docs.json`. These are automatically generated as part of the Storybook build process and contain:

- **`manifests/components.json`** — component names, selectors, import statements, story snippets, and prop definitions (types, required flags, defaults, descriptions)
- **`manifests/docs.json`** — design tokens and other foundations documentation

Peer dependency information is not currently part of the manifests; the `get_peer_dependencies` tool points users to your design system package's own `peerDependencies` instead.

### Bringing up a new design system repo (for Storybook owners)

None of this happens with a vanilla Storybook install — it requires two things wired into the target Angular repo:

**1. Generate Angular metadata with Compodoc**

Compodoc is a separate tool, not part of Storybook. Install it and add a script that runs it before Storybook starts/builds:

```json
// package.json
"scripts": {
  "compodoc:lib": "compodoc -p <path-to-your-lib-tsconfig> -e json -d <output-dir> --silent",
  "prestorybook": "npm run compodoc:lib",
  "prebuild-storybook": "npm run compodoc:lib"
}
```

This produces a `documentation.json` file describing every component's inputs, outputs, and types.

**2. Add the manifest addon + feature flag to `.storybook/main.ts`**

```ts
addons: [
  'storybook-addon-angular-manifest', // must come BEFORE addon-docs
  '@storybook/addon-docs',
  // ...your other addons
  '@storybook/addon-mcp',
],
features: {
  componentsManifest: true, // Storybook 10.3+; use `experimentalComponentsManifest` on 10.2.x
},
```

Every story's `meta` must set `component:` (e.g. `component: ButtonComponent`) — without it, the addon can't resolve the Angular component name and the manifest entry comes out as an error.

**3. Build and deploy Storybook as usual**

`npm run build-storybook` now emits `manifests/components.json` and `manifests/docs.json` as static files alongside the rest of the Storybook site. Deploy that output wherever your Storybook is normally hosted (S3+CloudFront, a container behind nginx, etc.) — no special MCP-aware hosting is required, it's just two extra static JSON files.

**4. Point this MCP server at it**

Once the manifests are reachable at `{your-storybook-url}/manifests/components.json` and `{your-storybook-url}/manifests/docs.json`, set `STORYBOOK_URL` to that base URL (see [Setup](#setup) and [Environment Variables](#environment-variables) above) — no changes to this server's code are needed.

Consumers on your team then just add this server to their own `.cursor/mcp.json` or `~/.claude/claude.json` as shown in [Setup](#setup), pointing `STORYBOOK_URL` at your deployed Storybook. Each person still builds/runs their own local copy of this server (it's a stdio server, not a hosted one) — only the Storybook + manifests need central deployment.