Component Library MCP Server (TypeScript)

A type-safe MCP (Model Context Protocol) server built with TypeScript that provides AI assistants with access to your private React component library documentation and examples.

Features

• 🎯 Type-safe implementation using TypeScript
• 🛠️ Modern MCP SDK with McpServer and .tool() methods
• 📦 Three core tools:
  • list_components - Lists all components with optional category filtering
  • get_component - Retrieves detailed documentation, props, and usage
  • get_example - Provides code examples for components
• 🔍 Smart parsing:
  • Markdown files with frontmatter metadata
  • TypeScript prop extraction from source files
  • Inline code block extraction from docs
• ⚡ Performance optimized with component caching

Quick Start

1. Install

# Clone or download the server
cd component-library-mcp-ts

# Install dependencies
npm install

# Build TypeScript
npm run build

2. Configure

Set environment variables for your paths:

export COMPONENTS_PATH="/path/to/your/component-library/src/components"
export DOCS_PATH="/path/to/your/documentation-site/content"
export EXAMPLES_PATH="/path/to/your/documentation-site/examples"

Or create a .env file:

COMPONENTS_PATH=/path/to/your/components
DOCS_PATH=/path/to/your/docs
EXAMPLES_PATH=/path/to/your/examples

3. Test

Run the test suite to verify everything works:

npm test

4. Configure Claude Desktop

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "component-library": {
      "command": "node",
      "args": ["/absolute/path/to/component-library-mcp-ts/dist/index.js"],
      "env": {
        "COMPONENTS_PATH": "/path/to/your/library/src",
        "DOCS_PATH": "/path/to/your/docs",
        "EXAMPLES_PATH": "/path/to/your/examples"
      }
    }
  }
}

For development mode (with hot reload):

{
  "mcpServers": {
    "component-library": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/component-library-mcp-ts/src/index.ts"],
      "env": {
        "COMPONENTS_PATH": "/path/to/your/library/src",
        "DOCS_PATH": "/path/to/your/docs",
        "EXAMPLES_PATH": "/path/to/your/examples"
      }
    }
  }
}

Documentation Structure

Organize your documentation like this:

docs/
├── components/
│   ├── Panel.md        # Component documentation with frontmatter
│   ├── Button.md
│   ├── Form.md
│   └── TextBox.md
└── examples/
    ├── Panel.tsx       # Component examples (optional)
    ├── Button.tsx
    └── Form.tsx

Component Documentation Format

Use Markdown with YAML frontmatter:

---
name: Panel
category: layout
description: A flexible container component for grouping content
importPath: '@your-library/Panel'
status: stable
version: 2.1.0
dependencies: ['Button', 'Icon']
accessibility: WCAG 2.1 AA compliant
---

# Panel Component

The Panel component provides consistent spacing and styling for grouped content.

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| title | string | No | - | Optional header title |
| variant | 'default' \| 'bordered' \| 'shadow' | No | 'default' | Visual style |

## Usage

\`\`\`tsx
import { Panel } from '@your-library/Panel';

function Example() {
  return (
    <Panel title="Settings" variant="shadow">
      <p>Content goes here</p>
    </Panel>
  );
}
\`\`\`

TypeScript Support

The server includes full TypeScript support with:

Type Definitions

interface ComponentInfo {
  name: string;
  category?: string;
  description?: string;
  importPath?: string;
  status?: 'stable' | 'beta' | 'deprecated' | 'experimental';
  version?: string;
  dependencies?: string[];
  props?: ComponentProps;
  documentation?: string;
  accessibility?: string;
}

interface ComponentProps {
  [key: string]: {
    type: string;
    required: boolean;
    description?: string;
    defaultValue?: any;
  }
}

Prop Extraction

The server automatically extracts props from TypeScript interfaces:

// Your component file
interface PanelProps {
  /** Optional title for the panel header */
  title?: string;
  /** Visual style variant */
  variant?: 'default' | 'bordered' | 'shadow';
  /** Content to display */
  children: ReactNode;
}

Usage in Claude

Once configured, use these commands in Claude:

Basic Commands

"Use the component-library MCP to list all components"

"Get details about the Panel component using component-library"

"Show me examples of using the Form component"

"List all components in the 'forms' category"

Building Applications

"Use component-library MCP to gather information about components needed for a user dashboard"

"Help me build a settings page using our component library - get the relevant components"

Development

Scripts

# Build TypeScript
npm run build

# Run in development mode (with tsx)
npm run dev

# Run tests
npm test

# Start production server
npm start

Project Structure

component-library-mcp-ts/
├── src/
│   ├── index.ts        # Main server implementation
│   ├── types.ts        # TypeScript type definitions
│   └── test.ts         # Test suite
├── dist/               # Compiled JavaScript (after build)
├── example-docs/       # Example documentation
│   ├── components/     # Component docs with frontmatter
│   └── examples/       # Component examples
├── tsconfig.json       # TypeScript configuration
├── package.json
└── README.md

Extending the Server

Add new tools by extending the setupTools() method:

// In src/index.ts
this.server.tool(
  'search_components',
  'Search components by keyword',
  {
    query: z.string().describe('Search query'),
    limit: z.number().optional().describe('Maximum results')
  },
  async (args) => {
    // Implementation here
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(results)
      }]
    };
  }
);

Advanced Features

Custom Metadata

Extend component metadata in frontmatter:

---
name: DataGrid
category: display
description: High-performance data grid with virtual scrolling
importPath: '@your-library/DataGrid'
status: beta
version: 3.0.0-beta.2
minReactVersion: 18.0.0
dependencies: 
  - VirtualScroller
  - TableHeader
  - TableCell
performance:
  maxRows: 100000
  virtualScrolling: true
accessibility: 
  wcag: 2.1 AA
  ariaSupport: full
  keyboardNavigation: true
---

Environment-Specific Configs

Use different paths for different environments:

{
  "mcpServers": {
    "component-library-dev": {
      "command": "npx",
      "args": ["tsx", "/path/to/src/index.ts"],
      "env": {
        "COMPONENTS_PATH": "/path/to/dev/components",
        "NODE_ENV": "development"
      }
    },
    "component-library-prod": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "COMPONENTS_PATH": "/path/to/prod/components",
        "NODE_ENV": "production"
      }
    }
  }
}

Troubleshooting

TypeScript Build Issues

# Clear build and rebuild
rm -rf dist
npm run build

Component Not Found

• Ensure file naming matches component name
• Check that paths are correctly configured
• Verify frontmatter YAML is valid

Props Not Detected

• Props interface must be named *Props (e.g., PanelProps)
• Ensure component files are accessible via COMPONENTS_PATH
• Check TypeScript syntax is valid

Server Connection Issues

• Use absolute paths in Claude Desktop config
• Ensure Node.js is in PATH
• Check server has read permissions for all paths
• Try development mode with tsx for debugging

License

MIT