Things MCP Server

Instructions

Implementation Reference

• things_server.py:335-381 (handler)

  Primary MCP tool handler for 'update_todo'. Decorated with @mcp.tool for registration. Executes by constructing and running a Things URL scheme.

  @mcp.tool
  async def update_todo(
      id: str,
      title: str = None,
      notes: str = None,
      when: str = None,
      deadline: str = None,
      tags: List[str] = None,
      completed: bool = None,
      canceled: bool = None,
      list: str = None,
      list_id: str = None,
      heading: str = None,
      heading_id: str = None
  ) -> str:
      """Update an existing todo in Things
      
      Args:
          id: ID of the todo to update
          title: New title
          notes: New notes
          when: New schedule
          deadline: New deadline
          tags: New tags
          completed: Mark as completed
          canceled: Mark as canceled
          list: The title of a project or area to move the to-do into
          list_id: The ID of a project or area to move the to-do into (takes precedence over list)
          heading: The heading title to move the to-do under
          heading_id: The heading ID to move the to-do under (takes precedence over heading)
      """
      url = url_scheme.update_todo(
          id=id,
          title=title,
          notes=notes,
          when=when,
          deadline=deadline,
          tags=tags,
          completed=completed,
          canceled=canceled,
          list=list,
          list_id=list_id,
          heading=heading,
          heading_id=heading_id
      )
      url_scheme.execute_url(url)
      return f"Updated todo with ID: {id}"

• url_scheme.py:95-119 (helper)

  Helper utility in url_scheme.py that generates the Things URL scheme command for updating a todo, used by the MCP handler.

  def update_todo(id: str, title: Optional[str] = None, notes: Optional[str] = None,
                  when: Optional[str] = None, deadline: Optional[str] = None,
                  tags: Optional[list[str]] = None, completed: Optional[bool] = None,
                  canceled: Optional[bool] = None, list: Optional[str] = None,
                  list_id: Optional[str] = None, heading: Optional[str] = None,
                  heading_id: Optional[str] = None) -> str:
      """Construct URL to update an existing todo.
      
      Note: list_id takes precedence over list if both are provided.
      """
      params = {
          'id': id,
          'title': title,
          'notes': notes,
          'when': when,
          'deadline': deadline,
          'tags': tags,
          'completed': completed,
          'canceled': canceled,
          'list': list,
          'list-id': list_id,
          'heading': heading,
          'heading-id': heading_id
      }
      return construct_url('update', {k: v for k, v in params.items() if v is not None})