Todoist MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Build and Development Commands - `npm run build` - Compiles TypeScript to JavaScript in the dist/ directory - `npm run prepare` - Runs build (used by npm automatically) - `npm run watch` - Watches for TypeScript changes and rebuilds automatically - `npm run lint` - Lints TypeScript files with ESLint - `npm run lint:fix` - Auto-fixes linting issues - `npm run format` - Formats code with Prettier - `npm run format:check` - Checks code formatting - `npm run test` - Runs Jest test suite - `npm run test:watch` - Runs tests in watch mode - `npm run test:coverage` - Runs tests with coverage report ## Architecture This is an MCP (Model Context Protocol) server that integrates Claude with the Todoist API. The codebase has been modularized into a well-structured architecture. ### Key Components - **MCP Server**: Uses `@modelcontextprotocol/sdk` for MCP protocol implementation - **Todoist Integration**: Uses `@doist/todoist-api-typescript` client library - **Transport**: Runs on stdio transport for communication with MCP clients ### Modular Architecture The codebase follows a clean, domain-driven architecture with focused modules for improved maintainability: #### Core Infrastructure - **`src/index.ts`**: Main server entry point with request routing - **`src/types.ts`**: TypeScript type definitions and interfaces - **`src/type-guards.ts`**: Runtime type validation functions - **`src/errors.ts`**: Custom error types with structured error handling - **`src/validation.ts`**: Input validation and sanitization - **`src/cache.ts`**: Simple in-memory caching for API optimization #### Modular Tool Organization - **`src/tools/`**: Domain-specific MCP tool definitions (refactored from single 863-line file): - `task-tools.ts` - Task management tools (CREATE, READ, UPDATE, DELETE, COMPLETE + bulk operations) - `subtask-tools.ts` - Subtask management tools (hierarchical task operations) - `project-tools.ts` - Project and section management tools - `comment-tools.ts` - Comment creation and retrieval tools - `label-tools.ts` - Label CRUD and statistics tools - `test-tools.ts` - Testing and validation tools - `index.ts` - Centralized exports with backward compatibility #### Business Logic Handlers - **`src/handlers/`**: Domain-separated business logic: - `task-handlers.ts` - Task CRUD operations and bulk operations - `subtask-handlers.ts` - Hierarchical task management and parent-child relationships - `project-handlers.ts` - Project and section operations - `comment-handlers.ts` - Comment creation and retrieval operations - `label-handlers.ts` - Label CRUD operations and usage statistics - `test-handlers.ts` - Testing infrastructure for API validation and performance monitoring #### Enhanced Testing Framework - **`src/handlers/test-handlers-enhanced/`**: Modular comprehensive testing (refactored from single 755-line file): - `types.ts` - Common test types and utilities - `task-tests.ts` - Task CRUD operation tests (5 tests) - `subtask-tests.ts` - Subtask management tests (4 tests) - `label-tests.ts` - Label operation tests (5 tests) - `bulk-tests.ts` - Bulk operation tests (4 tests) - `index.ts` - Test orchestrator and exports #### Utility Modules - **`src/utils/`**: Shared utility functions: - `api-helpers.ts` - API response handling and formatting utilities - `error-handling.ts` - Centralized error management with context tracking - `dry-run-wrapper.ts` - Dry-run mode implementation for safe testing and validation ### Tool Architecture The server exposes 28 tools organized by entity type with standardized naming convention using underscores (MCP-compliant): **Task Management:** - `todoist_task_create` - Creates new tasks with full attribute support - `todoist_task_get` - Retrieves and filters tasks (with caching) - `todoist_task_update` - Updates existing tasks found by name search - `todoist_task_delete` - Deletes tasks found by name search - `todoist_task_complete` - Marks tasks as complete found by name search **Subtask Management:** - `todoist_subtask_create` - Creates subtasks under parent tasks with full attribute support - `todoist_subtasks_bulk_create` - Creates multiple subtasks under a parent task efficiently - `todoist_task_convert_to_subtask` - Converts existing tasks to subtasks of another task - `todoist_subtask_promote` - Promotes subtasks to main tasks (removes parent relationship) - `todoist_task_hierarchy_get` - Retrieves task hierarchies with completion percentage tracking **Bulk Task Operations:** - `todoist_tasks_bulk_create` - Creates multiple tasks at once for improved efficiency - `todoist_tasks_bulk_update` - Updates multiple tasks based on search criteria - `todoist_tasks_bulk_delete` - Deletes multiple tasks based on search criteria - `todoist_tasks_bulk_complete` - Completes multiple tasks based on search criteria **Comment Management:** - `todoist_comment_create` - Adds comments to tasks with optional file attachments - `todoist_comment_get` - Retrieves comments for tasks or projects **Label Management:** - `todoist_label_get` - Lists all labels with IDs, names, and colors - `todoist_label_create` - Creates new labels with optional color, order, and favorite status - `todoist_label_update` - Updates existing labels by ID or name (supports all attributes) - `todoist_label_delete` - Deletes labels by ID or name - `todoist_label_stats` - Provides detailed usage statistics and analytics **Project Management:** - `todoist_project_create` - Creates new projects with optional color and favorite status - `todoist_project_get` - Lists all projects with their IDs and names **Section Management:** - `todoist_section_create` - Creates sections within projects - `todoist_section_get` - Lists sections within projects **Testing Infrastructure:** - `todoist_test_connection` - Quick API token validation and connection test - `todoist_test_all_features` - Dual-mode testing: basic (read-only) and enhanced (full CRUD with cleanup) - `todoist_test_performance` - Performance benchmarking with configurable iterations ### Error Handling Strategy Structured error handling with custom error types: - `ValidationError` - Input validation failures - `TaskNotFoundError` - Task search failures - `LabelNotFoundError` - Label search failures - `SubtaskError` - Subtask operation failures - `TodoistAPIError` - Todoist API failures - `AuthenticationError` - Token validation failures ### Performance Optimizations - **Caching**: 30-second TTL cache for GET operations to reduce API calls - **Cache Invalidation**: Automatic cache clearing on mutations (create/update/delete) - **Type Safety**: Compile-time and runtime type checking ### Search Strategy For update, delete, and complete operations, the server uses partial string matching against task content (case-insensitive) to find tasks, enabling natural language task identification. ### Bulk Operations Strategy Bulk operations provide significant efficiency improvements by allowing multiple tasks to be processed in a single API call: - **Bulk Create**: Accepts an array of task objects and creates them sequentially, providing detailed feedback on successes and failures - **Bulk Update/Delete/Complete**: Uses flexible search criteria to identify target tasks: - `project_id`: Filter by specific project - `priority`: Filter by priority level (1 highest, 4 lowest) - `due_before`/`due_after`: Filter by due date ranges (YYYY-MM-DD format) - `content_contains`: Filter by text within task content - **Error Handling**: Each bulk operation reports individual successes and failures for better debugging - **Cache Management**: Bulk operations automatically clear relevant caches to ensure consistency ### Subtask Architecture Hierarchical task management with parent-child relationships: - **Creation Strategy**: Subtasks are created using the `parent_id` field in the Todoist API - **API Compatibility**: Uses delete & recreate pattern for converting tasks to subtasks due to API limitations - **Hierarchy Building**: Recursive algorithm builds task trees with completion percentage calculation - **Task Conversion**: - `Convert to Subtask`: Deletes original task and recreates with `parent_id` - `Promote Subtask`: Deletes subtask and recreates as main task without `parent_id` - **Completion Tracking**: Calculates completion percentages for parent tasks based on subtask status - **Bulk Operations**: Efficient creation of multiple subtasks under a single parent - **Tree Visualization**: `formatTaskHierarchy()` provides hierarchical display with completion indicators - **Cache Integration**: Subtask operations integrated with 30-second TTL caching system - **Search Strategy**: Supports both task ID and name-based parent/child identification ### Dry-Run Mode Architecture Complete simulation framework for safe testing and validation: - **DryRunWrapper Class**: Located in `src/utils/dry-run-wrapper.ts`, wraps TodoistApi to intercept mutations - **Environment Activation**: Enabled when `process.env.DRYRUN=true` - **Real Data Validation**: Uses actual API calls to validate projects, tasks, sections, and labels exist - **Simulated Mutations**: Create, update, delete, and complete operations are simulated (not executed) - **Read Operations**: Pass through to real API unchanged for authentic data queries - **Mock Response Generation**: Returns realistic mock data with generated IDs for mutation operations - **Detailed Logging**: Clear `[DRY-RUN]` prefixes show exactly what operations would perform - **Factory Pattern**: `createTodoistClient()` function automatically wraps client based on environment - **Comprehensive Coverage**: All 28 MCP tools support dry-run mode with full validation - **Type Safety**: Full TypeScript support with proper type definitions for all dry-run operations ### Data Flow Pattern 1. **Request Validation**: Type guards validate incoming parameters 2. **Input Sanitization**: Validation functions check business rules 3. **Cache Check**: GET operations check cache first 4. **API Call**: Execute Todoist API operation (or simulate in dry-run mode) 5. **Cache Management**: Update/invalidate cache as needed 6. **Error Handling**: Structured error responses with error codes ### Environment Requirements - `TODOIST_API_TOKEN` environment variable is required and validated at startup - Server exits with error code 1 if token is missing - `DRYRUN=true` optional environment variable enables dry-run mode for safe testing ### Testing Infrastructure The codebase includes comprehensive testing capabilities: **Unit Tests:** - Jest configured for ESM modules with ts-jest - Type guard unit tests in `src/__tests__/type-guards.test.ts` - Test imports use TypeScript extensions (not .js) **Integration Tests:** - `src/__tests__/integration.test.ts` - Full API integration testing - Requires `TODOIST_API_TOKEN` environment variable for execution - Tests skip gracefully when token is not available - Comprehensive testing of all MCP tools and API operations **Dry-Run Tests:** - `src/__tests__/dry-run-wrapper.test.ts` - Comprehensive dry-run mode validation - Tests all mutation operations (create, update, delete, complete) in simulation mode - Validates real data queries pass through unchanged - Tests error handling and validation in dry-run mode **Built-in Testing Tools:** - `todoist_test_connection` - Validates API token and connection - `todoist_test_all_features` - Dual-mode testing: - Basic mode: Read-only tests for tasks, projects, labels, sections, comments (default) - Enhanced mode: Full CRUD testing with automatic cleanup including subtasks - `todoist_test_performance` - Benchmarks API response times with configurable iterations **Enhanced Testing Infrastructure:** - **Comprehensive CRUD Testing**: 18 tests across 4 suites (Task, Subtask, Label, Bulk Operations) - **Automatic Test Data Management**: Generates unique test data with timestamps - **Complete Cleanup**: Removes all test data after testing to prevent workspace pollution - **Detailed Reporting**: Response times, success/failure metrics, and error details - **Suite Organization**: Grouped tests by functionality for better debugging **Running Tests:** - `npm test` - Runs all tests (unit tests always, integration tests if token available) - `TODOIST_API_TOKEN=your-token npm test` - Runs with integration tests - `npm run test:watch` - Runs tests in watch mode - `npm run test:coverage` - Runs tests with coverage report ### Code Quality - ESLint with TypeScript rules and Prettier integration - Strict TypeScript configuration with explicit return types - No `any` types - proper TypeScript interfaces throughout ### Distribution - Built as ES modules targeting ES2020 - Executable binary at `dist/index.js` with shebang - Published as `@greirson/mcp-todoist` ### CI/CD and Quality Assurance - **GitHub Actions**: Automated CI/CD pipeline with multi-Node.js version testing (18.x, 20.x, 22.x) - **Dependabot Integration**: Automated dependency updates with CI validation - **Pre-commit Hooks**: Linting and type checking enforced before commits - **Release Automation**: Automated NPM publishing on version tags ### API Compatibility Handling Due to evolving Todoist API types, the codebase uses defensive programming patterns: - **Response Format Handling**: Uses `extractArrayFromResponse()` helper to handle multiple API response formats (direct arrays, `result.results`, `result.data`) - **Type Assertions**: Strategic type assertions for API compatibility while maintaining type safety - **Error Recovery**: Try-catch patterns for API signature changes - **Flexible Response Parsing**: Handles both array and object responses gracefully - **Testing Integration**: Built-in test tools validate API compatibility across different response formats ### Important Notes - **Tool Names**: All MCP tool names use underscores (e.g., `todoist_task_create`) to comply with MCP naming requirements `^[a-zA-Z0-9_-]{1,64}$` - **Cache Strategy**: GET operations are cached for 30 seconds; mutation operations (create/update/delete) clear the cache - **Dry-Run Mode**: Enable with `DRYRUN=true` environment variable for safe testing and validation - Uses real API data for validation while simulating mutations - All 28 MCP tools support dry-run mode with comprehensive logging - Perfect for testing automations, learning the API, and safe experimentation - **Task Search**: Update/delete/complete operations support both: - **Task ID**: Direct lookup by ID (more reliable, takes precedence) - **Task Name**: Case-insensitive partial string matching against task content - **Task Identification**: When both `task_id` and `task_name` are provided, ID takes precedence - **Due Dates vs Deadlines**: - `due_string`/`due_date`: When the task appears in "Today" (start date) - `deadline_date`: Actual deadline for task completion (YYYY-MM-DD format) - **Bulk Operations**: Use bulk tools (e.g., `todoist_tasks_bulk_create`) when working with multiple tasks to improve efficiency and reduce API calls - **Bulk Search Criteria**: Bulk operations support flexible filtering by project, priority, due dates, and content matching - **Empty String Handling (Security Fix v0.8.8)**: Empty or whitespace-only strings in `content_contains` now correctly match NO tasks (not all tasks) - **Minimum Criteria Requirement**: At least one valid search criterion must be provided for bulk operations - **Project Name Resolution**: The `todoist_tasks_bulk_update` tool supports both project IDs and project names in the `project_id` field. Project names are automatically resolved to IDs - **Testing**: Use `todoist_test_all_features` after making changes to ensure functionality works correctly - **Linting**: Always run `npm run lint -- --fix` after making changes to auto-fix formatting issues - **Type Safety**: When TypeScript compilation fails due to API changes, use defensive type assertions with proper interfaces rather than disabling strict checking - **Development Workflow**: For API response handling, prefer using `extractArrayFromResponse()` helper function over inline type assertions ## Development Roadmap The codebase includes a comprehensive development plan in `todoist-mcp-dev-prd.md`: **Completed Phases:** - ✅ **Phase 1**: Testing Infrastructure (v0.6.0) - Comprehensive testing tools and integration tests - ✅ **Phase 2**: Label Management System (v0.7.0) - Full CRUD operations for labels with usage statistics and analytics - ✅ **Code Quality Improvement Phase (v0.7.0)**: Major architectural enhancements and security improvements - ✅ **Shared API Utilities**: Created `src/utils/api-helpers.ts` with unified helper functions eliminating code duplication - Added `resolveProjectIdentifier()` function to resolve project names to IDs - ✅ **Standardized Error Handling**: Built `src/utils/error-handling.ts` with ErrorHandler class and context-aware error management - ✅ **Enhanced Type Safety**: Replaced all `unknown` types with proper `TodoistAPIResponse<T>` interfaces - ✅ **Input Validation & Sanitization**: Comprehensive security protection with XSS prevention and injection attack blocking - ✅ **Centralized Cache Management**: Advanced caching system with CacheManager singleton and performance monitoring - ✅ **Refactored All Handlers**: Updated all handlers to use shared utilities and standardized patterns - ✅ **Phase 3**: Subtask Management (v0.8.0) - Hierarchical task management with parent-child relationships - ✅ **Subtask Handlers**: Created `src/handlers/subtask-handlers.ts` with full CRUD operations for hierarchical tasks - ✅ **Enhanced Testing**: Built `src/handlers/test-handlers-enhanced.ts` with comprehensive CRUD testing and automatic cleanup - ✅ **New MCP Tools**: Added 5 subtask management tools (total: 28 tools) - ✅ **Type System Enhancement**: Extended type definitions for subtask operations and hierarchy management - ✅ **API Compatibility**: Implemented workarounds for Todoist API limitations using delete & recreate patterns - ✅ **Dry-Run Mode Implementation**: Complete simulation framework for safe testing and validation - ✅ **DryRunWrapper Architecture**: Created `src/utils/dry-run-wrapper.ts` for operation simulation - ✅ **Environment Configuration**: Enabled via `DRYRUN=true` environment variable - ✅ **Comprehensive Tool Support**: All 28 MCP tools support dry-run mode with full validation - ✅ **Real Data Validation**: Uses actual API calls to validate while simulating mutations - ✅ **Factory Pattern Integration**: `createTodoistClient()` automatically handles dry-run wrapping - ✅ **Test Coverage**: Comprehensive test suite in `src/__tests__/dry-run-wrapper.test.ts` **Planned Future Phases:** - **Phase 4**: Duplicate Detection - Smart task deduplication using similarity algorithms - **Phase 5**: Project Analytics - Comprehensive project health metrics and insights All future development should use the testing infrastructure to validate changes and ensure compatibility. ## Documentation Maintenance Requirements **CRITICAL: Always keep documentation files updated when making changes to the codebase.** ### Required Documentation Updates When making ANY changes to the codebase, you MUST update the following files: #### 1. CHANGELOG.md Updates **ALWAYS update CHANGELOG.md for every significant change:** - Add new entries following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format - Use semantic versioning for version numbers - Categorize changes as: Added, Changed, Deprecated, Removed, Fixed, Security - Include specific details about new tools, API changes, or breaking changes - Update the unreleased section or create new version entries - **Never skip this step** - releases reference "See CHANGELOG.md for full details" #### 2. README.md Updates **Update README.md when:** - Adding new MCP tools (update tool count and add to Tools Overview section) - Adding new features (update Features section and Usage Examples) - Changing installation or setup procedures - Adding new usage patterns or best practices - Modifying architecture or key components #### 3. CLAUDE.md Updates **Update CLAUDE.md when:** - Adding new handlers, modules, or architectural components - Changing build commands, testing procedures, or development workflow - Adding new important notes, patterns, or best practices - Updating tool counts, capabilities, or technical details - Modifying the development roadmap or completed phases ### Documentation Update Checklist For every commit that adds features or changes functionality: - [ ] **CHANGELOG.md**: Added entry with proper categorization and version - [ ] **README.md**: Updated relevant sections (features, tools, examples) - [ ] **CLAUDE.md**: Updated technical details and architectural information - [ ] **Version consistency**: All files reflect the same tool counts and capabilities - [ ] **Cross-references**: Links between files are accurate and up-to-date ### Documentation Standards - **Be specific**: "Added 3 new testing tools" not "Added testing" - **Include examples**: Show usage patterns for new features - **Maintain consistency**: Tool counts, version numbers, and feature lists must match across all files - **Use proper formatting**: Follow established markdown patterns and structures - **Link appropriately**: Ensure cross-references between README.md and CHANGELOG.md work ### Consequences of Not Updating Documentation - Release notes will be incomplete or inaccurate - Users won't know about new features or changes - Future developers will have outdated guidance - Tool counts and capability descriptions will be wrong - Installation and setup instructions may become obsolete **Remember: Documentation is not optional - it's a required part of every change.** ## AI Team Configuration (autogenerated by team-configurator, 2025-01-21) **Important: YOU MUST USE subagents when available for the task.** ### Detected Technology Stack - **Runtime**: Node.js with TypeScript (ES2020/ES2022 modules) - **Core Framework**: Model Context Protocol (MCP) Server using @modelcontextprotocol/sdk v1.17.1 - **API Integration**: Todoist API via @doist/todoist-api-typescript v5.1.1 - **Testing**: Jest with ts-jest for ESM modules, comprehensive unit and integration tests - **Code Quality**: ESLint + Prettier with TypeScript strict mode, pre-commit hooks - **Build System**: TypeScript compiler targeting ES2020, executable binary generation - **Architecture**: Domain-driven design with modular handlers, tools, and utilities - **Transport**: stdio transport for MCP client communication - **Distribution**: NPM package (@greirson/mcp-todoist) with automated CI/CD ### AI Team Agent Assignments | Task | Agent | Notes | |------|-------|-------| | **MCP Protocol & API Integration** | `api-architect` | Design MCP tool contracts, Todoist API integration patterns | | **TypeScript Backend Development** | `backend-developer` | Core server logic, handlers, business logic implementation | | **Code Quality & Security Reviews** | `code-reviewer` | Mandatory for all PRs, security-aware reviews of API integrations | | **Performance & Caching Optimization** | `performance-optimizer` | API response optimization, caching strategies, bulk operations | | **Documentation Updates** | `documentation-specialist` | README, API docs, architecture guides, changelog maintenance | | **Legacy Code Analysis** | `code-archaeologist` | Codebase exploration for refactoring, onboarding, risk assessment | | **Complex Multi-Step Features** | `tech-lead-orchestrator` | Coordinate multiple agents for large features or architectural changes | ### Routing Rules **Use `@api-architect` when:** - Designing new MCP tool interfaces or modifying existing tool contracts - Planning Todoist API integration patterns or authentication flows - Creating OpenAPI specs for the MCP server capabilities - Standardizing error responses or validation patterns **Use `@backend-developer` when:** - Implementing new MCP tools or handlers - Adding business logic for task, project, or label operations - Building caching mechanisms or performance optimizations - Creating utility functions or type definitions **Use `@code-reviewer` when:** - Reviewing any code changes before merging (mandatory) - Security review of API token handling or input validation - Quality assessment of TypeScript type safety - Performance review of bulk operations or caching **Use `@performance-optimizer` when:** - Optimizing API response times or reducing Todoist API calls - Implementing or tuning caching strategies (30-second TTL) - Analyzing bulk operation efficiency - Profiling memory usage or improving algorithmic complexity **Use `@documentation-specialist` when:** - Updating README.md with new features or tool counts - Creating or updating API documentation - Maintaining CHANGELOG.md for releases - Writing architecture documentation or onboarding guides **Use `@code-archaeologist` when:** - Exploring unfamiliar parts of the codebase - Planning major refactoring or architectural changes - Analyzing code quality metrics or technical debt - Understanding complex business logic flows **Use `@tech-lead-orchestrator` when:** - Planning multi-phase features like duplicate detection or analytics - Coordinating work across multiple domains (tasks, projects, labels) - Making architectural decisions affecting multiple modules - Breaking down complex requirements into agent assignments ### Sample Commands - **API Design**: `@api-architect design a new MCP tool for task scheduling` - **Feature Implementation**: `@backend-developer add batch task completion with rollback` - **Quality Assurance**: `@code-reviewer review the new subtask hierarchy implementation` - **Performance Tuning**: `@performance-optimizer optimize the task search and filtering logic` - **Documentation**: `@documentation-specialist update docs for the new bulk operations tools` # important-instruction-reminders Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.