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

Operating Modes

Get API key:

/popkit:cloud signup

Arguments

--from-analysis

.claude/analysis.json

--no-embed

--no-semantic

--tools <list>

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

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

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

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

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

Step 3: Server Registration

Uses Claude Code 2.0.70+ wildcard syntax:

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

Benefits of wildcard permissions:

• All current and future tools automatically allowed
• Less configuration maintenance
• Clearer intent: "trust this MCP server"
• See

  docs/MCP_WILDCARD_PERMISSIONS.md

  for details

Semantic Tool Descriptions

Write descriptions optimized for semantic search:

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

{
  "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

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

MCP Wildcard Permissions

Added in Claude Code 2.0.70

PopKit-generated MCP servers use wildcard permissions by default:

{
  "mcpServers": {
    "{project-name}-dev": {
      "permissions": {
        "allowed": ["mcp__{project-name}-dev__*"]
      }
    }
  }
}

Permission Patterns

mcp__server__*

mcp__server__health-*

Custom Permissions

Override permissions after generation:

1. Edit

   .claude/settings.json

   or

   .mcp.json

2. Change from wildcard to explicit allow-list if needed
3. Add denied list for risky operations:

{
  "permissions": {
    "allowed": ["mcp__git-tools__*"],
    "denied": ["mcp__git-tools__force-push", "mcp__git-tools__delete-branch"]
  }
}

Documentation:

docs/MCP_WILDCARD_PERMISSIONS.md

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/