get_headings
Extract headings from projects in Things app using a specified project UUID. Simplify task organization and project analysis by retrieving structured data for better workflow management.
Instructions
Get headings from Things
Args: project_uuid: Optional UUID of a specific project to get headings from
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_uuid | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
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