Python MCP Server Development Framework

# Python MCP Server Development with Cursor Rules > **A comprehensive development framework for Python MCP servers with enforced incremental development practices** [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://docs.astral.sh/uv/) ## 🌟 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: ```bash # 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 ```bash # Copy the .cursor directory to your project cp -r .cursor /path/to/your/mcp-project/ ``` ### 2. Initialize Your Project ```bash # 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 ```bash # 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 ```python # 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 ```python # 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](/.cursor/rules/python_mcp_servers.mdc)** - Primary development guidelines 2. **[Global Standards](/.cursor/rules/global-standards.mdc)** - Universal development standards 3. **[File Server Rules](/.cursor/rules/file-server-rules.mdc)** - File operation specific guidelines 4. **[Database Server Rules](/.cursor/rules/database-server-rules.mdc)** - Database operation guidelines ### Operational Guides 1. **[Deployment Guide](/.cursor/rules/deployment-guide.mdc)** - Production deployment procedures 2. **[Troubleshooting](/.cursor/rules/troubleshooting.mdc)** - 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 ```markdown # 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 ``` ```markdown # 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](LICENSE) file for details. ## 🙏 Acknowledgments - Built for the [Cursor AI IDE](https://cursor.sh/) - Designed for [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) - Powered by [UV](https://docs.astral.sh/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!**