Claude Todo MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

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

  Registers the TodoWrite MCP tool with @mcp.tool. Provides input schema in docstring and type hints, error handling wrapper that delegates to internal todo_write handler.
  @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/tools/todo_write.py:6-39 (handler)

  Core handler implementation for TodoWrite tool. Validates input parameters, persists todos via store.write_todos, and returns success response.
  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:64-76 (schema)

  Input schema and documentation for TodoWrite tool defined in the function docstring, including parameter structure and expected fields.
  """ 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. """
• src/state/store.py:28-76 (helper)

  Supporting store.write_todos method that handles todo validation, timestamping, persistence saving, invoked by the TodoWrite handler.
  async def write_todos(self, todos: list[dict[str, Any]]) -> int: """ Write todos to the store (complete replacement) Returns the number of todos written """ await self.initialize() # Validate todos validate_todos(todos) # Process todos - add/update timestamps processed_todos = [] current_time = datetime.now().isoformat() # Load existing store to preserve created_at timestamps existing_store = await self.persistence.load() existing_todos_map = {todo["id"]: todo for todo in existing_store["todos"]} for todo in todos: # Preserve created_at if todo already exists if todo["id"] in existing_todos_map: created_at = existing_todos_map[todo["id"]].get( "created_at", current_time ) else: created_at = todo.get("created_at", current_time) processed_todo = { "id": todo["id"], "content": todo["content"], "status": todo["status"], "priority": todo["priority"], "created_at": created_at, "updated_at": current_time, "metadata": todo.get("metadata", None), } processed_todos.append(processed_todo) # Create new store new_store: TaskStore = { "lastModified": current_time, "todos": processed_todos, } # Save to persistence await self.persistence.save(new_store) return len(processed_todos)