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

├── src/
│   ├── index.ts            # CLI entrypoint, server creation, transport wiring
│   ├── tools.ts            # Tool registration and handler logic
│   ├── storage.ts          # JSON file storage with locking and caching
│   ├── schema.ts           # Zod input/output schemas
│   ├── responses.ts        # createToolResponse / createErrorResponse helpers
│   ├── diagnostics.ts      # node:diagnostics_channel publishers
│   ├── requestContext.ts   # AsyncLocalStorage request context
│   ├── constants.ts        # Error name/code constants
│   └── instructions.md     # Server instructions resource
├── tests/                  # node:test test files
├── scripts/
│   └── tasks.mjs           # Build orchestration
├── assets/
│   └── logo.svg            # Server icon
├── .github/
│   └── workflows/
│       └── publish.yml     # CI/CD: npm publish on release
├── package.json
├── tsconfig.json
└── eslint.config.mjs

Requirements

• Node.js ≥ 24

• npm (included with Node.js)

Quickstart

Run with npx — no installation needed:

npx -y @j0hanz/todokit-mcp@latest

Add to your MCP client configuration:

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

Installation

NPX (recommended)

npx -y @j0hanz/todokit-mcp@latest

Global Install

npm install -g @j0hanz/todokit-mcp
todokit-mcp

From Source

git clone https://github.com/j0hanz/todokit-mcp-server.git
cd todokit-mcp-server
npm ci
npm run build
node dist/index.js

Configuration

CLI Arguments

Environment Variables

Usage

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

# With npx
npx -y @j0hanz/todokit-mcp@latest

# With custom todo file
npx -y @j0hanz/todokit-mcp@latest --todo-file ./my-tasks.json

# With diagnostics enabled
npx -y @j0hanz/todokit-mcp@latest --diagnostics --log-level debug

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.

{
  "ok": true,
  "result": {
    "item": {
      "id": "a1b2c3",
      "description": "Review PR #42",
      "completed": false,
      "priority": "high",
      "category": "work",
      "createdAt": "2026-02-10T12:00:00.000Z"
    },
    "summary": "Added todo",
    "nextActions": ["list_todos", "update_todo", "complete_todo"]
  }
}

add_todos

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

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

{
  "ok": true,
  "result": {
    "count": 3,
    "ids": ["id1", "id2", "id3"],
    "summary": "Added 3 todos",
    "nextActions": ["list_todos", "update_todo"]
  }
}

list_todos

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

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

{
  "ok": true,
  "result": {
    "items": [],
    "summary": "Showing 5 pending todos (Found 10 todos (5 pending, 5 completed))",
    "counts": { "total": 10, "pending": 5, "completed": 5 },
    "filteredCounts": { "total": 5, "pending": 5, "completed": 0 },
    "status": "pending",
    "returned": 5,
    "truncated": false,
    "remaining": 0,
    "hint": "Tip: when all todos are completed, the storage file is automatically deleted.",
    "limit": 50,
    "hasMore": false
  }
}

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.

{
  "ok": true,
  "result": {
    "items": [],
    "query": "review",
    "status": "pending",
    "summary": "Found 2 matches for \"review\" (pending)",
    "returned": 2,
    "totalMatches": 2,
    "remaining": 0,
    "limit": 50,
    "hasMore": false,
    "nextActions": ["update_todo", "complete_todo"]
  }
}

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.

{
  "ok": true,
  "result": {
    "item": {
      "id": "a1b2c3",
      "description": "Updated task",
      "completed": false,
      "priority": "medium",
      "category": "work",
      "createdAt": "...",
      "updatedAt": "..."
    },
    "summary": "Updated todo",
    "nextActions": ["list_todos", "complete_todo"]
  }
}

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.

{
  "ok": true,
  "result": {
    "item": {
      "id": "a1b2c3",
      "completed": true,
      "completedAt": "2026-02-10T14:00:00.000Z"
    },
    "summary": "Completed todo",
    "nextActions": ["list_todos"]
  }
}

delete_todo

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

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

{
  "ok": true,
  "result": {
    "deletedIds": ["a1b2c3"],
    "summary": "Deleted todo",
    "nextActions": ["list_todos"]
  }
}

Resources

Prompts

Client Configuration Examples

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

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

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

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

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

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

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

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

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

npm ci

Scripts

Full Validation

npm run format && npm run lint && npm run type-check && npm run build && npm test

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:

npx @modelcontextprotocol/inspector node dist/index.js

Or if installed from npm:

npx @modelcontextprotocol/inspector npx -y @j0hanz/todokit-mcp@latest

Common Issues

Diagnostics

Enable detailed logging to stderr:

npx -y @j0hanz/todokit-mcp@latest --diagnostics --log-level debug

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:

npm run format && npm run lint && npm run type-check && npm run build && npm test

License

MIT