MCP Server Generator

A meta-generator for creating dual-mode MCP servers with best practices

Overview

Generate complete, production-ready MCP (Model Context Protocol) servers that work in two modes:

MCP Server Mode: For AI agents (Claude Desktop, etc.)
CLI Mode: For developers

This tool is itself an MCP server, enabling AI agents to generate other MCP servers! It demonstrates the dual-mode architecture pattern it creates and implements progressive disclosure for context-efficient tool discovery.

Why Use This?

⚡ Fast: Generate a complete MCP server in under 5 minutes
🏗️ Complete: Includes tests, documentation, packaging, and CI/CD
✅ Tested: Generated servers have comprehensive test suites with high coverage
🎯 Best Practices: Follows validated patterns from production MCP servers with built-in guidance
🔧 Dual-Mode: Works as both MCP server and CLI tool
🧠 Smart Discovery: Progressive disclosure tools for context-efficient AI agent usage
📦 Ready to Publish: GitHub Actions workflows included for PyPI publishing

Features

✅ Dual-mode architecture (MCP + CLI)
✅ Progressive disclosure tools (context-efficient tool discovery for AI agents)
✅ Built-in guidance (best practices and implementation guides)
✅ Claude Code integration (generate slash commands for guided development)
✅ Async/await support (async handlers for I/O operations, avoids event loop errors)
✅ Package prefix support (avoid PyPI namespace conflicts with AUTO detection)
✅ Complete project scaffolding (tests, docs, packaging)
✅ GitHub Actions workflows (via pypi-workflow-generator)
✅ Comprehensive test suite (92+ tests with high coverage)
✅ Type hints and documentation
✅ Best practices enforcement
✅ Minimal dependencies

Installation

For MCP Server Usage (Recommended)

Using uvx (no installation required):

The easiest way to use this as an MCP server - just configure in Claude Desktop:

{
  "mcpServers": {
    "mcp-server-generator": {
      "command": "uvx",
      "args": ["hitoshura25-mcp-server-generator"]
    }
  }
}

Prerequisites: Install uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

For CLI Usage (Alternative)

Using pipx (isolated installation):

pipx install hitoshura25-mcp-server-generator

Using pip:

pip install hitoshura25-mcp-server-generator

From Source (Development)

git clone https://github.com/hitoshura25/mcp-server-generator.git
cd mcp-server-generator
pip install -e .

Quick Start

Interactive Mode (Recommended)

The easiest way to get started:

hitoshura25-mcp-server-generator-cli --interactive

This will guide you through:

Project naming
Author information
Tool definitions
Configuration options

Command-Line Mode

For automation or when you have a tool definition file:

hitoshura25-mcp-server-generator-cli \
  --project-name my-mcp-tool \
  --description "Does something useful" \
  --author "Your Name" \
  --email "[email protected]" \
  --tools-file tools.json

MCP Server Mode (For AI Agents)

Configure mcp-server-generator as an MCP server in Claude Desktop to let Claude generate MCP servers for you:

Using uvx (recommended):

{
  "mcpServers": {
    "mcp-server-generator": {
      "command": "uvx",
      "args": ["hitoshura25-mcp-server-generator"]
    }
  }
}

Using pipx/pip installation:

{
  "mcpServers": {
    "mcp-server-generator": {
      "command": "hitoshura25-mcp-server-generator"
    }
  }
}

For detailed MCP configuration, see MCP-USAGE.md

MCP Server Tools

When used as an MCP server (in Claude Desktop or other MCP clients), mcp-server-generator provides powerful tools with progressive disclosure support - allowing AI agents to discover and use tools efficiently without loading all schemas upfront.

Discovery Tools

search_tools - Find relevant tools by query

Search by keywords, categories, or use cases
Three detail levels for context efficiency:
- name: Just tool names (most efficient)
- summary: Names + descriptions + categories
- full: Complete information including use cases
Example: search_tools(query="generate", detail_level="summary")

get_tool_info - Get detailed information about a specific tool

Two detail levels: summary or full
Progressive disclosure for context efficiency
Example: get_tool_info(tool_name="generate_mcp_server", detail_level="full")

Generation Tools

generate_mcp_server - Generate complete MCP server projects

Creates dual-mode architecture (MCP + CLI)
Includes tests, documentation, and CI/CD workflows
Production-ready scaffolding with best practices
Supports async/await patterns

generate_claude_command - Create Claude Code command files

Generates .claude/commands/ directory structure
Creates slash commands for guided MCP development
Templates for common workflows: mcp_generator, best_practices, implementation_helper, custom
Enables guided development experience

Validation Tools

validate_project_name - Validate project names

Check Python package compatibility
Avoid Python keyword conflicts
Ensure PyPI naming conventions

Guidance Tools

get_best_practices - MCP development best practices

Progressive disclosure strategies
Context-efficient tool design
Control flow optimization
Security and privacy considerations
State management patterns
Testing strategies

get_implementation_guide - Step-by-step implementation guide

Project setup and initialization
Tool implementation patterns
Testing strategies
Deployment and publishing
Claude Desktop integration

Why Progressive Disclosure?

Progressive disclosure allows AI agents to:

Discover tools without loading full schemas upfront
Save context window space for actual work
Scale to hundreds or thousands of tools
Get exactly the level of detail needed

Example workflow (MCP tool invocations):

# 1. Search for relevant tools
search_tools(query="generate", detail_level="name")
# Returns: ["generate_mcp_server", "generate_claude_command"]

# 2. Get summary of specific tool
get_tool_info(tool_name="generate_mcp_server", detail_level="summary")
# Returns: name, description, category

# 3. Get full details when ready to use
get_tool_info(tool_name="generate_mcp_server", detail_level="full")
# Returns: complete information including use cases and parameters

Package Prefix

To avoid namespace conflicts on PyPI, mcp-server-generator supports prefixing package names. This is highly recommended for unique package names.

Prefix Modes

AUTO (Recommended)

Automatically detects your GitHub username from git config
Priority: github.user → remote URL → user.name (sanitized)
Example: my-tool → username-my-tool

Custom Prefix

Use your own prefix (organization name, brand, etc.)
Example: --prefix acme → acme-my-tool

NONE

No prefix applied (only if you have a truly unique name)
Example: unique-server-name → unique-server-name

Usage Examples

Interactive Mode:

hitoshura25-mcp-server-generator-cli --interactive
# You'll be prompted: "Prefix (default: AUTO): "
# - Press Enter for AUTO detection
# - Type "NONE" for no prefix
# - Type "acme" for custom prefix

Command-Line:

# AUTO mode (default)
hitoshura25-mcp-server-generator-cli --project-name calculator --prefix AUTO ...

# Custom prefix
hitoshura25-mcp-server-generator-cli --project-name calculator --prefix acme ...

# No prefix
hitoshura25-mcp-server-generator-cli --project-name unique-calculator --prefix NONE ...

MCP Server Mode:

{
  "project_name": "calculator",
  "prefix": "AUTO",
  ...
}

Generated Names

With prefix username and project my-tool:

PyPI Package: username-my-tool (install with pip install username-my-tool)
Python Import: username_my_tool (use in code as import username_my_tool)
CLI Command: username-my-tool (run as username-my-tool --help)
MCP Command: mcp-username-my-tool (use in config)

For detailed MCP configuration, see MCP-USAGE.md

What Gets Generated

A complete, production-ready MCP server project:

my-mcp-tool/
├── .gitignore
├── README.md
├── MCP-USAGE.md
├── LICENSE
├── setup.py
├── pyproject.toml
├── requirements.txt
├── MANIFEST.in
├── my_mcp_tool/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── cli.py             # CLI interface
│   ├── generator.py       # Business logic (TODO stubs)
│   └── tests/
│       ├── __init__.py
│       ├── test_server.py  # MCP protocol tests
│       └── test_generator.py  # Core logic tests
└── .github/
    └── workflows/
        └── pypi-publish.yml  # PyPI publishing workflow

Generated Features

✅ Working MCP server with proper JSON-RPC over stdio
✅ CLI interface with argparse
✅ Complete test suite (MCP protocol + business logic)
✅ GitHub Actions workflow for PyPI publishing
✅ Comprehensive documentation (README, MCP-USAGE)
✅ Proper Python packaging (setup.py, pyproject.toml)
✅ TODO stubs for easy implementation

Tool Definition Format

Create a tools.json file to define your MCP server's tools:

{
  "tools": [
    {
      "name": "my_function",
      "description": "Does something useful",
      "parameters": [
        {
          "name": "input_text",
          "type": "string",
          "description": "Text to process",
          "required": true
        },
        {
          "name": "max_length",
          "type": "number",
          "description": "Maximum length",
          "required": false
        }
      ]
    }
  ]
}

Supported Types

string / str
number / int / integer / float
boolean / bool
array / list
object / dict

For complete examples, see EXAMPLES.md

Documentation

MCP-USAGE.md - Detailed MCP server configuration guide
ASYNC_GUIDE.md - Complete guide for using async/await in generated MCP servers
EXAMPLES.md - Example projects and use cases
SECURITY.md - Security guidelines and best practices
CONTRIBUTING.md - Development and contribution guidelines

Security

🔒 Important: MCP servers can be exploited for malicious purposes if not properly secured. See SECURITY.md for comprehensive security guidelines.

Key Security Features

Generated MCP servers include:

Security utilities module (security_utils.py) with ready-to-use functions for:
- Input validation and sanitization
- Path traversal protection
- Command injection prevention
- Rate limiting to prevent high-speed automated attacks
- Audit logging for security-relevant operations
- Sensitive data redaction (PII, credentials, API keys)
Automated security analysis - The generator analyzes your tool definitions and warns about:
- High-risk patterns (command execution, code evaluation)
- Medium-risk patterns (file operations, network access, credential handling)
- Recommendations for secure implementation
Comprehensive security documentation - Every generated project includes SECURITY.md with:
- Threat model based on real-world AI-orchestrated cyber espionage
- Secure coding patterns and examples
- Security checklist for deployment
- Incident response procedures

Best Practices

When creating MCP servers:

Validate all inputs - Use whitelists, not blacklists
Apply principle of least privilege - Tools should do the minimum necessary
Implement rate limiting - Protect against high-speed automated attacks
Add audit logging - Track all security-relevant operations
Redact sensitive data - Don't expose PII, credentials, or secrets
Use security utilities - Leverage the built-in security_utils.py module

Threat Model

MCP servers can be targeted for:

AI-orchestrated cyber espionage campaigns
Jailbreak attempts through task decomposition
High-speed reconnaissance and exploitation
Credential harvesting through tool chaining
Data exfiltration at scale

Reference: Anthropic's research on AI-orchestrated cyber espionage

Testing

The project includes a comprehensive test suite:

# Run all tests
pytest

# Run with coverage report
pytest --cov=hitoshura25_mcp_server_generator --cov-report=term-missing

# Run specific test file
pytest hitoshura25_mcp_server_generator/tests/test_server.py -v

Test Statistics:

92+ comprehensive tests covering all functionality
All async MCP protocol tests passing
Progressive disclosure and discovery tools tests passing
Template validation tests passing

Requirements

Python ≥3.8
Jinja2 ≥3.0
hitoshura25-pypi-workflow-generator ==0.6.0

Development

See CONTRIBUTING.md for detailed development instructions.

Quick setup:

# Clone the repository
git clone https://github.com/hitoshura25/mcp-server-generator.git
cd mcp-server-generator

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run tests
pytest

Architecture

mcp-server-generator follows a dual-mode architecture pattern:

┌─────────────────────────────────────┐
│     mcp-server-generator            │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────┐      ┌──────────┐     │
│  │ MCP Mode │      │ CLI Mode │     │
│  └────┬─────┘      └────┬─────┘     │
│       │                 │           │
│       └────────┬────────┘           │
│                │                    │
│         ┌──────▼───────┐            │
│         │ generator.py │            │
│         │ (Core Logic) │            │
│         └──────────────┘            │
│                                     │
└─────────────────────────────────────┘

Both modes use the same core generator logic, ensuring consistency.

License

Apache-2.0

Author

Vinayak Menon

Acknowledgments

This project is based on patterns validated in pypi-workflow-generator, a production MCP server for generating GitHub Actions workflows.

Progressive disclosure implementation follows best practices from:

Anthropic's MCP Engineering Blog: Code Execution with MCP