@instincthub/react-ui-mcp-server

v1.0.1

Published

9 months ago

MCP server for InstinctHub React UI component recommendations and code generation

0High
0Medium
0Low

noaholatoye

mcp model-context-protocol instincthub react-ui components typescript claude ai code-generation component-library

InstinctHub React UI - Local MCP Server

This directory contains the local Model Context Protocol (MCP) server for InstinctHub React UI. This server enables AI tools like Claude Code CLI to interact with the InstinctHub React UI component library through natural language.

🎯 What This Is

A local MCP server that runs on your machine and connects to the remote InstinctHub React UI API at https://ui.instincthub.com. It acts as a bridge between AI tools and the component library.

✨ Features

🔍 Component Search: Find components by name, description, or functionality
📖 Documentation Access: Get detailed docs, examples, and usage guides
🤖 AI Recommendations: Get intelligent component suggestions
🛠️ Code Generation: Generate TypeScript/JavaScript code examples
🤝 Integration Help: Get step-by-step integration guides

🏗️ Architecture

Claude Code CLI → Local MCP Server → Remote API (ui.instincthub.com)

Installation

Quick Start (Recommended)

Add the MCP server to any project with a single command:

claude mcp add instincthub-react-ui -e API_BASE_URL=https://ui.instincthub.com -- npx -y @instincthub/react-ui-mcp-server

This will:

Add the InstinctHub React UI MCP server to your Claude Code CLI configuration
Set the correct API base URL
Install and run the server automatically

Manual Installation

For development or manual setup:

Install dependencies:

npm install

Build the server:

npm run build

Generate component data:

npm run generate-components

Usage

Starting the Server

npm start

Available Tools

1. search_components

Search for components by name, description, or category.

{
  "name": "search_components",
  "arguments": {
    "query": "input button form",
    "category": "Forms",
    "limit": 10
  }
}

2. get_component_docs

Get detailed documentation for a specific component.

{
  "name": "get_component_docs",
  "arguments": {
    "component_name": "SubmitButton",
    "include_examples": true,
    "include_props": true
  }
}

3. generate_code

Generate code examples for component usage.

{
  "name": "generate_code",
  "arguments": {
    "components": ["SubmitButton", "InputText"],
    "pattern": "form",
    "framework": "nextjs",
    "typescript": true
  }
}

4. integration_help

Get integration help for specific topics.

{
  "name": "integration_help",
  "arguments": {
    "topic": "installation",
    "framework": "nextjs"
  }
}

5. recommend_components

Get AI-powered component recommendations.

{
  "name": "recommend_components",
  "arguments": {
    "description": "I need to build a user login form with validation",
    "context": "Next.js application with TypeScript",
    "complexity": "medium"
  }
}

Component Categories

The server organizes components into the following categories:

Forms (30+ components): Input fields, validation, form controls
UI (20+ components): Cards, tables, charts, dialogs, buttons
Auth (8+ components): Authentication, session management, user handling
Navbar (6+ components): Navigation, menus, breadcrumbs
Status (10+ components): Error states, notifications, loading indicators
Theme (6+ components): Dark mode, styling, theme providers
Tabs (3+ components): Tab navigation and content
Cursors (5+ components): Custom cursor effects and animations
Library (1+ components): Utility components and integrations

Examples

Finding Form Components

curl -X POST http://localhost:3010/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "method": "tools/call",
    "params": {
      "name": "search_components",
      "arguments": {
        "query": "input form validation",
        "category": "Forms"
      }
    }
  }'

Getting Component Documentation

curl -X POST http://localhost:3010/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "method": "tools/call",
    "params": {
      "name": "get_component_docs",
      "arguments": {
        "component_name": "IHubTable",
        "include_examples": true
      }
    }
  }'

AI-Powered Recommendations

curl -X POST http://localhost:3010/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "method": "tools/call",
    "params": {
      "name": "recommend_components",
      "arguments": {
        "description": "I want to create a dashboard with charts and data tables",
        "context": "Analytics application with real-time data"
      }
    }
  }'

Configuration

Automatic Configuration (Recommended)

Use the one-liner command for automatic setup:

claude mcp add instincthub-react-ui -e API_BASE_URL=https://ui.instincthub.com -- npx -y @instincthub/react-ui-mcp-server

Manual Configuration

Option 1: NPX-based (Recommended)

{
  "mcpServers": {
    "instincthub-react-ui": {
      "command": "npx",
      "args": ["-y", "@instincthub/react-ui-mcp-server"],
      "env": {
        "API_BASE_URL": "https://ui.instincthub.com"
      }
    }
  }
}

Option 2: Local Development Build

For local development or when you have the repository cloned:

{
  "mcpServers": {
    "instincthub-react-ui": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"],
      "env": {
        "API_BASE_URL": "https://ui.instincthub.com"
      },
      "cwd": "/mnt/c/Users/instincthub/code_projects/npm/instincthub-react-ui"
    }
  }
}

Requirements: Local build must exist (npm run build)

Alternative: Docker-based (Limited Support)

Docker exec approach for containers (may have stdio issues):

{
  "mcpServers": {
    "instincthub-react-ui": {
      "command": "docker",
      "args": ["exec", "-i", "instincthub-mcp-server", "node", "dist/index.js"],
      "env": {
        "API_BASE_URL": "https://ui.instincthub.com"
      }
    }
  }
}

Note: Docker exec may not work reliably with MCP stdio transport. Use Direct Node.js if this fails.

Claude Desktop Configuration

Claude Desktop supports the same configuration options:

Recommended: NPX-based

{
  "mcpServers": {
    "instincthub-react-ui": {
      "command": "npx",
      "args": ["-y", "@instincthub/react-ui-mcp-server"],
      "env": {
        "API_BASE_URL": "https://ui.instincthub.com"
      }
    }
  }
}

Alternative: Local Development

{
  "mcpServers": {
    "instincthub-react-ui": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"],
      "env": {
        "API_BASE_URL": "https://ui.instincthub.com"
      },
      "cwd": "/mnt/c/Users/instincthub/code_projects/npm/instincthub-react-ui"
    }
  }
}

Development

File Structure

mcp-server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── tools/                # MCP tools implementation
│   │   ├── component-search.ts
│   │   ├── component-docs.ts
│   │   ├── code-generator.ts
│   │   ├── integration-helper.ts
│   │   └── component-recommendation.ts
│   ├── scripts/              # Utility scripts
│   │   └── generate-components.ts
│   ├── types/                # TypeScript types
│   │   └── index.ts
│   └── data/                 # Generated component data
│       ├── components.json
│       ├── categories.json
│       └── summary.json
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Development Mode

npm run dev

Updating Component Data

When components are added or updated in the main library:

npm run generate-components

📦 Publishing

NPM Package

The MCP server is published as @instincthub/react-ui-mcp-server on NPM for easy installation:

# Install globally
npm install -g @instincthub/react-ui-mcp-server

# Run directly with npx (recommended)
npx @instincthub/react-ui-mcp-server

# Use in Claude Code CLI
claude mcp add instincthub-react-ui -e API_BASE_URL=https://ui.instincthub.com -- npx -y @instincthub/react-ui-mcp-server

Publishing Steps (for maintainers)

# Build the package
npm run build

# Publish to NPM
npm publish --access public

🐳 Docker Deployment

The MCP server can be containerized for consistent deployment across environments.

Quick Start with Docker

# Build and run with Docker Compose (recommended)
npm run docker:prod

# Or build and run manually
npm run docker:build
npm run docker:run

Docker Commands

# Development mode with hot reload
npm run docker:dev

# Production mode (detached)
npm run docker:prod

# View logs
npm run docker:logs

# Stop all services
npm run docker:stop

Checking Server Status

Verify if the MCP server is running and troubleshoot issues:

# Check if MCP server container is running
docker ps | grep instincthub

# Check Docker Compose service status
docker-compose ps

# View server logs (useful for debugging)
docker-compose logs mcp-server

# Follow logs in real-time
docker-compose logs -f mcp-server

# Check if ports are in use
# Windows:
netstat -ano | findstr :3010
netstat -ano | findstr :3011

# Linux/Mac:
lsof -i :3010
lsof -i :3011

# Check for MCP server processes
ps aux | grep mcp-server

# Test server health (if health endpoint is available)
curl http://localhost:3010/health || echo "Server not responding on port 3010"
curl http://localhost:3011/health || echo "Server not responding on port 3011"

Expected Results When Running:

docker ps shows instincthub-mcp-server container
docker-compose ps shows service status as "Up"
Ports 3010/3011 are in use by Docker
Logs show "InstinctHub React UI MCP Server started"

Troubleshooting:

If no containers: Run npm run docker:prod to start
If port conflicts: Check what's using the port and stop it
If build errors: Check docker-compose logs for details
If startup fails: Verify all dependencies are installed

MCP Client Troubleshooting

MCP tools not detected:

Ensure Docker container is running (for Docker-based config):
```
docker ps | grep instincthub-mcp-server
```

Test MCP server manually:

# For Docker config:
docker exec -i instincthub-mcp-server node dist/index.js
   
# For Direct Node.js config:
node mcp-server/dist/index.js

Restart Claude Code CLI after configuration changes
Check configuration syntax:
```
cat .claude_code_config.json | jq .
```

Common Issues:

MCP tools not detected: Use Direct Node.js configuration (recommended)
"stdio timeout": Switch from Docker exec to Direct Node.js configuration
"Container not found": Ensure Docker container is running with npm run docker:prod
"Command not found": Verify Node.js is installed and accessible
Direct Node.js works, Docker doesn't: This is expected - MCP stdio transport works better with direct processes

Recommended Solution: Use Direct Node.js configuration for MCP clients, Docker for deployment only.

Docker Compose Services

The project includes two Docker services:

mcp-server (Production)
- Optimized multi-stage build
- Runs on port 3010
- Non-root user for security
mcp-server-dev (Development)
- Hot reload with volume mounting
- Runs on port 3011
- TypeScript watch mode

Docker Environment Variables

NODE_ENV: Set to production or development
API_BASE_URL: Remote API endpoint (default: https://ui.instincthub.com)

Docker Health Check

The container includes a health check that runs every 30 seconds:

# Manual health check
docker exec <container_id> node -e "console.log('MCP Server Health Check: OK')"

Docker Configuration

Dockerfile Features:

Multi-stage build for optimized image size
Non-root user for security
Health check endpoint
Proper signal handling

Volume Mounting:

Component data persistence
Development source code mounting
Configuration file access

Deployment Examples

Production Deployment

# Build and deploy
docker-compose up mcp-server --build -d

# Check status
docker-compose ps
docker-compose logs -f mcp-server

Development Environment

# Start development server with hot reload
docker-compose --profile development up mcp-server-dev --build

# Access logs
docker-compose logs -f mcp-server-dev

Custom Configuration

# Run with custom API URL
docker run -e API_BASE_URL=https://custom-api.com instincthub-mcp-server

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests and build
Submit a pull request

License

MIT License - see the main package license for details.

Support

For issues and questions:

GitHub Issues: https://github.com/instincthub/instincthub-react-ui/issues
Documentation: https://github.com/instincthub/instincthub-react-ui#readme

Changelog

v1.0.0

Initial release with 5 core tools
Support for 80+ components across 9 categories
AI-powered component recommendations
TypeScript support
Next.js integration guides