# 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

```bash
# 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:

```bash
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:

```env
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:

```bash
npm test
```

### 4. Configure Claude Desktop

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

```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):

```json
{
  "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:

```markdown
---
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

```typescript
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:

```typescript
// 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

```bash
# 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:

```typescript
// 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:

```yaml
---
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:

```json
{
  "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

```bash
# 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