MCP Framework

🚀 MCP Development Guide

This guide provides detailed instructions on developing, deploying, and configuring MCP tools, along with common issue solutions and reference materials.

🚀 Quick Start

Tool Template Example

import mcp.types as types
from . import BaseTool, ToolRegistry

@ToolRegistry.register
class YourTool(BaseTool):
    """Your tool description"""
    name = "your_tool_name"  # Unique identifier for the tool
    description = "Your tool description"  # Tool description to be shown to users
    input_schema = {
        "type": "object",
        "required": ["param1"],  # Required parameters
        "properties": {
            "param1": {
                "type": "string",
                "description": "Description of parameter 1",
            },
            "param2": {
                "type": "integer",
                "description": "Description of parameter 2 (optional)",
            }
        },
    }
  
    async def execute(self, arguments: dict) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
        """Execute tool logic"""
        # Parameter validation
        if "param1" not in arguments:
            return [types.TextContent(
                type="text",
                text="Error: Missing required argument 'param1'"
            )]
          
        # Get parameters
        param1 = arguments["param1"]
        param2 = arguments.get("param2", 0)  # Get optional parameter with default value
      
        # Execute tool logic
        result = f"Processing parameters: {param1}, {param2}"
      
        # Return result
        return [types.TextContent(
            type="text",
            text=result
        )]

📦 Installation

Docker Deployment (Recommended)

1. Initial Setup:

# Clone the repository
git clone https://github.com/your-username/mcp-framework.git
cd mcp-framework

# Create environment file
cp .env.example .env

2. Use Docker Compose:

# Build and start
docker compose up --build -d

# View logs
docker compose logs -f

# Manage containers
docker compose ps
docker compose pause
docker compose unpause
docker compose down

3. Access the Service:

• SSE Endpoint: http://localhost:8000/sse

4. Cursor IDE Configuration:

• Settings → Features → Add MCP Server
• Type: "sse"
• URL: http://localhost:8000/sse

Traditional Python Deployment

1. Install System Dependencies:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y poppler-utils tesseract-ocr tesseract-ocr-chi-sim

# macOS
brew install poppler tesseract tesseract-lang

# Windows
# 1. Download and install Tesseract: https://github.com/UB-Mannheim/tesseract/wiki
# 2. Add Tesseract to the system PATH

2. Install Python Dependencies:

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

3. Run the Service:

uvicorn mcp_server:app --reload

🛠️ Configuration

Environment Variables

The following are some commonly used environment variables:

• MCP_HOST: The host to which the service binds, default is 0.0.0.0.
• MCP_PORT: The port to which the service binds, default is 8000.
• MCP_DEBUG: Whether to enable debug mode, default is False.

Logging

By default, logs are output to the console. You can change the log output method by configuring the logging module.

💻 Tool Development

Tool Template

The following is a basic template for a tool:

from typing import Dict, Any
import mcp.types as types
from . import BaseTool, ToolRegistry

@ToolRegistry.register
class MyTool(BaseTool):
    name = "my_tool"
    description = "This is an example tool"

    async def execute(self, arguments: Dict[str, Any]) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
        # Implement logic here
        return []

Event Handling

You can extend functionality by subscribing to events:

from .events import EventManager

class MyEventListener:
    def on_event(self, event: str, data: Dict[str, Any]):
        if event == "my_event":
            print(f"Received custom event: {data}")

📚 Documentation

Frequently Asked Questions

1. How to debug the service?

   • Enable debug mode: MCP_DEBUG=True
   • Use the IDE's debugging feature

2. How to view logs?

   • By default, logs are output to the console
   • Configure the logging module to output to a file or database

3. How to handle errors?

   • Catch exceptions in the tool and return friendly error messages

References

• MCP Official Documentation
• Python Type Hints
• Uvicorn Documentation

Contact Information

If you have any questions, please contact support@mcp.com