Things MCP Server

Instructions

Implementation Reference

• things_server.py:164-184 (handler)

  The handler function for the 'get_headings' tool, decorated with @mcp.tool which also handles registration. Fetches headings (tasks of type 'heading') from Things database, optionally filtered by project UUID, formats them, and returns a string.

  @mcp.tool
  async def get_headings(project_uuid: str = None) -> str:
      """Get headings from Things
      
      Args:
          project_uuid: Optional UUID of a specific project to get headings from
      """
      if project_uuid:
          project = things.get(project_uuid)
          if not project or project.get('type') != 'project':
              return f"Error: Invalid project UUID '{project_uuid}'"
          headings = things.tasks(type='heading', project=project_uuid)
      else:
          headings = things.tasks(type='heading')
      
      if not headings:
          return "No headings found"
      
      from formatters import format_heading
      formatted_headings = [format_heading(heading) for heading in headings]
      return "\n\n---\n\n".join(formatted_headings)

• formatters.py:146-181 (helper)

  Helper function used by get_headings to format each heading into a readable string, including title, UUID, project, dates, notes, and optionally subtasks.

  def format_heading(heading: dict, include_items: bool = False) -> str:
      """Helper function to format a single heading."""
      heading_text = f"Title: {heading['title']}\nUUID: {heading['uuid']}"
      heading_text += f"\nType: heading"
      
      # Add project info if present
      if heading.get('project'):
          if heading.get('project_title'):
              heading_text += f"\nProject: {heading['project_title']}"
          else:
              try:
                  project = things.get(heading['project'])
                  if project:
                      heading_text += f"\nProject: {project['title']}"
              except Exception:
                  pass
      
      # Add dates
      if heading.get('created'):
          heading_text += f"\nCreated: {heading['created']}"
      if heading.get('modified'):
          heading_text += f"\nModified: {heading['modified']}"
          
      # Add notes if present
      if heading.get('notes'):
          heading_text += f"\nNotes: {heading['notes']}"
          
      if include_items:
          # Get todos under this heading
          todos = things.todos(heading=heading['uuid'])
          if todos:
              heading_text += "\n\nTasks under heading:"
              for todo in todos:
                  heading_text += f"\n- {todo['title']}"
      
      return heading_text