ui-context

Features

Architecture

ui-context is a TypeScript monorepo with five focused packages that work together:

Quick Start

Get up and running in under 5 minutes.

npm install @ui-context/cli

# 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

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

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

Installation

Prerequisites

• Node.js ≥ 18
• npm (comes with Node.js)

From npm (recommended)

# Install the CLI globally
npm install -g @ui-context/cli

# Or use directly with npx (no install needed)
npx @ui-context/cli generate -s ./src/components -p react

You can also install individual packages:

npm install @ui-context/core
npm install @ui-context/parser-react
npm install @ui-context/parser-angular
npm install @ui-context/mcp-server

From source (for contributors)

git clone https://github.com/oluizcarvalho/ui-context.git
cd ui-context
npm install
npm run build

Try with the example libraries

After cloning the repository, you can test with the included sample libraries:

# React example
npx ui-context generate -s ./examples/react-sample-lib/src/components -p react

# Angular example
npx ui-context generate -s ./examples/angular-sample-lib/src/components -p angular

CLI Commands

ui-context generate

Extract component metadata from source files.

# Basic usage
npx ui-context generate -s ./src/components -p react

# With options
npx ui-context generate \
  -s ./src/components \
  -p react \
  -o ./docs/metadata \
  --name "My Design System" \
  --exclude "**/*.test.*" "**/__mocks__/**"

ui-context serve

Start an MCP server from generated metadata.

ui-context validate

Check metadata for completeness and quality issues.

MCP Tools

Once the server is running, AI assistants can query your component library using these tools:

Search scoring

The search_components tool uses weighted matching:

Configuration

After running generate, connect the MCP server to your AI tool.

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

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

Cursor

Add to .cursor/mcp.json in your project root:

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

Programmatic API

Use ui-context packages directly in your TypeScript/JavaScript code.

Core Schema

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

Using Parsers

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

const parser = createParser();
const components = await parser.parse({
  sourcePath: "./src/components",
  include: ["**/*.tsx"],
  exclude: ["**/*.test.*"],
});

Creating an MCP Server

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

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

// Or start directly from a file
await startServer("./output/components.json");

Parser Registry

import { ParserRegistry } from "@ui-context/core";

const registry = new ParserRegistry();

// Register a custom parser
registry.register(myCustomParser);

// Resolve a parser by name (supports auto-discovery)
const parser = await registry.resolve("react");
const components = await parser.parse({ sourcePath: "./src" });

Examples

The repository includes sample component libraries to help you get started.

React Example

// examples/react-sample-lib/src/components/Button.tsx

export interface ButtonProps {
  /** The button label text */
  label: string;
  /** Visual variant */
  variant?: "primary" | "secondary" | "danger";
  /** Size of the button */
  size?: "sm" | "md" | "lg";
  /** Whether the button is disabled */
  disabled?: boolean;
  /** Click handler */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
}

export const Button: React.FC<ButtonProps> = ({
  label,
  variant = "primary",
  size = "md",
  disabled = false,
  onClick,
}) => { /* ... */ };

Angular Example

// examples/angular-sample-lib/src/components/button.component.ts

@Component({
  selector: "ui-button",
  template: `
    <button [class]="variant" (click)="handleClick($event)">
      <ng-content></ng-content>
      {{ label }}
    </button>
  `,
})
export class ButtonComponent {
  @Input() label: string = "";
  @Input() variant: "primary" | "secondary" | "danger" = "primary";
  @Output() clicked = new EventEmitter<MouseEvent>();

  focus(): void { /* ... */ }
}

Running the examples

# Parse the React sample library
npx ui-context generate \
  -s ./examples/react-sample-lib/src/components \
  -p react \
  --name "React Sample Lib"

# Parse the Angular sample library
npx ui-context generate \
  -s ./examples/angular-sample-lib/src/components \
  -p angular \
  --name "Angular Sample Lib"

# Validate the output
npx ui-context validate -d ./ui-context-output/components.json

# Start the MCP server
npx ui-context serve -d ./ui-context-output/components.json

Parsers

React Parser

Uses react-docgen to analyze React components:

• Supported extensions: .tsx, .jsx, .ts, .js
• Extracts props from TypeScript interfaces and PropTypes
• Props starting with on + uppercase letter are classified as events
• Discovers examples from .stories.tsx files and @example JSDoc tags
• Ignores test, spec, and story files by default

Angular Parser

Uses ts-morph for TypeScript AST analysis:

• Parses @Component and @Directive decorators
• Extracts @Input() and @Output() metadata
• Supports Angular 14+ signal APIs (input(), output())
• Extracts <ng-content> slots from templates
• Filters lifecycle hooks (ngOnInit, ngOnDestroy, etc.)
• Ignores spec, module, and routing files by default

Custom Parsers

Implement the ComponentParser interface to add support for other frameworks:

import type { ComponentParser, ParserOptions, ComponentMetadata } from "@ui-context/core";

export class VueParser implements ComponentParser {
  name = "vue";
  supportedExtensions = [".vue"];

  async parse(options: ParserOptions): Promise<ComponentMetadata[]> {
    // Your parsing logic here
  }
}

Contributing

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

Development setup

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch