simongrevin/todo-mcp-server

Project Documentation: Todo App with FastAPI & MCP Server

Features

• RESTful Todo API with FastAPI
• Data persistence using todos.json
• MCP server (todo_mcp_server.py) proxies all operations to FastAPI
• Minimalist web UI (index.html, app.js, style.css)
• Docker support for easy sharing and deployment

How Data Persistence Works

• Todos are stored in todos.json
• FastAPI loads todos at startup and saves after every change
• MCP server and web UI interact with FastAPI, so all data is consistent

How to Run and Test

1. Install dependencies

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt

For MCP server:

uv pip install -r requirements-mcp.txt

Or, using Docker (recommended for sharing):

docker build -t todo-mcp-server .
docker run -i --rm -e FASTAPI_URL=http://host.docker.internal:8000/todos todo-mcp-server

2. Start the FastAPI server

uvicorn todo_app:app --reload

3. (Optional) Start the MCP server (in another terminal)

uv run todo_mcp_server.py

4. Test the API with curl

• List todos:

  curl -X GET http://127.0.0.1:8000/todos
  

• Add a todo:

  curl -X POST http://127.0.0.1:8000/todos \
    -H "Content-Type: application/json" \
    -d '{"id": 1, "title": "Buy milk", "completed": false}'
  

• Update a todo:

  curl -X PUT http://127.0.0.1:8000/todos/1 \
    -H "Content-Type: application/json" \
    -d '{"id": 1, "title": "Buy milk and bread", "completed": true}'
  

• Delete a todo:

  curl -X DELETE http://127.0.0.1:8000/todos/1
  

5. Test the web UI

• Open index.html in your browser (with FastAPI server running)

6. Test the MCP server in VS Code

• See README_MCP.md for VS Code MCP setup and usage, including Docker configuration with the -i flag.

All todos are persisted in todos.json. Stopping and restarting the server will keep your data.