Claude Todo MCP Server

Instructions

Implementation Reference

• src/tools/todo_write.py:6-39 (handler)

  Core handler function `todo_write` that performs validation on input parameters and writes the todos list to the persistent store using `store.write_todos`. This contains the primary execution logic for the TodoWrite tool.

  async def todo_write(params: TodoWriteParams) -> TodoWriteResponse:
      """
      Update the entire task list (complete replacement).
  
      Parameters:
          params: Dictionary containing 'todos' list
  
      Returns:
          TodoWriteResponse with success status and todo count
  
      Raises:
          ValidationError: If todos fail validation
      """
      # Validate params structure
      if not isinstance(params, dict):
          raise ValidationError("Parameters must be a dictionary")
  
      if "todos" not in params:
          raise ValidationError("Missing required field: todos")
  
      todos = params["todos"]
  
      try:
          # Write todos (validation happens inside)
          count = await store.write_todos(todos)
  
          return {"success": True, "count": count}
      except ValidationError:
          # Re-raise validation errors
          raise
      except Exception as e:
          # Wrap other errors
          raise ValidationError(f"Failed to write todos: {str(e)}")

• src/server.py:62-88 (registration)

  MCP tool registration and wrapper handler for `TodoWrite`. Decorated with `@mcp.tool` and delegates to the core `todo_write` function while handling errors.

  @mcp.tool
  async def TodoWrite(todos: list[dict[str, Any]]) -> dict[str, Any]:
      """
      Update the entire task list (complete replacement).
  
      Parameters:
          todos: List of todo items, each containing:
              - id: Unique identifier for the task
              - content: Task description
              - status: Current status (pending, in_progress, completed)
              - priority: Task priority (high, medium, low)
              - metadata: Optional additional data
  
      Returns success status and count of todos written.
      """
      try:
          return await todo_write({"todos": todos})
      except ValidationError as e:
          return {"error": {"code": "VALIDATION_ERROR", "message": str(e)}}
      except Exception as e:
          return {
              "error": {
                  "code": "WRITE_ERROR",
                  "message": f"Failed to write todos: {str(e)}",
              }
          }

• src/types.py:36-43 (schema)

  Type definitions (schemas) for `TodoWriteParams` input and `TodoWriteResponse` output used in the tool implementation.

  class TodoWriteParams(TypedDict):
      todos: list[dict[str, Any]]
  
  
  class TodoWriteResponse(TypedDict):
      success: bool
      count: int