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