Todokit MCP Server

A local, persistent task management MCP server with JSON file storage, cursor pagination, and diagnostics.

Overview

Todokit is a Model Context Protocol (MCP) server that gives AI assistants the ability to manage a structured todo list. Tasks are persisted as a JSON file on disk with atomic writes and file-based locking, so data integrity is maintained even under concurrent access. The server communicates over stdio transport and exposes 7 tools, 2 resources, and 1 prompt for complete task lifecycle management.

Key Features

• Full task lifecycle — create, list, search, update, complete, and delete todos

• Batch operations — add up to 50 tasks in a single call

• Cursor-based pagination — efficiently navigate large task lists (up to 100 items per page)

• Fuzzy search — find tasks by description or category text

• Atomic file writes — data integrity with temp-file-then-rename strategy and file-based locking

• Resource subscriptions — live todo://list resource with change notifications

Tech Stack

Architecture

1. CLI Entrypoint (src/index.ts) — Parses CLI args, wires the McpServer to a StdioServerTransport, registers signal handlers for graceful shutdown.

2. Tool Layer (src/tools.ts) — Registers 7 tools with timeout/abort/diagnostics wrappers and cursor-based pagination.

3. Storage Layer (src/storage.ts) — Port/Adapter pattern (FileSystemPort, LockPort) for atomic JSON file reads/writes with in-memory caching and mtime-based invalidation.

4. Schema Layer (src/schema.ts) — Zod strict schemas for all tool inputs and outputs.

5. Diagnostics (src/diagnostics.ts) — Publishes events on todokit:tool, todokit:storage, and todokit:lifecycle channels.

6. Request Context (src/requestContext.ts) — AsyncLocalStorage-based correlation of tool calls with storage events.

Repository Structure

Requirements

• Node.js ≥ 24

• npm (included with Node.js)

Quickstart

Run with npx — no installation needed:

Add to your MCP client configuration:

Installation

NPX (recommended)

Global Install

From Source

Configuration

CLI Arguments

Environment Variables

Usage

Todokit uses stdio transport. Start the server and communicate via JSON-RPC over stdin/stdout:

MCP Surface

Tools

add_todo

Create a single task. For multiple items, prefer add_todos.

Returns: The created todo item with id, timestamps, and suggested next actions.

add_todos

Create multiple tasks in one batch call (1–50 items).

Returns: Count of created items, their IDs, and suggested next actions.

list_todos

List todos with optional status filtering and cursor-based pagination.

Returns: Filtered todo items with counts, pagination info, and hints.

search_todos

Search todos by description or category text with status filtering and pagination.

Returns: Matching items with match count, pagination info, and suggested next actions.

update_todo

Update one or more fields on an existing todo.

At least one field besides id must be provided.

Returns: The updated todo item and suggested next actions.

complete_todo

Mark a todo as completed. Idempotent — completing an already-completed todo returns success with an informational summary.

Returns: The completed todo item with completedAt timestamp.

delete_todo

Permanently delete a todo by ID. Destructive — cannot be undone.

Returns: The deleted todo's ID and suggested next actions.

Resources

Prompts

Client Configuration Examples

Add to your VS Code settings (settings.json) or use the one-click install buttons above:

Add to your Claude Desktop config file (claude_desktop_config.json):

Add to your Cursor MCP config (.cursor/mcp.json), or use the one-click install button above:

Add to your Windsurf MCP config (~/.windsurf/mcp.json):

Security

• stdout safety — The server never writes non-MCP output to stdout. All logging goes to stderr via console.error(), preserving JSON-RPC transport integrity.

• Path traversal protection — The todo file must reside within the current working directory by default. Set TODOKIT_ALLOW_OUTSIDE_CWD to override. Symlink resolution is performed to prevent escaping via symlinks.

• File locking — Concurrent access is protected by file-based locks with exponential backoff and timingSafeEqual ownership verification.

• Atomic writes — Data is written to a temporary file first, then atomically renamed to prevent corruption on partial writes.

• Size limits — The todo file is capped at 5 MB by default (TODOKIT_MAX_TODO_FILE_BYTES) to prevent unbounded growth.

Development Workflow

Install Dependencies

Scripts

Full Validation

Build and Release

The project uses GitHub Actions for CI/CD. On a GitHub Release event:

1. Checks out the repository

2. Sets up Node.js 24 with the npm registry

3. Installs dependencies (npm ci)

4. Runs lint, type-check, tests, coverage, and duplication checks

5. Builds the package

6. Publishes to npm using Trusted Publishing (OIDC — no NODE_AUTH_TOKEN needed)

Published package: @j0hanz/todokit-mcp

Troubleshooting

Inspect the Server

Use the MCP Inspector to interactively test tools:

Or if installed from npm:

Common Issues

Diagnostics

Enable detailed logging to stderr:

This publishes events on node:diagnostics_channel channels: todokit:tool, todokit:storage, todokit:lifecycle.

Contributing

Contributions are welcome! Please ensure all changes pass the full validation sequence:

License

MIT