# Todo MCP Server

A small MCP (Model Context Protocol) server for managing todos, so an assistant like Claude can create, update and query your task list through a normal conversation. Written in TypeScript, stores everything in a local SQLite file.

I built this mostly to learn how MCP works end to end - tools, resources and prompts - and a todo manager was a simple enough domain to actually finish.

## What it exposes

**Tools** (the things Claude can call): create, update, delete, complete, list, and search todos, plus a stats tool.

**Resources** (read-only data Claude can pull): all / completed / pending / overdue todos, a single todo by id, todos filtered by priority or tag, and overall stats. A couple of them support autocomplete.

**Prompts** (canned flows): daily review, weekly planning, productivity analysis and task breakdown.

## Setup

```bash
npm install
npm run build
```

## Running

```bash
npm start        # run the server (talks over stdio)
npm run dev      # watch mode while developing
npm test         # run the test script against an in-memory db
```

To poke at it without Claude, the MCP inspector is handy:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Hooking it into Claude Desktop

Drop this into your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "todo-manager": {
      "command": "node",
      "args": ["/path/to/todo-mcp-server/dist/index.js"],
      "env": {
        "TODO_DB_PATH": "/path/to/your/todos.db"
      }
    }
  }
}
```

`TODO_DB_PATH` is optional - defaults to `todos.db` in the working directory.

## How it's laid out

```
src/
├── database.ts       # sqlite layer (better-sqlite3)
├── todo-service.ts   # validation + business logic
├── mcp-server.ts     # wires the service up to MCP tools/resources/prompts
├── index.ts          # entry point
├── types.ts          # shared types
└── test.ts           # quick sanity test
```

The `todos` table keeps id, title, description, completed, priority, due_date, tags and timestamps, with a few indexes on the columns I actually filter by.

## License

MIT