Todokit MCP Server

Instructions

Implementation Reference

• src/tools/complete_todo.ts:62-73 (handler)

  The main handler function that processes the complete_todo tool input: resolves the todo selector, calls the storage mutation, and constructs the tool response.

  async function handleCompleteTodo(
    input: CompleteTodoInput
  ): Promise<CallToolResult> {
    const targetCompleted = input.completed ?? true;
    const selector =
      input.id !== undefined ? { id: input.id } : { query: input.query };
    const outcome = await completeTodoBySelector(
      toResolveInput(selector),
      targetCompleted
    );
    return buildOutcomeResponse(outcome, targetCompleted);
  }

• src/schemas/inputs.ts:175-193 (schema)

  Zod schema for CompleteTodoInput: union of selector by ID or query, with optional 'completed' boolean.

  const completeTodoSelector = buildSelectorSchemas(
    'The ID of the todo to complete',
    'Search text to find a single todo to complete'
  );
  
  export const CompleteTodoSchema: ZodType<CompleteTodoInput> = z.union([
    completeTodoSelector.byId.extend({
      completed: z
        .boolean()
        .optional()
        .describe('Set completion status (default: true)'),
    }),
    completeTodoSelector.byQuery.extend({
      completed: z
        .boolean()
        .optional()
        .describe('Set completion status (default: true)'),
    }),
  ]);

• src/tools/complete_todo.ts:75-96 (registration)

  Registers the complete_todo tool on the MCP server with input/output schemas, metadata, and error-handling wrapper around the handler.

  export function registerCompleteTodo(server: McpServer): void {
    server.registerTool(
      'complete_todo',
      {
        title: 'Complete Todo',
        description: 'Set completion status for a todo item',
        inputSchema: CompleteTodoSchema,
        outputSchema: DefaultOutputSchema,
        annotations: {
          readOnlyHint: false,
          idempotentHint: true,
        },
      },
      async (input) => {
        try {
          return await handleCompleteTodo(input);
        } catch (err) {
          return createErrorResponse('E_COMPLETE_TODO', getErrorMessage(err));
        }
      }
    );
  }

• src/lib/storage.ts:221-248 (helper)

  Storage layer function that resolves the todo selector, toggles completion status if needed, handles 'already' case, and persists changes via withTodos.

  export async function completeTodoBySelector(
    input: ResolveTodoInput,
    completed: boolean
  ): Promise<CompleteTodoOutcome> {
    return withTodos<CompleteTodoOutcome>((todos) => {
      const outcome = unwrapResolution(resolveTodoTargetFromTodos(todos, input));
      if (outcome.kind !== 'match') {
        return { todos, result: outcome };
      }
  
      if (outcome.todo.completed === completed) {
        return { todos, result: { kind: 'already', todo: outcome.todo } };
      }
  
      const updated = applyUpdateToTodos(todos, outcome.todo.id, { completed });
      if (!updated.result) {
        return {
          todos,
          result: createNotFoundOutcome(outcome.todo.id),
        };
      }
  
      return {
        todos: updated.todos,
        result: { kind: 'match', todo: updated.result },
      };
    });
  }