todo-mcp/README.md

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

uv run todo-mcp          # stdio MCP server

Install into OpenCode

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

"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

uv run pytest