TODO MCP Server

TODO MCP CLI & Server

This repository contains a minimal Model Context Protocol (MCP) implementation for a to-do list application, including:

• FastAPI server (server/): exposes a /tools endpoint for tool discovery and an /rpc endpoint for JSON-RPC calls to perform operations on tasks.
• CLI client (client/cli.py): a Python command-line interface that interacts with an LLM (via OpenAI) and the MCP server to create, list, and complete tasks using function calls.

Features

• Add tasks with title, content, and optional due date
• List all tasks
• Mark tasks as completed
• Server-side task ID generation
• JSON-RPC 2.0 compliance for tool invocation

Prerequisites

• Python 3.10+
• pipenv or venv for virtual environments
• An OpenAI API key

Installation

1. Clone the repo:

   git clone https://github.com/oseni99/todo-mcp
   cd todo-mcp
   

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Create a .env in the project root:

   OPENAI_API_KEY=sk-...
   MCP_SERVER=http://127.0.0.1:8000
   

Directory Structure

todoMCP/
├── client/        # CLI client code
│   └── cli.py     # Main entrypoint for the MCP-CLI
├── server/        # FastAPI server code
│   ├── handlers.py    # Business logic for add, list, complete
│   ├── tools.py       # JSON-Schema tool manifest
│   └── main.py        # FastAPI app with /tools and /rpc
├── .env           # Environment variables (not committed)
├── requirements.txt   # Python dependencies
└── README.md      # This file

Running the Server

fastapi dev server/main.py

• Visit http://127.0.0.1:8000/docs for interactive API docs.

Running the CLI

From the project root:

python -m client.cli

Type natural language commands at the prompt, for example:

> Create a task titled "Write blog post" with content "Outline first draft" due 2025-05-20
> List my tasks
> Mark the first task as done
> Thanks!
> exit

The CLI will print tool invocations and LLM responses.