todoist-mcp: Instructions file for Claude Code

Todoist MCP Server - Development Guidelines

For repo structure, architecture, shared utilities, and where things live, read CODEBASE.md first. This file covers the rules; CODEBASE.md is the map.

Tool Schema Design Rules

Output schemas must never use .nullable()

structuredContent is sanitised with removeNullFields before it leaves the server, so a null can never reach a client. A nullable output field therefore declares a value the tool cannot deliver: the MCP SDK validates the sanitised payload against the declared outputSchema and fails the whole call with Output validation error the moment that field is stripped.

Declare the field .optional() instead and leave the key out of structuredContent (foo: value ?? undefined) when there is nothing to report. src/tools/output-schema-nullability.test.ts enforces this across every registered tool.

Removing/Clearing Optional Fields

When you need to support clearing an optional field:

1. Use a special string value (not null - avoids LLM provider compatibility issues, with Gemini in particular)

   • For assignments: use "unassign"
   • For other fields: use "remove" or similar descriptive string

2. Handle both legacy and new patterns in runtime logic for backward compatibility:

   if (fieldValue === null || fieldValue === 'remove') {
       // Convert to null for API call
       updateArgs = { ...updateArgs, fieldName: null }
   }
   

3. Update schema description to document the special string value

Examples from Codebase

• PR #181: Fixed responsibleUser field - changed from .nullable() to using "unassign" string
• Latest commit: Fixed deadlineDate field - changed from .nullable() to using "remove" string

Why This Matters

• Ensures compatibility with all LLM providers (OpenAI, Anthropic, Gemini, etc.)
• Maintains backward compatibility through dual handling
• Creates self-documenting APIs with explicit action strings