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)

Related MCP server: Insider Design System MCP

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):

{
  "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:

{
  "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

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):

npm run dev

Or start the built server directly:

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.