@j0hanz/todokit-mcp

Todokit-MCP

An MCP server for Todokit, a task management and productivity tool with JSON storage.

Overview

Todokit MCP provides a lightweight, local task management system that integrates directly with your AI coding assistant. It uses a simple JSON file for persistence, allowing you to create, track, and complete tasks without leaving your editor. The server automatically handles file safety, locking, and atomic writes.

Key Features

• Local Persistence: Stores tasks in a human-readable todos.json file in your working directory.
• Task Management: Create, update, complete, and delete tasks with priorities and categories.
• Batch Operations: Add multiple tasks efficiently in a single operation.
• Filtering: List tasks by status (pending/completed) to keep context manageable.
• Safety Controls: Validates file paths to prevent traversal outside the working directory (unless configured).
• Diagnostics: emitting events for tool calls, storage operations, and lifecycle events.

Tech Stack

• Runtime: Node.js >=22.19.8
• Language: TypeScript 5.9
• SDK: Model Context Protocol SDK (@modelcontextprotocol/sdk)
• Libraries: Zod (validation)

Repository Structure

c:\todokit-mcp
├── dist/            # Compiled output
├── scripts/         # Build and task scripts
├── src/
│   ├── index.ts     # Server entrypoint & startup
│   ├── schema.ts    # Zod schemas for tools & types
│   ├── storage.ts   # JSON file persistence layer
│   └── tools.ts     # Tool registration & handlers
├── package.json
└── README.md

Requirements

• Node.js >=22.19.8

Quickstart

NPX (Recommended)

npx -y @j0hanz/todokit-mcp@latest

Configuration

The server can be configured via CLI arguments or environment variables.

CLI Arguments

Flag	Short	Description
--todo-file	-f	Path to the todo JSON file.
--diagnostics	-d	Enable diagnostic logging to stderr.
--log-level	-l	Set log level (error, warn, info, debug). Default: info.

Environment Variables

Variable	Description	Default
TODOKIT_TODO_FILE	Absolute or relative path to the todo storage file.	todos.json (in CWD)
TODOKIT_JSON_PRETTY	Set to true or 1 to indent JSON files with 2 spaces.	false (compact)
TODOKIT_TOOL_TIMEOUT_MS	Timeout for tool execution in milliseconds.	60000
TODOKIT_LOCK_TIMEOUT_MS	Timeout for acquiring file lock.	5000
TODOKIT_MAX_TODO_FILE_BYTES	Maximum allowed size of the todo file.	5242880 (5MB)
TODOKIT_ALLOW_OUTSIDE_CWD	Allow storage file to be outside the current working directory.	false

MCP Surface

Tools

Tool	Description	Parameters	Results
add_todo	Create a new task.	description (str, req), priority (enum, req), category (enum, req), dueAt (iso-date, opt)	Returns the created item and summary.
add_todos	Create multiple tasks in batch.	items (array of todos, req, max 50)	Returns count and IDs of created items.
list_todos	List tasks with optional filtering.	status (pending/completed/all, opt, def: pending)	Returns list of items, counts, and status summary.
update_todo	Update an existing task.	id (str, req), description, priority, category, dueAt (all opt)	Returns updated item.
complete_todo	Mark a task as completed.	id (str, req)	Returns updated item.
delete_todo	Permanently remove a task.	id (str, req)	Returns summary of deletion.

Resources

URI Template	Type	Description
internal://instructions	text/markdown	Returns usage instructions and context about the Todokit manager.

Client Configuration Examples

VS Code

Add to your settings.json (Code) or mcpServers configuration:

{
  "todokit": {
    "command": "npx",
    "args": ["-y", "@j0hanz/todokit-mcp@latest"]
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "todokit": {
      "command": "npx",
      "args": ["-y", "@j0hanz/todokit-mcp@latest"]
    }
  }
}

Cursor

• Open Cursor Settings > Features > MCP
• Click + Add New MCP Server
• Name: todokit
• Type: command
• Command: npx -y @j0hanz/todokit-mcp@latest

Security

• Path Traversal: By default, the server enforces that the todos.json file must reside within the current working directory. You must explicitly opt-in via TODOKIT_ALLOW_OUTSIDE_CWD to store files elsewhere.
• File Limits: The server enforces a maximum file size (default 5MB) to prevent disk exhaustion.

Development Workflow

• Install Dependencies

  npm install
  

• Common Scripts

  Script	Description
  npm run build	Builds the project to dist/.
  npm run dev	Watches for changes and recompiles.
  npm run test	Runs the test suite via Node test runner.
  npm run lint	Lints code with ESLint.
  npm run format	Formats code with Prettier.
  npm run inspector	Launches the MCP inspector for debugging.

Troubleshooting

• Server Error: Server not initialized: This typically happens if tools are called before the server has fully started. Ensure the client waits for initialization.
• Storage Error: path outside CWD: You are trying to use a file outside the workspace. Move the file or set TODOKIT_ALLOW_OUTSIDE_CWD=1.

License

MIT