AgentSkillsCN

python-mcp-server-generator

使用工具、资源与恰当配置，以Python语言生成完整的MCP服务器项目。在从零开始搭建新MCP服务器时使用此功能。

SKILL.md
--- frontmatter
name: python-mcp-server-generator
description: Generate a complete MCP server project in Python with tools, resources, and proper configuration. Use when scaffolding a new MCP server from scratch.
argument-hint: "server-name"

Generate Python MCP Server

Create a complete Model Context Protocol (MCP) server in Python with the following specifications:

Requirements

  1. •Project Structure: Create a new Python project with proper structure using uv
  2. •Dependencies: Include mcp[cli] package with uv
  3. •Transport Type: Choose between stdio (for local) or streamable-http (for remote)
  4. •Tools: Create at least one useful tool with proper type hints
  5. •Error Handling: Include comprehensive error handling and validation

Implementation Details

Project Setup

  • •Initialize with uv init project-name
  • •Add MCP SDK: uv add "mcp[cli]"
  • •Create main server file (e.g., server.py)
  • •Add .localdocs for Python projects
  • •Configure for direct execution with if __name__ == "__main__"

Server Configuration

  • •Use FastMCP class from mcp.server.fastmcp
  • •Set server name and optional instructions
  • •Choose transport: stdio (default) or streamable-http
  • •For HTTP: optionally configure host, port, and stateless mode

Tool Implementation

  • •Use @mcp.tool() decorator on functions
  • •Always include type hints - they generate schemas automatically
  • •Write clear docstrings - they become tool descriptions
  • •Use Pydantic models or TypedDicts for structured outputs
  • •Support async operations for I/O-bound tasks
  • •Include proper error handling

Resource/Prompt Setup (Optional)

  • •Add resources with @mcp.resource() decorator
  • •Use URI templates for dynamic resources: "resource://{param}"
  • •Add prompts with @mcp.prompt() decorator
  • •Return strings or Message lists from prompts

Code Quality

  • •Use type hints for all function parameters and returns
  • •Write docstrings for tools, resources, and prompts
  • •Follow PEP 8 style guidelines
  • •Use async/await for asynchronous operations
  • •Implement context managers for resource cleanup
  • •Add inline comments for complex logic

Example Tool Types to Consider

  • •Data processing and transformation
  • •File system operations (read, analyze, search)
  • •External API integrations
  • •Database queries
  • •Text analysis or generation (with sampling)
  • •System information retrieval
  • •Math or scientific calculations

Configuration Options

  • •

    For stdio Servers:

    • •Simple direct execution
    • •Test with uv run mcp dev server.py
    • •Install to Claude: uv run mcp install server.py
  • •

    For HTTP Servers:

    • •Port configuration via environment variables
    • •Stateless mode for scalability: stateless_http=True
    • •JSON response mode: json_response=True
    • •CORS configuration for browser clients
    • •Mounting to existing ASGI servers (Starlette/FastAPI)

Testing Guidance

  • •Explain how to run the server:
    • •stdio: python server.py or uv run server.py
    • •HTTP: python server.py then connect to http://localhost:PORT/mcp
  • •Test with MCP Inspector: uv run mcp dev server.py
  • •Install to Claude Desktop: uv run mcp install server.py
  • •Include example tool invocations
  • •Add troubleshooting tips

Best Practices

  • •Use type hints everywhere - they're not optional
  • •Return structured data when possible
  • •Log to stderr (or use Context logging) to avoid stdout pollution
  • •Clean up resources properly
  • •Validate inputs early
  • •Provide clear error messages
  • •Test tools independently before LLM integration

Generate a complete, production-ready MCP server with type safety, proper error handling, and comprehensive documentation.