name

mcp-generator

description

Use when setting up project-specific development tools or after analyzing a codebase - generates custom MCP server with semantic search, project-aware tools, and health monitoring capabilities. Works with both basic and enhanced modes. Do NOT use if generic popkit commands are sufficient or for small projects where MCP server overhead isn't justified - stick with built-in tools for simple workflows.

MCP Server Generator

Overview

Generate a custom MCP (Model Context Protocol) server tailored to the specific project's needs, including semantic search, project-specific tools, and contextual capabilities.

Core principle: Every project deserves tools that understand its unique architecture.

Trigger: /popkit:project mcp command after project analysis

Operating Modes

Mode	Availability	Capabilities
Basic	Always (no API key)	Project analysis, tech stack detection, recommendations
Enhanced	With API key	Custom MCP generation, semantic search, embeddings

Get API key: /popkit:cloud signup (free)

Arguments

Flag	Description
`--from-analysis`	Use `.claude/analysis.json` for tool selection
`--no-embed`	Skip auto-embedding of tools
`--no-semantic`	Don't include semantic search capabilities
`--tools <list>`	Comma-separated list of tools to generate

Generated Structure

.claude/mcp-servers/[project-name]-dev/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/
│   │   ├── project-tools.ts  # Project-specific tools
│   │   ├── health-check.ts   # Service health checks
│   │   └── search.ts         # Semantic search
│   └── resources/
│       └── project-context.ts # Project documentation
└── README.md

Tool Selection Matrix

Framework	Generated Tools
`nextjs`	`check_dev_server`, `check_build`, `run_typecheck`
`express`	`check_api_server`, `health_endpoints`
`prisma`	`check_database`, `run_migrations`, `prisma_studio`
`supabase`	`check_supabase`, `supabase_status`
`redis`	`check_redis`, `redis_info`
`docker-compose`	`docker_status`, `docker_logs`
Common	`git_status`, `git_diff`, `git_recent_commits`, `morning_routine`, `nightly_routine`, `tool_search`

Language-Specific Tools

Node.js: check_nextjs/vite/express, run_typecheck, run_lint, run_tests, npm_scripts Python: run_pytest, run_mypy, check_virtualenv, run_lint (ruff/black) Rust: cargo_check, cargo_test, cargo_clippy

Generation Workflow

Analyze Project - Detect tech stack, frameworks, test tools
Select Tools - Use analysis.json or auto-detect
Generate Code - TypeScript implementations with semantic descriptions
Export Embeddings - tool_embeddings.json for semantic search
Register Server - Update .claude/settings.json
Report Status - Tools created, embedding summary, next steps

📄 See detailed workflow steps (optional)

Step 1: Project Detection

# Detect tech stack
ls package.json Cargo.toml pyproject.toml go.mod 2>/dev/null
# Find main directories
ls -d src lib app components 2>/dev/null
# Detect test framework
grep -l "jest\|mocha\|vitest\|pytest" package.json pyproject.toml 2>/dev/null

Step 2: Tool Implementation

See examples/tool-implementation.ts for detailed examples

Step 3: Server Registration

{
  "mcpServers": {
    "[project]-dev": {
      "command": "node",
      "args": [".claude/mcp-servers/[project]-dev/dist/index.js"]
    }
  }
}

Semantic Tool Descriptions

Write descriptions optimized for semantic search:

Guideline	Example
State action clearly	"Check if...", "Run...", "Get..."
Include target	"...Next.js development server..."
Mention use cases	"...troubleshoot startup issues..."
List outputs	"Returns status, URL, response time"

📋 Before/After Examples

Before (Too Brief)

{
  name: "health:dev-server",
  description: "Check dev server"
}

After (Semantic-Friendly)

{
  name: "health:dev-server",
  description: "Check if the Next.js development server is running and responding on port 3000. Use this to verify the dev environment is working, troubleshoot startup issues, or confirm the app is accessible. Returns status, URL, and response time."
}

Auto-Embedding Tools

Generated servers include tool_embeddings.json for semantic search:

{
  "generated_at": "2025-12-26T10:00:00Z",
  "model": "voyage-3.5",
  "dimension": 1024,
  "tools": [
    {
      "name": "health:dev-server",
      "description": "Check if the Next.js...",
      "embedding": [0.123, 0.456, ...]
    }
  ]
}

Requires Voyage API key. Set VOYAGE_API_KEY environment variable or skip with --no-embed.

Post-Generation Output

MCP server generated at .claude/mcp-servers/[project]-dev/

Tools created (8):
✓ health:dev-server - Check Next.js dev server
✓ health:database - Check PostgreSQL connectivity
✓ quality:typecheck - Run TypeScript type checking
✓ quality:lint - Run ESLint checks
✓ quality:test - Run Jest test suite
✓ git:status - Get git working tree status
✓ git:diff - Show staged and unstaged changes
✓ search:tools - Semantic tool search

Embedding Summary:
- Tool embeddings: .claude/tool_embeddings.json
- Total tools: 8
- Successfully embedded: 8
- Model: voyage-3.5

Next steps:
1. cd .claude/mcp-servers/[project]-dev
2. npm install
3. npm run build
4. Restart Claude Code to load MCP server

Would you like me to build and test it?

Integration Requirements

Optional:

Project analysis (via analyze-project skill) for best results
Voyage AI API key for auto-embedding (recommended)

Enables:

Project-specific tools in Claude Code
Semantic tool search with natural language queries
Health monitoring with detailed status
Custom workflows tailored to your stack
Discoverable tools across projects

See examples/ directory for detailed code samples and implementation patterns.