Python MCP Server Development with Cursor Rules

Python MCP Server Development with Cursor Rules

A comprehensive development framework for Python MCP servers with enforced incremental development practices

🌟 What This Is

This repository showcases a production-ready development framework for building Python MCP (Model Context Protocol) servers using Cursor Rules. The system enforces incremental development practices and provides comprehensive guidelines for building reliable, secure, and maintainable MCP servers.

🚀 Key Features

🎯 Enforced Incremental Development

• NEVER create multiple untested files at once
• Mandatory TODO.md and TASKS.md management
• Step-by-step development workflow
• Built-in quality gates

🔧 Comprehensive Tooling

• UV integration for modern Python dependency management
• Type checking with mypy
• Code formatting with black and isort
• Testing with pytest and pytest-asyncio
• Pre-commit hooks for quality assurance

🛡️ Security First

• File path validation and directory traversal protection
• SQL injection prevention
• Input sanitization and validation
• Comprehensive error handling

📋 Smart Rule System

• Auto-attached rules based on file location
• Manual rules for deployment and troubleshooting
• Always-active rules for global standards
• Context-aware development guidelines

📁 Repository Structure

python-mcp-development-framework/
├── .cursor/
│   └── rules/
│       ├── python_mcp_servers.mdc        # Main development rules
│       ├── global-standards.mdc          # Global standards
│       ├── file-server-rules.mdc         # File server specific rules
│       ├── database-server-rules.mdc     # Database server specific rules
│       ├── deployment-guide.mdc          # Deployment procedures
│       └── troubleshooting.mdc           # Troubleshooting guide
├── examples/
│   ├── file-server/                      # File server examples
│   └── db-server/                        # Database server examples
├── docs/                                 # Additional documentation
└── README.md                             # This file

🎯 Development Philosophy

The Incremental Approach

This framework is built around a strict incremental development methodology:

1. 📋 Plan First - Update TODO.md with specific tasks
2. 🔨 Implement One Thing - Build one component at a time
3. 🧪 Test Immediately - Write and run tests before proceeding
4. ✅ Verify - Ensure current step works completely
5. 📝 Document - Update progress and notes

Why This Matters

• Reduces bugs by catching issues early
• Improves code quality through focused development
• Enhances maintainability with clear progression
• Increases reliability through comprehensive testing
• Accelerates debugging with smaller change sets

🛠️ How the Rule System Works

Auto-Attached Rules

Rules automatically apply based on your file location:

# Working in file server? File server rules auto-apply
servers/file-server/main.py  → file-server-rules.mdc

# Working in database server? Database rules auto-apply
servers/db-server/main.py    → database-server-rules.mdc

Manual Rules

Call specific rules in Cursor chat when needed:

@deployment-guide    # Get deployment procedures
@troubleshooting     # Get debugging help

Always-Active Rules

Core development standards apply everywhere:

• Type hints are mandatory
• Error handling is required
• Tests must be written
• Documentation is enforced

🚀 Quick Start

1. Copy the Rules

# Copy the .cursor directory to your project
cp -r .cursor /path/to/your/mcp-project/

2. Initialize Your Project

# Initialize with UV
uv init your-mcp-project
cd your-mcp-project

# Add dependencies
uv add mcp fastapi uvicorn pydantic aiofiles
uv add --dev pytest pytest-asyncio black isort mypy ruff

3. Create Task Files

# Create required task management files
touch TODO.md TASKS.md

4. Start Development

The rules will automatically guide you through:

• Creating minimal implementations first
• Writing tests immediately
• Following security best practices
• Maintaining proper documentation

📊 Examples

File Server Example

# examples/file-server/main.py
from typing import Dict, Any
import aiofiles
import logging

logger = logging.getLogger(__name__)

async def read_file_tool(request: Dict[str, Any]) -> Dict[str, Any]:
    """Handle file read requests with security validation"""
    try:
        file_path = request.get("file_path")
        if not file_path:
            raise ValueError("file_path is required")
        
        # Security: Validate file path
        safe_path = validate_file_path(file_path)
        
        # Read file asynchronously
        async with aiofiles.open(safe_path, 'r') as f:
            content = await f.read()
        
        return {
            "status": "success",
            "data": {"content": content, "path": str(safe_path)}
        }
    except Exception as e:
        logger.error(f"File read error: {e}")
        return {"status": "error", "error": str(e)}

Database Server Example

# examples/db-server/main.py
from typing import Dict, Any
import aiosqlite
import logging

logger = logging.getLogger(__name__)

async def query_database_tool(request: Dict[str, Any]) -> Dict[str, Any]:
    """Handle database queries with SQL injection prevention"""
    try:
        table = request.get("table")
        if not table:
            raise ValueError("table is required")
        
        # Security: Validate table name
        if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', table):
            raise ValueError("Invalid table name")
        
        # Execute query safely
        async with aiosqlite.connect("database.db") as conn:
            async with conn.execute(f"SELECT * FROM {table} LIMIT 100") as cursor:
                rows = await cursor.fetchall()
                columns = [desc[0] for desc in cursor.description]
        
        return {
            "status": "success",
            "data": {"rows": rows, "columns": columns}
        }
    except Exception as e:
        logger.error(f"Database query error: {e}")
        return {"status": "error", "error": str(e)}

📚 Documentation

Core Rules

1. Main Development Rules - Primary development guidelines
2. Global Standards - Universal development standards
3. File Server Rules - File operation specific guidelines
4. Database Server Rules - Database operation guidelines

Operational Guides

1. Deployment Guide - Production deployment procedures
2. Troubleshooting - Debugging and problem resolution

🎯 Benefits

For Developers

• Faster development with clear guidelines
• Fewer bugs through incremental approach
• Better code quality with enforced standards
• Easier debugging with comprehensive logging

For Teams

• Consistent code style across projects
• Reduced onboarding time for new developers
• Better collaboration with clear practices
• Improved maintainability of codebases

For Projects

• Higher reliability through comprehensive testing
• Better security with built-in protections
• Easier deployment with detailed guides
• Faster troubleshooting with comprehensive documentation

🔄 Development Workflow Example

# TODO.md
## Current Sprint: File Server Basic Operations
- [ ] Implement file read functionality
- [ ] Add file write functionality
- [ ] Implement directory listing
- [ ] Add file metadata retrieval

## Next Sprint
- [ ] Add file streaming for large files
- [ ] Implement file caching

# TASKS.md
## Task: Implement File Read Functionality
**Status**: In Progress
**Priority**: High

### Subtasks:
1. [x] Create basic file read function
2. [x] Add path validation
3. [x] Write unit tests
4. [ ] Add error handling
5. [ ] Add logging

### Acceptance Criteria:
- [ ] Function can read text files
- [ ] Path validation prevents directory traversal
- [ ] All tests pass
- [ ] Proper error handling implemented
- [ ] Logging is comprehensive

🤝 Contributing

This showcase demonstrates best practices for MCP server development. Feel free to:

1. Use these rules in your own projects
2. Adapt the system to your specific needs
3. Share improvements through issues and discussions
4. Contribute examples for different use cases

📄 License

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

🙏 Acknowledgments

• Built for the Cursor AI IDE
• Designed for MCP (Model Context Protocol)
• Powered by UV for Python package management

Remember: The key to successful development is not speed, but consistency and quality. This framework helps you achieve both through disciplined, incremental development practices.

🚀 Ready to transform your MCP server development? Copy the .cursor directory to your project and start building better, faster, and more reliably!