nasarali03/todo-mcp-server

📝 To-Do API with MCP Server

🎯 Overview

This project is a comprehensive To-Do application built with FastAPI and integrated with MCP (Model Context Protocol) server capabilities. It provides both traditional REST API endpoints and modern MCP tool-based interactions for managing tasks.

🌟 Key Highlights

• Dual Interface: Both REST API and MCP server for maximum flexibility
• Modern Architecture: Built with FastAPI for high performance and automatic documentation
• Type Safety: Full Pydantic model validation
• Developer Friendly: Auto-generated API docs and comprehensive error handling
• CORS Ready: Configured for frontend integration
• Tool-Based Interactions: MCP server enables AI agent integration

🚀 Features

📋 Core Functionality

• ✅ Create new todo items with title and description
• 📖 Read all todos or individual items by ID
• ✏️ Update todo items (title, description, completion status)
• 🗑️ Delete todo items
• 📊 Summary Statistics with completion rates

🛠️ Technical Features

• REST API Endpoints for traditional web integration
• MCP Server Integration for AI agent interactions
• Auto-generated Documentation (Swagger UI & ReDoc)
• CORS Support for cross-origin requests
• Type Validation with Pydantic models
• Error Handling with proper HTTP status codes
• Health Check endpoint for monitoring

🎯 MCP Tools Available

• create_todo - Create new todo items
• list_todos - Get all todos
• get_todo - Get specific todo by ID
• update_todo - Update existing todos
• delete_todo - Remove todos
• todo_summary - Get statistics and completion rates

📦 Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)

Step 1: Clone the Repository

git clone <your-repo-url>
cd mcp

Step 2: Install Dependencies

pip install -r requirements.txt

Step 3: Run the Application

# Development server with auto-reload
uvicorn main:app --reload

# Or run directly
python main.py

🔧 Usage

🌐 Access Points

Once the server is running, you can access:

📡 REST API Examples

Create a Todo

curl -X POST "http://localhost:8000/todos/" \
     -H "Content-Type: application/json" \
     -d '{"title": "Learn FastAPI", "description": "Complete the FastAPI tutorial"}'

Get All Todos

curl -X GET "http://localhost:8000/todos/"

Update a Todo

curl -X PUT "http://localhost:8000/todos/1" \
     -H "Content-Type: application/json" \
     -d '{"completed": true}'

Delete a Todo

curl -X DELETE "http://localhost:8000/todos/1"

🤖 MCP Server Usage

List Available Tools

curl -X GET "http://localhost:8000/mcp/tools"

Use MCP Tools

# Create a todo via MCP
curl -X POST "http://localhost:8000/mcp/tools/create_todo" \
     -H "Content-Type: application/json" \
     -d '{"title": "MCP Todo", "description": "Created via MCP"}'

# Get todo summary
curl -X GET "http://localhost:8000/mcp/resources/todo_summary"

📚 API Documentation

📋 Todo Model

{
    "id": int,           # Unique identifier
    "title": str,        # Todo title (required)
    "description": str,  # Optional description
    "completed": bool,   # Completion status (default: false)
    "created_at": datetime  # Creation timestamp
}

🔗 Endpoints

REST API Endpoints

MCP Server Endpoints

🎥 Demo Video

🏗️ Project Structure

mcp/
├── 📁 routes/
│   ├── __pycache__/
│   └── todo.py              # Todo route handlers
├── 📄 main.py               # FastAPI application & MCP server
├── 📄 models.py             # Pydantic data models
├── 📄 requirements.txt      # Python dependencies
├── 📄 mcp_server.json       # MCP server configuration
├── 📄 todo-api-mcp-demo.mp4  # Demo video
├── 📄 README.md             # This file
└── 📄 LICENSE               # MIT License

🛠️ Development

🔧 Configuration

The application uses the following configuration:

• Host: 0.0.0.0 (all interfaces)
• Port: 8000
• Auto-reload: Enabled in development
• CORS: Configured for all origins (adjust for production)

📝 Adding New Features

1. New API Endpoints: Add to routes/todo.py
2. New MCP Tools: Add to main.py with @mcp.tool() decorator
3. New Models: Add to models.py
4. Dependencies: Update requirements.txt

🧪 Testing

# Test the API endpoints
curl -X GET "http://localhost:8000/health"

# Test MCP server
curl -X GET "http://localhost:8000/mcp/"

🤝 Contributing

We welcome contributions! Here's how you can help:

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

📋 Contribution Guidelines

• Follow PEP 8 style guidelines
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass

📄 License

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

👨‍💻 Author

Nasar Ali

• GitHub: @nasarali
• Project: To-Do API with MCP Server
• Video:

🙏 Acknowledgments

• FastAPI - The modern, fast web framework for building APIs
• Pydantic - Data validation using Python type annotations
• MCP Protocol - Model Context Protocol for AI agent integration
• Uvicorn - Lightning-fast ASGI server

📞 Support

If you have any questions or need help:

1. Check the API Documentation
2. Watch the
3. Open an issue on GitHub
4. Contact the author