README.md•2.34 kB
## 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](https://pipenv.pypa.io/) or `venv` for virtual environments
- An OpenAI API key
---
### Installation
1. Clone the repo:
```bash
git clone https://github.com/oseni99/todo-mcp
cd todo-mcp
```
2. Create and activate a virtual environment:
```bash
python3 -m venv .venv
source .venv/bin/activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. Create a `.env` in the project root:
```ini
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
```bash
fastapi dev server/main.py
```
- Visit [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) for interactive API docs.
---
### Running the CLI
From the project root:
```bash
python -m client.cli
```
Type natural language commands at the prompt, for example:
```text
> 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.
---