ui-context

Generate MCP Servers from frontend component libraries

Quick Start · CLI Commands · MCP Tools · Documentation · npm

ui-context extracts component metadata (props, events, methods, slots, design tokens) from your React and Angular component libraries and exposes them via an MCP (Model Context Protocol) server. This gives AI assistants like Claude Desktop, Cursor, and other MCP-compatible tools deep knowledge of your design system.

Features

• Multi-Framework — First-class support for React and Angular, with an extensible parser registry
• Universal Schema — Framework-agnostic component metadata representation
• MCP Integration — Stdio-based MCP server compatible with Claude Desktop, Cursor, and more
• Intelligent Search — Find components by name, category, props, or free-text query with relevance scoring
• Auto-Discovery — Extracts examples from Storybook stories and JSDoc tags
• Design Tokens — Captures colors, spacing, typography, and other tokens
• Validation — CLI command to check metadata completeness and quality
• TypeScript First — Full type safety across the entire stack

Architecture

ui-context/
├── packages/
│   ├── core/              # Universal schema & parser interface
│   ├── parser-react/      # React parser (react-docgen)
│   ├── parser-angular/    # Angular parser (ts-morph)
│   ├── mcp-server/        # MCP server runtime
│   └── cli/               # CLI tool
└── examples/
    ├── react-sample-lib/
    └── angular-sample-lib/

Package	Version	Description
@ui-context/core		Universal component schema, parser interface, and plugin registry
@ui-context/parser-react		Parses React components using react-docgen (TSX, JSX, TS, JS)
@ui-context/parser-angular		Parses Angular components using ts-morph (decorators + signal APIs)
@ui-context/mcp-server		Creates and runs MCP servers from extracted metadata
@ui-context/cli		CLI to generate, validate, and serve component metadata

Documentation: oluizcarvalho.github.io/ui-context  |  npm: @ui-context  |  Source: github.com/oluizcarvalho/ui-context

Quick Start

1. Install

npm install @ui-context/cli

Or use directly with npx (no install needed):

npx @ui-context/cli generate -s ./src/components -p react

2. Generate metadata from your component library

# React
npx ui-context generate -s ./path/to/components -p react -o ./output

# Angular
npx ui-context generate -s ./path/to/components -p angular -o ./output

This produces two files:

• components.json — Extracted component metadata
• mcp-config.json — Ready-to-use config snippet for AI tools

3. Validate metadata quality

npx ui-context validate -d ./output/components.json

4. Start the MCP server

npx ui-context serve -d ./output/components.json

5. Connect to your AI tool

Claude CLI (Claude Code) — register via terminal, no JSON editing needed:

# Project scope (default)
claude mcp add my-design-system -- npx -y @ui-context/cli serve -d path/to/components.json

# Global scope
claude mcp add --scope global my-design-system -- npx -y @ui-context/cli serve -d path/to/components.json

Claude Desktop (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-design-system": {
      "command": "npx",
      "args": ["-y", "@ui-context/cli", "serve", "-d", "path/to/components.json"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "my-design-system": {
      "command": "npx",
      "args": ["-y", "@ui-context/cli", "serve", "-d", "path/to/components.json"]
    }
  }
}

CLI Commands

ui-context generate

Extract component metadata from source files.

Usage: ui-context generate [options]

Options:
  -s, --source <path>        Source directory (required)
  -p, --parser <name>        Parser to use: "react" or "angular" (required)
  -o, --output <path>        Output directory (default: ./ui-context-output)
  --name <name>              Library name (defaults to directory name)
  --include <patterns...>    Glob patterns to include
  --exclude <patterns...>    Glob patterns to exclude

ui-context serve

Start an MCP server from generated metadata.

Usage: ui-context serve [options]

Options:
  -d, --data <path>    Path to components.json (required)

ui-context validate

Check metadata for completeness and quality.

Usage: ui-context validate [options]

Options:
  -d, --data <path>    Path to components.json (required)

Validation checks:

• Errors — Missing library name, no components, missing component names
• Warnings — Missing descriptions, untyped props, missing examples

MCP Tools

Once the server is running, AI assistants can use these tools:

Programmatic API

Core

import { ParserRegistry } from "@ui-context/core";
import type { ComponentMetadata, LibraryMetadata } from "@ui-context/core";

Parsers

import { createParser } from "@ui-context/parser-react";
// or
import { createParser } from "@ui-context/parser-angular";

const parser = createParser();
const components = await parser.parse({ sourcePath: "./src/components" });

MCP Server

import { createMcpServer, startServer } from "@ui-context/mcp-server";

// From metadata object
const server = createMcpServer(libraryMetadata);

// From file
await startServer("./components.json");

Development

# Clone the repository
git clone https://github.com/oluizcarvalho/ui-context.git
cd ui-context

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT