Skip to main content
Glama
yoniler82

Angular DS MCP Server

by yoniler82
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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.

Available Tools

7 tools
get_component_propsB

Get the full props interface for a component

ParametersJSON Schema
NameRequiredDescriptionDefault
componentNameYesComponent name, e.g. "PxButton" or "button"

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description only states the action without disclosing behavior such as error handling, casing conventions, or what 'full props interface' entails.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no unnecessary words. Front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no annotations. Description does not explain the return format or what 'props interface' includes, leaving ambiguity for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description of componentName. The tool description adds no additional meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Get the full props interface for a component'. Distinct from siblings like get_foundations, get_type_details, list_components, search_components, which cover other aspects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use. Implies usage for getting component props, but no guidance on alternatives among sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_foundationsB

Get foundation/token documentation categories (colors, typography, spacing, etc.)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the short description does not disclose behavioral traits such as authentication needs, rate limits, or whether it returns a list or object.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with key information, but slightly vague terminology ('documentation categories') reduces precision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and no annotations, the description is minimal; it conveys the tool's purpose but omits details on return format or structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so the baseline is 4; the description adds meaning by specifying what kind of data is returned (documentation categories).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it retrieves foundation/token documentation categories with examples (colors, typography, spacing), distinguishing it from sibling tools like get_component_props or get_import which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives; sibling tools are listed but not described, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_importC

Get the correct import statement for a component

ParametersJSON Schema
NameRequiredDescriptionDefault
componentNameYesComponent name, e.g. "PxButton" or "button"

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as side-effects, rate limits, or that it is a read-only operation. The agent is left to infer safety from the name, but no explicit statement is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 9 words, containing no unnecessary information. It is front-loaded with the verb and resource, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's simplicity, the description omits important context such as the output format (e.g., full import statement syntax, quotes, relative/absolute path) and potential error conditions. For an agent to use it correctly, it needs these details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not add meaning beyond the input schema, which already fully documents the single parameter with an example. Since schema coverage is 100%, a baseline of 3 is appropriate; no additional param semantics are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'correct import statement for a component', which is specific. However, it doesn't specify the component system or library, leaving some ambiguity about the context. It distinguishes from sibling tools like 'get_component_props' by focusing on imports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites or context, such as whether the component must already exist or be known, or when to use 'get_component_props' instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_peer_dependenciesA

Get peer dependencies required to use the Phenom DS

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must disclose behavioral traits. It does not mention that the tool is read-only or provide any side-effect information, leaving the agent with minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no wasted words, effectively communicating the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, no output schema, and no annotations, the description is minimally complete. It tells what the tool does, but lacks detail on return format or usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the description adds no param information. The baseline for 0-parameter tools is 4, and the description is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'peer dependencies' specifically for the Phenom DS, distinguishing it from sibling tools like get_component_props.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the description does not explicitly state when to use or not use this tool, the purpose is straightforward and sibling tools do not overlap significantly, making usage clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_type_detailsC

Get details for a specific prop including its type

ParametersJSON Schema
NameRequiredDescriptionDefault
propNameYesProp name, e.g. "variant"
componentNameYesComponent name, e.g. "PxButton"

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It only mentions 'including its type', which hints at output but does not disclose any behavioral traits such as error handling, authorization, or side effects. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no wasted words. While efficient, it could be structured to front-load the core action more effectively. Still, it is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description is too sparse. It only mentions 'type' as the detail returned, but agents may need to know what other fields (e.g., default value, description) are included. Incomplete for a detail retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters (componentName and propName) documented. The tool description adds no extra meaning beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (Get) and resource (details for a specific prop including its type). However, it does not distinguish this tool from the sibling 'get_component_props', which likely lists all props. The purpose is clear but lacks sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'get_component_props'. The description only states what the tool does without any context on selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_componentsA

List all available components in the Phenom DS

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description does not disclose behavioral traits such as whether the list is exhaustive, paginated, or has restrictions. It only states the action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, well-structured sentence that immediately states the tool's purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with no parameters or output schema, the description is minimally adequate but lacks details about what information is returned (e.g., names, IDs).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description provides no parameter info, which is acceptable. Baseline for no parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' and resource 'components', clearly distinguishing from siblings like get_component_props or search_components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives is provided. The description simply states what it does without any context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_componentsC

Search for components by name or selector

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch term — matches component name, selector, or id

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It only states the basic purpose but omits what the search returns (e.g., list of matching components?), result count limits, partial match behavior, or performance considerations. The agent is left guessing about side effects or reliability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, no-fluff sentence that directly states the tool's purpose. Every word earns its place; there is no redundancy or unnecessary detail. It is optimally concise for the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of output schema and annotations, the description is insufficient for complete understanding. It does not explain the output format, whether results are sorted, or how it differs from sibling tools (e.g., list_components). For a search tool, this leaves critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides a description for the 'query' parameter (matches name, selector, or id). The tool description adds little beyond restating 'name or selector'. Since schema coverage is 100%, baseline is 3; the description adds marginal value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for components by name or selector, which is a specific verb+resource. However, it does not differentiate from sibling tools like 'list_components' or 'get_component_props', missing an opportunity to clarify when to use search vs. list. A score of 4 reflects clear purpose but lack of sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., list_components for full listing, get_component_props for specific component details). Without context on when to search vs. list, the agent lacks decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.0.0
    • First observedget_component_props
    • First observedget_foundations
    • First observedget_import
    • First observedget_peer_dependencies
    • First observedget_type_details
    • First observedlist_components
    • First observedsearch_components
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly defined purpose covering different aspects of a design system: listing, searching, getting props, types, imports, foundations, and peer dependencies. No two tools overlap significantly.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern using snake_case (e.g., list_components, get_component_props). The naming is predictable and clear.

Tool Count5/5

With 7 tools, the server covers essential operations for a design system without being too minimal or overloaded. Each tool addresses a specific developer need.

Completeness5/5

The tool set covers the full lifecycle of using a component library: discovery (list/search), configuration (props, imports, peer dependencies), and understanding (foundations, type details). No obvious gaps for typical tasks.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • claude-design-mcp

    e-brokenc0de
    A
    license
    B
    quality
    D
    maintenance
    An MCP server that drives Anthropic's Claude Design from agentic coding CLIs, providing tools to create, generate, iterate, and export design systems without a browser.
    32
    MIT

  • Insider Design System MCP

    denizzeybek-fe
    F
    license
    B
    quality
    D
    maintenance
    Automated MCP server for the Insider Design System. Enables AI assistants to discover, understand, and generate code for over 60 Design System components with automated extraction from source code.
    14
    -

  • exo

    guqing
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that ingests various data sources and uses LLMs to compile them into structured knowledge pages, enabling hybrid search and integration with AI coding tools like Claude Code and Cursor.
    14 npm
    1
    MIT