Todokit MCP Server

Instructions

Implementation Reference

• src/tools/delete_todo.ts:49-85 (handler)

  Handler functions (handleDeleteTodo, handleDeleteTodoDryRun, handleDeleteTodoLive) that implement the core logic for deleting a todo item, supporting dry-run mode and selector-based resolution.

  async function handleDeleteTodoDryRun(
    input: DeleteTodoInput
  ): Promise<CallToolResult> {
    const todos = await getTodos();
    const selector =
      input.id !== undefined ? { id: input.id } : { query: input.query };
    const outcome = unwrapResolution(
      resolveTodoTargetFromTodos(todos, toResolveInput(selector))
    );
    if (outcome.kind === 'error') return outcome.response;
    if (outcome.kind === 'ambiguous') {
      return buildDryRunMultiple(outcome.previews, outcome.matches.length);
    }
    return buildDeleteResponse(outcome.todo, true);
  }
  
  async function handleDeleteTodoLive(
    input: DeleteTodoInput
  ): Promise<CallToolResult> {
    const selector =
      input.id !== undefined ? { id: input.id } : { query: input.query };
    const outcome = await deleteTodoBySelector(toResolveInput(selector));
    if (outcome.kind === 'error' || outcome.kind === 'ambiguous') {
      return outcome.response;
    }
    return buildDeleteResponse(outcome.todo, false);
  }
  
  async function handleDeleteTodo(
    input: DeleteTodoInput
  ): Promise<CallToolResult> {
    const dryRun = input.dryRun ?? false;
    if (dryRun) {
      return handleDeleteTodoDryRun(input);
    }
    return handleDeleteTodoLive(input);
  }

• src/tools/delete_todo.ts:87-109 (registration)

  Registration of the 'delete_todo' tool with the MCP server, specifying title, description, schemas, annotations, and handler.

  export function registerDeleteTodo(server: McpServer): void {
    server.registerTool(
      'delete_todo',
      {
        title: 'Delete Todo',
        description: 'Delete a todo item (supports dry-run)',
        inputSchema: DeleteTodoSchema,
        outputSchema: DefaultOutputSchema,
        annotations: {
          readOnlyHint: false,
          idempotentHint: true,
          destructiveHint: true,
        },
      },
      async (input) => {
        try {
          return await handleDeleteTodo(input);
        } catch (err) {
          return createErrorResponse('E_DELETE_TODO', getErrorMessage(err));
        }
      }
    );
  }

• src/schemas/inputs.ts:155-173 (schema)

  DeleteTodoSchema: Zod schema defining the input for delete_todo tool, supporting ID or query selector with optional dryRun flag.

  const deleteTodoSelector = buildSelectorSchemas(
    'The ID of the todo to delete',
    'Search text to find a single todo to delete'
  );
  
  export const DeleteTodoSchema: ZodType<DeleteTodoInput> = z.union([
    deleteTodoSelector.byId.extend({
      dryRun: z
        .boolean()
        .optional()
        .describe('Simulate the deletion without changing data'),
    }),
    deleteTodoSelector.byQuery.extend({
      dryRun: z
        .boolean()
        .optional()
        .describe('Simulate the deletion without changing data'),
    }),
  ]);

• src/lib/storage.ts:200-219 (helper)

  deleteTodoBySelector: Storage helper that resolves a todo by selector and deletes it from the todos list, returning match outcome.

  export async function deleteTodoBySelector(
    input: ResolveTodoInput
  ): Promise<MatchOutcome> {
    return withTodos<MatchOutcome>((todos) => {
      const outcome = unwrapResolution(resolveTodoTargetFromTodos(todos, input));
      if (outcome.kind !== 'match') {
        return { todos, result: outcome };
      }
  
      const remaining = todos.filter((todo) => todo.id !== outcome.todo.id);
      if (remaining.length === todos.length) {
        return {
          todos,
          result: createNotFoundOutcome(outcome.todo.id),
        };
      }
  
      return { todos: remaining, result: { kind: 'match', todo: outcome.todo } };
    });
  }