Python MCP Server Development with Cursor Rules

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

License: MIT Python

🌟 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:

📋 Plan First - Update TODO.md with specific tasks
🔨 Implement One Thing - Build one component at a time
🧪 Test Immediately - Write and run tests before proceeding
✅ Verify - Ensure current step works completely
📝 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

Main Development Rules - Primary development guidelines
Global Standards - Universal development standards
File Server Rules - File operation specific guidelines
Database Server Rules - Database operation guidelines

Operational Guides

Deployment Guide - Production deployment procedures
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:

Use these rules in your own projects
Adapt the system to your specific needs
Share improvements through issues and discussions
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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

A comprehensive framework for building reliable Python MCP servers that enforces incremental development practices through Cursor Rules, featuring built-in security measures and a smart rule system.

Related MCP Servers

Lodestar MCP Server
kanlanc
-
security
F
license
-
quality
This is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.
Last updated -
Python REPL MCP Server
hdresearch
A
security
A
license
A
quality
A server that provides a persistent Python REPL environment through the MCP protocol, allowing execution of Python code, variable management, and package installation.
Last updated -
3
28
MIT License
MCP Server Python Template
Cris-0k
-
security
A
license
-
quality
A streamlined foundation for building Model Context Protocol servers in Python, designed to make AI-assisted development of MCP tools easier and more efficient.
Last updated -
14
MIT License
Python MCP Server Template
nictuku
A
security
A
license
A
quality
A template repository for creating custom Model Context Protocol (MCP) servers in Python that can be integrated with applications like Claude Desktop or Cursor.
Last updated -
3
5
MIT License

View all related MCP servers