# todo-mcp

A lightweight MCP server for task management. Backed by a single JSON file, no
database or external service. Built in the same style as the Harrier / OSINT-MCP
servers already in this machine.

## Tools

| Tool | Purpose | Mutates? |
| --- | --- | --- |
| `todo_add` | Create a task (title required; optional priority, due, tags, project, description) | yes |
| `todo_list` | List tasks with status/priority/project/tag filters + pagination | no |
| `todo_get` | Fetch one task by id | no |
| `todo_update` | Update any subset of a task's mutable fields | yes |
| `todo_toggle` | Flip a task between active and done | yes |
| `todo_delete` | Delete a task by id | yes (destructive) |
| `todo_clear` | Remove all completed tasks | yes (destructive) |
| `todo_stats` | Summary: totals, by status, by priority, by project | no |

Every tool accepts `format: "json"` (default) or `"markdown"`.

## Storage

State lives in a JSON document:

- Default: `~/.todo-mcp/todos.json`
- Override: set the `TODO_MCP_STORE` environment variable to another path.

Writes are atomic (temp file + rename) so a crash cannot corrupt the store.

## Run

```bash
uv run todo-mcp          # stdio MCP server
```

## Install into OpenCode

Add to `~/.config/opencode/opencode.jsonc` under `mcp.clients` (already done
here):

```jsonc
"todo-mcp": {
  "type": "local",
  "command": ["uv", "run", "--directory", "/home/jason/Documents/source/git-cloned/todo-mcp", "todo-mcp"],
  "enabled": true
}
```

After reloading OpenCode, the tools appear as `tools["todo-mcp"].todo_*`.

## Test

```bash
uv run pytest
```