---

name: mcp-server-generator description: Generate complete, production-ready MCP (Model Context Protocol) servers with automatic setup, configuration, and Claude Code integration allowed-tools:

• Read
• Write
• Edit
• Bash
• Glob
• Grep
• Task

---

MCP Server Generator

Expert skill for generating complete, production-ready MCP (Model Context Protocol) servers. Specializes in automated server generation, setup, configuration, and seamless integration with Claude Code.

Core Capabilities

1. Complete Server Generation

• Full TypeScript MCP server with all boilerplate
• Tool implementations (not just templates)
• Type-safe interfaces and schemas
• Error handling and validation
• Logging and debugging support
• Production-ready code quality

2. Automatic Setup & Installation

• Generate server code
• Install dependencies (npm/pnpm/yarn)
• Build TypeScript project
• Configure Claude Code integration
• Test server connection
• Start server automatically

3. Tool Categories Support

• Browser Automation: Playwright, Puppeteer
• Testing: Visual regression, E2E, accessibility
• Development: Live preview, hot reload, DevTools
• Performance: Profiling, metrics, Core Web Vitals
• Utilities: File operations, data processing, API calls
• Custom: Any tool category you need

4. Smart Configuration

• Zero Config: Works out of the box with sensible defaults
• Auto-Detection: Detects project type, framework, tools
• Optional Override: JSON/TypeScript config for customization
• Environment Variables: Support for secrets and configuration
• Multiple Profiles: Dev, staging, production configs

5. Claude Code Integration

• Automatic .claude/config.json configuration
• Server registration and startup
• Health check and monitoring
• Automatic restart on failure
• Logging to Claude Code console

6. Template Library

• Pre-built server templates for common use cases
• UI Testing Server (Playwright + visual regression)
• API Testing Server (HTTP client + validation)
• File Processing Server (read/write/transform)
• Web Scraping Server (browser automation + parsing)
• Custom template creation

Workflow

Phase 1: Analysis & Planning

1. Understand Requirements

   • What tools does the server need to provide?
   • What technologies to use? (Playwright, Puppeteer, etc.)
   • Integration requirements (APIs, databases, etc.)
   • Performance and scalability needs

2. Select Template

   • Use pre-built template if available
   • Identify closest template and customize
   • Create from scratch if needed

3. Plan Architecture

   • Tool organization (categories, naming)
   • Configuration strategy (zero-config vs explicit)
   • Dependencies and external services
   • Error handling approach

Phase 2: Generation

1. Generate Server Structure

   • Create directory structure
   • Generate package.json with dependencies
   • Create tsconfig.json for TypeScript
   • Set up build scripts

2. Implement Tools

   • Generate tool implementations
   • Add input validation and schemas
   • Implement error handling
   • Add logging and debugging

3. Create Configuration

   • Auto-detection logic
   • Default configuration
   • Override mechanism
   • Environment variable support

4. Add Documentation

   • README with setup instructions
   • Tool documentation (inputs, outputs, examples)
   • Troubleshooting guide
   • API reference

Phase 3: Setup & Integration

1. Install & Build

   • Run npm install
   • Compile TypeScript
   • Run tests (if present)
   • Verify build output

2. Configure Claude Code

   • Add server to .claude/config.json
   • Set up environment variables
   • Configure auto-start
   • Set up logging

3. Test & Verify

   • Start server
   • Test connection
   • Verify tool registration
   • Run sample tool calls
   • Check error handling

4. Documentation & Handoff

   • Generate usage examples
   • Document configuration options
   • Provide troubleshooting steps
   • Create quick start guide

MCP Server Architecture

Standard Structure

Copymcp-server-name/
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment variables template
├── src/
│   ├── index.ts             # Server entry point
│   ├── config/
│   │   ├── auto-detect.ts   # Auto-detection logic
│   │   ├── defaults.ts      # Default configuration
│   │   └── schema.ts        # Config validation schema
│   ├── tools/
│   │   ├── category1/
│   │   │   ├── tool1.ts     # Tool implementation
│   │   │   └── tool2.ts
│   │   └── category2/
│   │       └── tool3.ts
│   ├── utils/
│   │   ├── logger.ts        # Logging utility
│   │   ├── errors.ts        # Error handling
│   │   └── validation.ts    # Input validation
│   └── types/
│       └── index.ts         # TypeScript types
├── scripts/
│   ├── setup.sh             # Setup automation
│   └── configure-claude.sh  # Claude Code config
├── tests/
│   └── server.test.ts       # Server tests
└── README.md                # Documentation

Server Entry Point Template

Copy// src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'

import { loadConfig } from './config/auto-detect.js'
import { registerTools } from './tools/index.js'
import { logger } from './utils/logger.js'

const server = new Server(
  {
    name: 'mcp-server-name',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
)

// Load configuration
const config = await loadConfig()
logger.info('Configuration loaded', config)

// Register all tools
const tools = registerTools(config)
logger.info(`Registered ${tools.length} tools`)

// Handle tool list request
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: tools.map(tool => ({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.inputSchema,
  })),
}))

// Handle tool execution request
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const tool = tools.find(t => t.name === request.params.name)

  if (!tool) {
    throw new Error(`Tool not found: ${request.params.name}`)
  }

  logger.info(`Executing tool: ${tool.name}`, request.params.arguments)

  try {
    const result = await tool.execute(request.params.arguments)
    logger.info(`Tool completed: ${tool.name}`)
    return result
  } catch (error) {
    logger.error(`Tool failed: ${tool.name}`, error)
    throw error
  }
})

// Start server
const transport = new StdioServerTransport()
await server.connect(transport)
logger.info('MCP Server started')

Tool Implementation Template

Copy// src/tools/category/example-tool.ts
import { z } from 'zod'
import { Tool } from '../../types/index.js'

// Input validation schema
const inputSchema = z.object({
  param1: z.string().describe('Description of param1'),
  param2: z.number().optional().describe('Optional param2'),
  options: z.object({
    option1: z.boolean().default(true),
  }).optional(),
})

export const exampleTool: Tool = {
  name: 'example_tool',
  description: 'Does something useful',

  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'Description of param1' },
      param2: { type: 'number', description: 'Optional param2' },
      options: {
        type: 'object',
        properties: {
          option1: { type: 'boolean', default: true },
        },
      },
    },
    required: ['param1'],
  },

  async execute(args: unknown) {
    // Validate input
    const params = inputSchema.parse(args)

    // Implement tool logic
    try {
      const result = await doSomething(params)

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      }
    } catch (error) {
      throw new Error(`Tool execution failed: ${error.message}`)
    }
  },
}

async function doSomething(params: z.infer<typeof inputSchema>) {
  // Implementation here
  return { success: true, data: params }
}

Auto-Detection Example

Copy// src/config/auto-detect.ts
import { existsSync, readFileSync } from 'fs'
import { join } from 'path'

export async function loadConfig() {
  const cwd = process.cwd()

  // Detect package.json
  const packageJsonPath = join(cwd, 'package.json')
  const packageJson = existsSync(packageJsonPath)
    ? JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
    : {}

  // Detect framework
  const framework = detectFramework(packageJson)

  // Detect test runner
  const testRunner = detectTestRunner(packageJson)

  // Detect available ports
  const port = await findAvailablePort(3000)

  // Load user config (if exists)
  const userConfig = loadUserConfig()

  // Merge with defaults
  return {
    port,
    framework,
    testRunner,
    ...getDefaults(),
    ...userConfig,
  }
}

function detectFramework(packageJson: any): string {
  if (packageJson.dependencies?.react) return 'react'
  if (packageJson.dependencies?.vue) return 'vue'
  if (packageJson.dependencies?.svelte) return 'svelte'
  return 'unknown'
}

function detectTestRunner(packageJson: any): string {
  if (packageJson.devDependencies?.vitest) return 'vitest'
  if (packageJson.devDependencies?.jest) return 'jest'
  return 'unknown'
}

function loadUserConfig() {
  // Try .claude/mcp-config.json
  const configPath = join(process.cwd(), '.claude', 'mcp-config.json')
  if (existsSync(configPath)) {
    return JSON.parse(readFileSync(configPath, 'utf-8'))
  }

  // Try package.json mcp-server field
  const packageJsonPath = join(process.cwd(), 'package.json')
  if (existsSync(packageJsonPath)) {
    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
    if (pkg['mcp-server']) {
      return pkg['mcp-server']
    }
  }

  return {}
}

Claude Code Integration

Configuration File

Copy// .claude/config.json
{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["./path/to/server/dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "LOG_LEVEL": "info"
      },
      "autoStart": true
    }
  }
}

Setup Script

Copy#!/bin/bash
# scripts/setup.sh

set -e

echo "🚀 Setting up MCP Server..."

# Install dependencies
echo "📦 Installing dependencies..."
npm install

# Build TypeScript
echo "🔨 Building server..."
npm run build

# Configure Claude Code
echo "⚙️  Configuring Claude Code..."
./scripts/configure-claude.sh

# Test server
echo "🧪 Testing server..."
node dist/index.js --test

echo "✅ Setup complete!"
echo "Server is ready to use."

Configure Claude Script

Copy#!/bin/bash
# scripts/configure-claude.sh

CLAUDE_CONFIG=".claude/config.json"
SERVER_NAME="$1"
SERVER_PATH="$(pwd)/dist/index.js"

# Create .claude directory if not exists
mkdir -p .claude

# Add server to config
if [ -f "$CLAUDE_CONFIG" ]; then
  # Update existing config
  jq ".mcpServers[\"$SERVER_NAME\"] = {
    \"command\": \"node\",
    \"args\": [\"$SERVER_PATH\"],
    \"autoStart\": true
  }" "$CLAUDE_CONFIG" > "$CLAUDE_CONFIG.tmp"
  mv "$CLAUDE_CONFIG.tmp" "$CLAUDE_CONFIG"
else
  # Create new config
  cat > "$CLAUDE_CONFIG" << EOF
{
  "mcpServers": {
    "$SERVER_NAME": {
      "command": "node",
      "args": ["$SERVER_PATH"],
      "autoStart": true
    }
  }
}
EOF
fi

echo "✅ Claude Code configured"

Pre-built Templates

UI Testing Server

Complete server for UI component testing with:

• Visual regression (screenshot, compare, baseline)
• E2E testing (navigate, click, type, forms)
• Component preview (live server, hot reload)
• Performance monitoring (render time, Core Web Vitals)
• Accessibility auditing (WCAG, keyboard nav, ARIA)

Location: templates/ui-testing-server/

API Testing Server

Server for API testing and validation with:

• HTTP client (GET, POST, PUT, DELETE, etc.)
• Request validation (schema, headers, auth)
• Response assertion (status, body, headers)
• Mock server setup
• Load testing support

File Processing Server

Server for file operations with:

• Read/write operations
• Format conversion (JSON, CSV, YAML, XML)
• Data transformation
• Archive operations (zip, tar)
• File watching

Web Scraping Server

Server for web scraping with:

• Page navigation and rendering
• Element selection and extraction
• Data parsing and cleaning
• Pagination handling
• Anti-bot bypass techniques

Best Practices

Server Design

1. Single Responsibility: One server, one domain
2. Tool Granularity: Fine-grained tools over monolithic ones
3. Input Validation: Always validate and sanitize inputs
4. Error Handling: Descriptive errors with context
5. Logging: Comprehensive logging for debugging

Configuration

1. Zero Config First: Work without configuration
2. Smart Defaults: Sensible defaults for common cases
3. Easy Override: Simple config file structure
4. Env Variables: Support for secrets and sensitive data
5. Validation: Validate configuration at startup

Performance

1. Lazy Loading: Load dependencies only when needed
2. Resource Pooling: Reuse expensive resources (browsers, connections)
3. Timeouts: Set reasonable timeouts for all operations
4. Cleanup: Properly dispose resources after use
5. Caching: Cache when appropriate

Security

1. Input Sanitization: Never trust user input
2. File System Access: Restrict to safe directories
3. Network Calls: Validate URLs and domains
4. Secrets: Use environment variables, never hardcode
5. Error Messages: Don't leak sensitive information

Tool Naming Conventions

Naming Rules

• Use snake_case for tool names
• Start with verb (action): create_, get_, update_, delete_
• Be specific and descriptive
• Group related tools with prefixes

Examples

Copy// Good
'screenshot_component'
'navigate_to_url'
'audit_accessibility'
'measure_performance'
'compare_visual_diff'

// Bad (too vague)
'take_pic'
'go'
'check'
'test'

Category Prefixes

Copy// Visual
'visual_screenshot'
'visual_compare'
'visual_baseline'

// Performance
'perf_measure'
'perf_profile'
'perf_trace'

// Accessibility
'a11y_audit'
'a11y_check_wcag'
'a11y_keyboard_nav'

Troubleshooting

Common Issues

Server Won't Start

Copy# Check Node version (requires 18+)
node --version

# Check dependencies
npm install

# Rebuild
npm run build

# Check logs
tail -f .claude/logs/mcp-server-name.log

Tool Not Found

Copy// Verify tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => {
  console.log('Registered tools:', tools.map(t => t.name))
  return { tools }
})

Connection Issues

Copy# Test server manually
echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | node dist/index.js

# Check Claude Code config
cat .claude/config.json

Performance Issues

Copy// Add timeouts
const result = await Promise.race([
  tool.execute(args),
  new Promise((_, reject) =>
    setTimeout(() => reject(new Error('Timeout')), 30000)
  )
])

// Profile execution
console.time('tool-execution')
const result = await tool.execute(args)
console.timeEnd('tool-execution')

When to Use This Skill

Activate this skill when you need to:

• Generate a new MCP server from scratch
• Create custom tools for Claude Code
• Automate server setup and configuration
• Integrate external services with Claude Code
• Build browser automation tools
• Create testing infrastructure
• Implement file processing pipelines
• Set up web scraping capabilities
• Extend Claude Code with new capabilities

Output Format

When generating MCP servers, provide:

1. Complete Server Code: Production-ready, type-safe implementation
2. Configuration Files: package.json, tsconfig.json, config templates
3. Setup Scripts: Automated installation and configuration
4. Documentation: README, tool docs, troubleshooting guide
5. Usage Examples: How to use each tool
6. Integration Guide: How to add to Claude Code

Always generate complete, working code that can be installed and used immediately with minimal configuration.