todoist-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Todoist MCP (Model Context Protocol) server built with TypeScript and Bun. The project integrates Todoist with AI assistants like Claude through the MCP standard, allowing AI to interact with Todoist tasks and projects.

Development Commands

# Install dependencies and setup tools
bun install       # Install Node.js dependencies
mise install      # Install required tool versions (Bun, Node.js, linting tools)

# Build and run
bun run build     # Build the MCP server to dist/index.js
bun dist/index.js # Run the built MCP server
# or for development: bun run src/index.ts

# Docker
docker build -t todoist-mcp-server .  # Build Docker image
docker run -e TODOIST_API_TOKEN=token todoist-mcp-server  # Run in container

# Testing
bun test          # Run all tests
bun test src/lib/todoist/client.spec.ts  # Run specific test file

# Code quality
bun run lint      # Check code with Biome
bun run format    # Format and fix code with Biome
bun run typecheck # Run TypeScript type checking

# MCP Server Testing
bun run inspector # Build and launch MCP Inspector for visual testing
bun run preinspector # Build server (runs automatically before inspector)

# GitHub Actions linting (requires mise tools)
actionlint        # Lint GitHub Actions workflow files
ghalint run       # Check GitHub Actions policies
zizmor . --persona=auditor  # Security audit GitHub Actions

# Action version management
pinact run -u     # Update GitHub Actions to latest versions

# Development workflow
bun run prepare   # Install git hooks (runs automatically on install)

Project Structure

src/              # Source code
├── index.ts      # Minimal entry point (delegates to server.ts)
├── server.ts     # MCP server initialization and configuration
├── mcp/          # Modular MCP architecture with colocation
│   └── tools/     # Tool handlers with co-located schemas  
│       ├── index.ts      # registerTools() aggregator
│       ├── projects.ts   # Project tools (CRUD + read operations)
│       ├── sections.ts   # Section tools (CRUD + read operations)
│       ├── tasks.ts      # Task tools (CRUD + close/reopen + read operations)
│       ├── labels.ts     # Label tools (create + update + individual/list read + delete operations)
│       ├── comments.ts   # Comment tools (separate task/project creation + read with pagination + update/delete)
└── lib/
    └── todoist/  # Todoist API client wrapper
        ├── client.ts     # TodoistClient class with CRUD operations
        ├── types.ts      # TypeScript types and interfaces
        └── client.spec.ts # Comprehensive test suite
scripts/          # Build and utility scripts
├── build.ts      # Bun.build configuration
dist/             # Built output (Bun runtime compatible)
Dockerfile        # Multi-stage Docker build with Bun