@aleph-alpha/lib-mcp

MCP (Model Context Protocol) Server for UI Library and ChatKit component discovery tools.

Overview

This package provides an MCP server that enables AI assistants (like Claude and Cursor) to discover and understand components from:

• @aleph-alpha/ui-library — Ui* components
• @aleph-alpha/chat-kit — Ck* components

It offers tools to list available components and retrieve detailed documentation including props, examples, and usage guidance.

Installation

Install @aleph-alpha/lib-mcp together with the component packages whose docs you want to query. UI Library is required; ChatKit is optional and only needed if you want Ck* component docs.

# UI Library only
pnpm add @aleph-alpha/lib-mcp @aleph-alpha/ui-library

# UI Library + ChatKit
pnpm add @aleph-alpha/lib-mcp @aleph-alpha/ui-library @aleph-alpha/chat-kit

ChatKit docs require @aleph-alpha/chat-kit to publish its src/ directory (component types.ts and *.stories.ts files). If get_chat_kit_docs returns "Could not find chat-kit source directory", upgrade @aleph-alpha/chat-kit to a version that includes src/ in its published files.

Usage

Configure MCP Server

Run the install command to configure your IDE:

# For Claude Code
npx @aleph-alpha/lib-mcp mcp-install

# For both Claude Code and Cursor
npx @aleph-alpha/lib-mcp mcp-install --cursor

# For VS Code
npx @aleph-alpha/lib-mcp mcp-install --vscode

After installation, restart your IDE to activate the MCP tools.

Available MCP Tools

Once configured, the following tools are available to your AI assistant:

UI Library tools

list_components

Lists all available UI Library components. Supports optional filtering by name, category, or description.

list_components
list_components --filter="button"
list_components --filter="form"

get_component_docs

Retrieves full documentation for a specific UI Library component including:

• Component description
• Props with types, defaults, and descriptions
• Sub-components (if applicable)
• Usage guidance
• Code examples

get_component_docs UiButton
get_component_docs Button  # "Ui" prefix is optional

ChatKit tools

Available when @aleph-alpha/chat-kit is installed alongside this package.

list_chat_kit_components

Lists all available ChatKit (Ck*) components. Supports optional filtering by name, category, or description.

list_chat_kit_components
list_chat_kit_components --filter="history"
list_chat_kit_components --filter="message"

get_chat_kit_docs

Retrieves full documentation for a specific ChatKit component, with the same shape as get_component_docs:

• Component description
• Props with types, defaults, and descriptions
• Sub-components (if applicable)
• Usage guidance
• Code examples

get_chat_kit_docs CkHistory
get_chat_kit_docs History  # "Ck" prefix is optional

Setup tool

get_setup_guide

Returns the setup and installation guide for integrating the UI library into a project (UnoCSS config, Vite config, required dependencies, and MCP setup instructions).

get_setup_guide

Development

Building

pnpm build

Generating Component Metadata

Regenerates components-meta.json (UI Library) and chat-kit-components-meta.json (ChatKit) by scanning each package's source files.

pnpm generate:component-meta

Testing

pnpm test

How It Works

The MCP server reads component metadata from each package's source layout:

1. types.ts: Extracts props, their types, descriptions, and component-level JSDoc tags (@category, @useCases, @keywords, @related)
2. *.stories.ts: Extracts code examples and usage guidance from Storybook stories
3. index.ts: Detects sub-component exports for the documented component
4. components-meta.json / chat-kit-components-meta.json: Pre-generated metadata for faster lookups

UI Library components are read from @aleph-alpha/ui-library/src/**, and ChatKit components from @aleph-alpha/chat-kit/src/components/**. Both packages must publish their src/ directory for docs to resolve when consumed from node_modules.

CLI Commands

| Command | Description | | ------------- | ----------------------------------------------------------------------- | | mcp-install | Configure MCP server for IDE (--cursor, --vscode to add extra IDEs) | | serve | Start the MCP server (used internally by IDE) | | --help | Show help message |

License

Apache-2.0