# Todo List MCP Server

A small [Model Context Protocol](https://modelcontextprotocol.io) server that turns
a plain JSON file into a todo list an MCP-compatible client (Claude Desktop,
Claude Code, Cursor, etc.) can read and manage on your behalf.

## What it does

It exposes five tools and one resource:

| Tool | Description |
|---|---|
| `add_todo(text, priority)` | Add a new task. `priority` is `low`, `medium`, or `high`. |
| `list_todos(status)` | List tasks. `status` is `all`, `pending`, or `done`. |
| `complete_todo(todo_id)` | Mark a task as done. |
| `delete_todo(todo_id)` | Remove a task permanently. |
| `clear_completed()` | Remove every completed task in one call. |

| Resource | Description |
|---|---|
| `todos://all` | Read-only JSON dump of every todo. |

Data lives in `todos.json` next to `server.py`, so it survives restarts.

## Setup

```bash
# 1. Clone / copy this folder
cd todo-mcp

# 2. Create a virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 3. Run it directly to sanity-check it starts (Ctrl+C to stop)
python server.py
```

## Connect it to an MCP client

### Claude Desktop
Add this to your `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "todo-list": {
      "command": "/absolute/path/to/todo-mcp/venv/bin/python",
      "args": ["/absolute/path/to/todo-mcp/server.py"]
    }
  }
}
```

Restart Claude Desktop, and you'll see the todo tools available in the tool
picker (hammer icon). Try: *"Add 'finish MCP ticket' as a high priority
todo, then show me everything pending."*

### MCP Inspector (for local debugging)
```bash
npx @modelcontextprotocol/inspector python server.py
```
This opens a browser UI where you can call each tool manually and see the
raw JSON-RPC request/response — the best way to understand what's actually
crossing the wire between client and server.

## Deploying to Smithery

1. Push this folder to a public GitHub repo (needs `server.py`,
   `pyproject.toml`, `requirements.txt`, and `smithery.yaml`).
2. Go to [smithery.ai](https://smithery.ai) → **New Server** → connect your
   GitHub repo.
3. Smithery reads `smithery.yaml` to learn how to start the server
   (`python server.py` over stdio) and builds/deploys it automatically.
4. Once deployed, anyone can add it to their own MCP client straight from
   your Smithery listing page — no local setup required on their end.

## Notes on how it's built

Built with the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
using `FastMCP`, which turns plain Python functions into MCP tools via the
`@mcp.tool()` decorator — the type hints and docstring become the tool's
JSON schema and description automatically, which is what the client model
reads to decide when and how to call each tool.