Component Library MCP Server

# 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