Todokit-MCP

!npm version !License !Node

 


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

``text
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

$3

`bash
npx -y @j0hanz/todokit-mcp@latest
`

Configuration

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

$3

| 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. |

$3

| 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

$3

| 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. |

$3

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

Client Configuration Examples

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

1. Install Dependencies

`bash
npm install
`

2. 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