Model Context Protocol Development Framework

A powerful development framework for creating custom tools that interact with large language models using the Model Context Protocol (MCP). This framework provides a comprehensive toolset to extend the functionality of the Cursor IDE, enabling advanced features like web content retrieval and file processing (PDF, Word, Excel).

Overview

The Model Context Protocol Development Framework is designed to simplify the creation of tools that interact with large language models. It offers a modular and extensible architecture, making it easy to add new functionalities and integrate with existing systems.

Core Features

1. Comprehensive File Processing

The file tool automatically identifies file types and selects the appropriate processing method. Supported formats include PDF, Word, and Excel.

• Usage: file /path/to/document
• Supported Formats:
• PDF files (.pdf)
• Word documents (.doc, .docx)
• Excel files (.xls, .xlsx, .xlsm)
• Parameters: file_path - The local path to the file
• Returns: Processed content based on the file type

2. PDF Document Processing

The pdf tool processes PDF documents with two modes:

• Usage: pdf /path/to/document.pdf [mode]
• Parameters:
• file_path - The local path to the PDF file
• mode - Processing mode (optional):
  • quick - Quick preview mode, extracts text only
  • full - Full parsing mode, extracts text and images (default)
• Returns:
• Quick preview mode: Text content
• Full parsing mode: Text and images
• Features:
• High-quality text extraction and image processing using PyMuPDF
• Automatic handling of large files
• Image extraction and saving

3. Word Document Parsing

The word tool parses Word documents to extract text, tables, and images.

• Usage: word /path/to/document.docx
• Features: Extracts text, tables, and images from Word documents
• Parameters: file_path - The local path to the Word document
• Returns: Text content, tables, and images
• Features: High-quality text and table extraction using python-docx

4. Excel File Processing

The excel tool parses Excel files to provide complete table data and structure information.

• Usage: excel /path/to/spreadsheet.xlsx
• Features: Parses all sheets in an Excel file
• Parameters: file_path - The local path to the Excel file
• Returns:
• File metadata (filename, number of sheets)
• Detailed information for each sheet:
  • Number of rows and columns
  • List of column names
  • Complete table data
• Features:
• High-quality table data processing using pandas and openpyxl
• Support for multiple sheets
• Automatic data type conversion

5. Web Content Retrieval

The url tool retrieves content from any web page.

• Usage: url https://example.com
• Parameters: url - The URL of the website to retrieve content from
• Returns: Text content of the web page
• Features:
• Comprehensive HTTP error handling
• Timeout management
• Automatic encoding handling

Technical Highlights

1. Smart File Type Recognition:
2. Automatically selects the appropriate processing tool based on file extension
3. Provides a unified file processing interface
4. Efficient Document Processing:
5. PDF processing: Supports quick preview and full parsing modes
6. Word processing: Accurately extracts text, tables, and images
7. Excel processing: Efficiently handles large table data
8. Memory Optimization:
9. Uses temporary files to manage large files
10. Automatically cleans up temporary resources
11. Processes large documents in chunks
12. Error Handling:
13. Comprehensive exception capture and handling
14. Detailed error feedback
15. Graceful failure handling mechanisms

Project Structure

The framework is modular and easy to maintain:

mcp_tool/
├── tools/
│   ├── __init__.py        # Defines tool base classes and registries
│   ├── loader.py          # Tool loader, automatically loads all tools
│   ├── file_tool.py       # Comprehensive file processing tool
│   ├── pdf_tool.py        # PDF parsing tool
│   ├── word_tool.py       # Word document parsing tool
│   ├── excel_tool.py      # Excel file processing tool
│   └── url_tool.py        # URL tool implementation
├── __init__.py
├── __main__.py
└── server.py              # MCP server implementation

Development Guide

How to Develop New Tools

1. Create a new Python file in the tools directory, e.g., your_tool.py
2. Import necessary dependencies and base classes
3. Create a tool class that inherits from BaseTool
4. Register the tool using the @ToolRegistry.register decorator
5. Implement the execute method for the tool

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"  # Description displayed 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"Processed parameters: {param1}, {param2}"

        # Return result
        return [types.TextContent(
            type="text",
            text=result
        )]

Deployment Guide

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

1. Using 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

1. Access the Service:

2. SSE endpoint: http://localhost:8000/sse

3. Cursor IDE Configuration:

4. Settings → Features → Add MCP Server

5. Type: "sse"
6. 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

1. 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

1. Start the Service:

python -m mcp_tool

Configuration

Environment Variables

Configure in the .env file:

• MCP_SERVER_PORT: Server port (default: 8000)
• MCP_SERVER_HOST: Binding address (default: 0.0.0.0)
• DEBUG: Debug mode (default: false)
• MCP_USER_AGENT: Custom User-Agent

Dependencies

Main dependencies:

• mcp: Model Context Protocol implementation
• PyMuPDF: PDF document processing
• python-docx: Word document processing
• pandas and openpyxl: Excel file processing
• httpx: Asynchronous HTTP client
• anyio: Asynchronous I/O support
• click: Command-line interface

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.