Todokit MCP Server

Instructions

Implementation Reference

• src/tools/add_todo.ts:22-36 (handler)

  The handler function for the 'add_todo' MCP tool. It destructures input parameters, calls the storage addTodo function, and returns a formatted tool response or error.

  async ({ title, description, priority, dueDate, tags }) => {
    try {
      const todo = await addTodo(title, description, priority, dueDate, tags);
      return createToolResponse({
        ok: true,
        result: {
          item: todo,
          summary: `Added todo "${todo.title}"`,
          nextActions: ['list_todos', 'update_todo', 'complete_todo'],
        },
      });
    } catch (err) {
      return createErrorResponse('E_ADD_TODO', getErrorMessage(err));
    }
  }

• src/tools/add_todo.ts:9-38 (registration)

  Registration of the 'add_todo' tool with the MCP server, including metadata, schemas, and inline handler.

  export function registerAddTodo(server: McpServer): void {
    server.registerTool(
      'add_todo',
      {
        title: 'Add Todo',
        description: 'Add a new todo item',
        inputSchema: AddTodoSchema,
        outputSchema: DefaultOutputSchema,
        annotations: {
          readOnlyHint: false,
          idempotentHint: false,
        },
      },
      async ({ title, description, priority, dueDate, tags }) => {
        try {
          const todo = await addTodo(title, description, priority, dueDate, tags);
          return createToolResponse({
            ok: true,
            result: {
              item: todo,
              summary: `Added todo "${todo.title}"`,
              nextActions: ['list_todos', 'update_todo', 'complete_todo'],
            },
          });
        } catch (err) {
          return createErrorResponse('E_ADD_TODO', getErrorMessage(err));
        }
      }
    );
  }

• src/schemas/inputs.ts:124-145 (schema)

  Zod schema for 'add_todo' input validation (TodoInputSchema aliased as AddTodoSchema).

  const TodoInputSchema: ZodType<TodoInput> = z.strictObject({
    title: z.string().min(1).max(200).describe('The title of the todo'),
    description: z
      .string()
      .max(2000)
      .optional()
      .describe('Optional description of the todo'),
    priority: z
      .enum(['low', 'normal', 'high'])
      .optional()
      .describe('Priority level (default: normal)'),
    dueDate: IsoDateSchema.optional().describe(
      'Due date in ISO format (YYYY-MM-DD)'
    ),
    tags: z
      .array(TagSchema)
      .max(50)
      .optional()
      .describe('Tags for categorization'),
  });
  
  export const AddTodoSchema: ZodType<TodoInput> = TodoInputSchema;

• src/lib/storage.ts:74-88 (helper)

  Helper function that adds a single todo item by wrapping the batch addTodos function from storage layer.

  export async function addTodo(
    title: string,
    description?: string,
    priority: 'low' | 'normal' | 'high' = 'normal',
    dueDate?: string,
    tags: string[] = []
  ): Promise<Todo> {
    const [todo] = await addTodos([
      { title, description, priority, dueDate, tags },
    ]);
    if (!todo) {
      throw new Error('Failed to create todo');
    }
    return todo;
  }

• src/tools/index.ts:12-12 (registration)

  Top-level call to register the 'add_todo' tool as part of all tools registration.

  registerAddTodo(server);