Todoist MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a TypeScript-based Model Context Protocol (MCP) server that provides CRUD operations for Todoist tasks and projects. The server connects to the Todoist API and exposes tools through the MCP protocol to Claude Desktop. ## Architecture - **Single-file architecture**: All server logic is contained in `src/index.ts` - **Class-based design**: `TodoistMCPServer` class handles all MCP server functionality - **Tool registration pattern**: Tools are registered using the MCP SDK's `registerTool` method - **API client**: Uses the official `@doist/todoist-api-typescript` client library - **Schema validation**: Uses Zod for input validation and type safety ## Development Commands ```bash # Build TypeScript to JavaScript npm run build # Start the server (requires build first) npm start # Build and start in one command npm run dev # Watch mode for development (auto-rebuild on changes) npm run watch ``` ## Environment Requirements - Requires `TODOIST_API_TOKEN` environment variable to be set - The server will exit with error code 1 if the token is missing - Token can be obtained from Todoist Integrations settings ## Tool Structure The server implements 15 MCP tools divided into three categories: ### Project Tools (5) - `create_project` - Create new projects - `get_project` - Get project by ID - `list_projects` - List all projects - `update_project` - Update project properties - `delete_project` - Delete projects ### Task Tools (5) - `create_task` - Create new tasks - `get_task` - Get task by ID - `list_tasks` - List tasks with optional filters - `update_task` - Update task properties - `complete_task` - Mark tasks as completed - `reopen_task` - Reopen completed tasks - `delete_task` - Delete tasks ### Subtask Tools (5) - `get_subtasks` - Get all subtasks for a parent task - `add_subtask` - Create a new subtask under a parent task - `move_task_to_subtask` - Move an existing task to become a subtask - `promote_subtask` - Promote a subtask to become a top-level task - `get_task_hierarchy` - Get the complete hierarchy for a task ## Error Handling Pattern All tools follow a consistent error handling pattern: - Wrap API calls in try-catch blocks - Return structured responses with `content` array - Set `isError: true` for error responses - Include error details in response text ## Configuration Notes The server uses ES modules (`"type": "module"`) and compiles to the `build/` directory. The main entry point is `build/index.js`, which can be used directly with Node.js or through the `todoist-mcp-server` CLI command after linking. ## Dependencies - `@modelcontextprotocol/sdk` - Core MCP SDK - `@doist/todoist-api-typescript` - Official Todoist API client - `zod` - Runtime type checking and validation