# Angular DS MCP Server

An MCP (Model Context Protocol) server that brings the Phenom Angular Design System into Claude Code and Cursor, enabling AI-assisted development with real-time access to component metadata, APIs, and documentation.

## Overview

This MCP server exposes the Phenom 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)

## 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://ds-storybook-intqa.phenompro.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://ds-storybook-intqa.phenompro.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 Phenom DS
```

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. Defaults to `https://ds-storybook-intqa.phenompro.com` if 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 Phenom DS

This server depends on the Phenom 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 the `@phenom/angular-ds` package's own `peerDependencies` instead.

For Storybook owners: ensure your build outputs `manifests/components.json` and `manifests/docs.json` to the Storybook static directory so they're accessible at `{STORYBOOK_URL}/manifests/components.json` and `{STORYBOOK_URL}/manifests/docs.json`.