Add support for creating headings in Things

[JoeDuncko]

Add support for creating headings in Things

Description

#8 adds support for moving todos to existing headings via the heading and heading_id parameters in things:add_todo and things:update_todo, but there's no functionality to create new headings. This limits the ability to programmatically organize todos into new sections.

Current Functionality

• ✅ Can move todos to existing headings using heading or heading_id parameters
• ✅ Can see headings when they exist in todo responses
• ❌ Cannot create new headings

Requested Feature

Add a new function to create headings in Things, similar to how things:add_todo and things:add_project work.

Proposed API

New Function: things:add_heading

{
  "name": "things:add_heading",
  "description": "Create a new heading in Things",
  "parameters": {
    "properties": {
      "title": {
        "title": "Title", 
        "type": "string",
        "description": "Title of the heading"
      },
      "list_id": {
        "title": "List Id", 
        "type": "string", 
        "default": null,
        "description": "ID of project/area to add heading to"
      },
      "list_title": {
        "title": "List Title", 
        "type": "string", 
        "default": null,
        "description": "Title of project/area to add heading to"
      },
      "when": {
        "title": "When", 
        "type": "string", 
        "default": null,
        "description": "When to schedule the heading (today, tomorrow, anytime, someday, or YYYY-MM-DD)"
      }
    },
    "required": ["title"]
  }
}

Use Cases

1. Programmatic organization: Create headings to organize batches of related todos
2. Project templates: Automatically create project structures with predefined headings
3. Workflow automation: Create headings based on external triggers (calendar events, project phases, etc.)
4. Better todo management: Organize todos into logical sections as they're created

Example Usage

// Create a new heading for organizing work tasks
await things.add_heading({
  title: "Sprint Planning",
  list_title: "Work Projects",
  when: "today"
});

// Then add todos under that heading
await things.add_todo({
  title: "Review user stories",
  heading: "Sprint Planning",
  list_title: "Work Projects"
});

Implementation Considerations

1. Things URL scheme: Investigate if Things supports creating headings via URL schemes
2. Database integration: If using direct database access, ensure headings are created with proper relationships
3. Return value: Should return the created heading's ID for immediate use in subsequent todo creation
4. Error handling: Handle cases where the target list doesn't exist or heading already exists
5. Consistency: Maintain parameter naming consistency with existing add_todo and add_project functions

Related Functions That Should Be Updated

Consider also adding:

• things:update_heading - for modifying existing headings
• things:get_headings - for listing all headings (if not already available)

Priority

Medium-High - This would significantly improve the organizational capabilities of the MCP server and enable more sophisticated workflow automation.

Alternative Workarounds

Currently, users must:

1. Manually create headings in the Things app
2. Note the heading names/IDs for use in API calls
3. Cannot dynamically create organizational structures

This limits the effectiveness of automated todo management workflows.

[JoeDuncko]

Ah, actually, this one might be impossible. After fighting a ton with Codex, I decided to try it myself from first principals. Apparently Things just doesn't support adding headings via URLs.

See this conversation with ChatGPT https://chatgpt.com/share/689794cb-f4e4-800a-991e-d66c71a9f092

[hald]

Looks like that's confirmed in the Things URL documentation:

heading-id
String. Takes precedence over heading. The ID of a heading within a project to add to. Ignored if a project is not specified, or if the heading doesn’t exist.
heading
String. The title of a heading within a project to add to. Ignored if heading-id is present, if a project is not specified, or if the heading doesn’t exist.

[3n9]

Things does support headings in json format. Excerpt from example:

  {
      "type": "project",
      "attributes": {
        "title": "Vacation in Rome",
        "notes": "Some time in August.",
        "area": "Family",
        "items": [
 ...
          {
            "type": "heading",
            "attributes": {
              "title": "Sights"
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Vatican City"
            }
          },
...

[3n9]

Ah, actually, this one might be impossible. After fighting a ton with Codex, I decided to try it myself from first principals. Apparently Things just doesn't support adding headings via URLs.

See this conversation with ChatGPT https://chatgpt.com/share/689794cb-f4e4-800a-991e-d66c71a9f092

The last answer GPT gave you was correct. You can copy/paste that link in notes then and try opening it. New project will be created with headings.

[skempken]

After investigating this thoroughly, adding headings to existing projects is unfortunately not supported by the Things URL scheme – even via the json command.

What does work: creating headings as part of new project creation using the JSON format:

[{
  "type": "project",
  "attributes": {
    "title": "My Project",
    "items": [
      { "type": "heading", "attributes": { "title": "Phase 1" } },
      { "type": "to-do", "attributes": { "title": "First task" } }
    ]
  }
}]

For adding headings to existing projects, I tested the following approaches – none worked:

• things:///add?type=heading&list-id=<id> – the add command with a type parameter
• Standalone heading object with list-id, project, and list as attribute names:

[{ "type": "heading", "attributes": { "title": "My Heading", "list-id": "<project-id>" } }]
[{ "type": "heading", "attributes": { "title": "My Heading", "project": "<project-id>" } }]
[{ "type": "heading", "attributes": { "title": "My Heading", "list": "Project Title" } }]

• Project object with existing ID in attributes, adding heading via items:

[{ "type": "project", "attributes": { "id": "<project-id>", "items": [{ "type": "heading", "attributes": { "title": "My Heading" } }] } }]

• Project object with existing ID at root level:

[{ "type": "project", "id": "<project-id>", "attributes": { "items": [{ "type": "heading", "attributes": { "title": "My Heading" } }] } }]

• All of the above with and without an auth token passed as auth-token query parameter

The heading type in the JSON format only supports title and archived as attributes, with no way to reference an existing project.

The only remaining option would be direct SQLite access to the Things database, which seems out of scope for this project.

[3n9]

It is possible to recreate a project with a new heading. It is not an elegant solution, but may work as a temporary hack till things api improves.

[fwahl711]

Looked into this while working through the open issues — wanted to flag what the URL scheme actually permits, since the PR can't easily ship the API as proposed.

Headings can only be created as part of a fresh project's creation, never standalone or into an existing project. Per the json command schema:

• heading is a valid type in the JSON schema, but it appears only inside a project's items array during the project's own create operation.
• The schema explicitly notes: "To add to-dos to an existing project, create individual to-do objects instead" — and there's no equivalent path for headings, because the heading type has no list-id / project-id / parent attribute.
• The update operation on projects doesn't accept new structural items either — it can change notes, tags, dates, etc., but not insert headings or to-dos.

So the proposed add_heading(list_id=…) tool — adding a heading to a project the user already has — isn't possible through Things' current URL scheme. Standalone headings (without a project) aren't possible either, because Things doesn't model them.

What is implementable is extending add_project to take a structured items list so a user can create a new project with headings + to-dos in one go. Happy to put that up as a separate PR if it sounds useful, but it doesn't satisfy this issue as written — the gap really is upstream.