v0.8.1 - 2026-06-05

Features

• Add Area Creation: New add_area tool creates Areas in Things 3. Since the Things URL scheme has no add-area command, this uses AppleScript (make new area with properties {name:...}) and returns the new Area's UUID. Title strings are escaped to prevent AppleScript injection. (#45)
• Update Area: New update_area tool renames an Area and/or sets its tags, also via AppleScript. Only provided fields are changed. There is intentionally no delete_area tool: deleting an Area in Things also deletes every project it contains.
• Response Pagination: The list and search read tools now accept optional limit and offset parameters, so large Things lists can be inspected in chunks instead of returning everything at once. Default behaviour is unchanged when no pagination is passed; otherwise a Showing X-Y of Z items header is added, and an out-of-range offset is reported distinctly from an empty result. (#41)
• Structured Responses: The 16 list/search read tools now return both the human-readable text (unchanged) and machine-readable structured_content — the raw item dicts plus count/total/offset/limit metadata — so MCP clients can consume either form. Built on FastMCP 3.x's native ToolResult/structured-output support (inspired by but supersedes the approach in #40). The structured items are the same data the text renders (full item dicts, including nested checklist / sub-items), coerced to JSON-safe values (e.g. dates → ISO strings). Use limit to bound large lists — it shrinks both the text and structured channels together.

Maintenance

• FastMCP 3.x: Migrated to FastMCP 3.x. The dependency pin was an open-ended fastmcp>=2.0.0, so fresh installs were already resolving FastMCP 3.x untested; the pin is now bounded to fastmcp>=3.0.0,<4. Runtime behaviour is unchanged — in 3.x the @mcp.tool decorator returns the original function, so the test suite was updated to call tool functions directly instead of via the removed .fn accessor. All 155 tests pass under FastMCP 3.4.0.

Credits

This release was shaped by several community contributions — thank you all 🙏

• @Jscoats — Area creation via AppleScript (#45). The new add_area tool is based on this work, and update_area extends the same AppleScript approach.
• @ariiscoding — Response pagination (#41). The limit/offset design — including distinguishing an out-of-range page from an empty result — comes from this PR; it was reimplemented on the current codebase.
• @NickChristensen — Structured MCP responses (#40). The dual text + structured-content design originated here; 0.8.1 realizes it natively on FastMCP 3.x.

Bug fixes

• URL Encoding: Slashes in titles/notes/checklist items are now percent-encoded as %2F. Previously a title like "Example 2/13" was silently truncated at the slash by Things' URL parser. Affects every URL-scheme operation, not just project updates. (#47 / #48)
• get_today Resilience: get_today no longer crashes with '<' not supported between instances of 'NoneType' and 'str' when Things' Today view contains deadline-only overdue items mixed with dated ones. Falls back to a local, None-safe sort when the upstream things.today() sort hits this case. (#43 / #49)
• Logbook Filter: get_logbook now filters by completion date (stop_date) instead of creation date. Tasks created weeks ago but checked off recently now appear in the report; 7d and 1w periods return useful results. Period parsing accepts d/w/m/y and surfaces invalid period strings explicitly. (#46 / #50)

Features

• Checklist Updates on Existing Todos: update_todo gains checklist_items, prepend_checklist_items, and append_checklist_items parameters. Existing tasks can now have their checklists edited without recreating the task and losing its UUID. (#34 / #51)
• Tag Usage Report: New get_tag_usage tool lists every tag with its open and total task counts, sorted by usage descending; only_unused=True narrows to cleanup candidates. update_todo gains an add_tags parameter (append) alongside the existing tags (replace). (#14 / #52)
• Bulk Updates: New bulk_update_todos tool applies the same change (list, tags/add_tags, when, deadline, heading, completed, canceled) to many to-dos in a single Things round-trip via the URL scheme's json endpoint. Replaces N sequential calls for weekly-review batch moves. Requires THINGS_AUTH_TOKEN. (#22 / #53)

Internal

• Formatters Refactor: Centralised the duplicated things.get-with-fallback pattern in a new _lookup_title helper, and the four-times-duplicated Created/Modified date block in a new _append_timestamps helper. Behaviour unchanged — the 67 existing formatter tests all still pass.
• Acknowledged Things-API Limits: Recurrence creation (#42) and standalone heading creation (#10) cannot be implemented via Things' current URL scheme or AppleScript (repetition rule is read-only; headings can only be created inside a project's initial create operation). Documented upstream so future contributors don't waste time on the same dead ends.

Credits

Huge thanks to @fwahl711 (Florian Wahl), who authored every fix and feature in this release — all of #48–#54. 🙏

• Fix Someday project tasks appearing in Today/Upcoming/Anytime views
• Show "(inherited from project)" annotation for tasks in Someday projects
• Update integration test plan with view-isolation and positive-presence tests
• Backfill changelog for v0.7.0–v0.7.3

• Fix verbose debug logging from third-party libraries (#36)
• Add uvx path troubleshooting (#35)

What's New

• MCPB now uses uvx: Fetches the package from PyPI instead of bundling source files (1KB vs 8KB)
• Cleaner README: Reorganized installation instructions

Installation

Claude Desktop

Download things-mcp-0.7.1.mcpb below and double-click to install.

Any MCP Client

uvx things-mcp

See the README for more options.

v0.6.0 - 2026-01-14

• Creation Date Filtering: Added last parameter to search_advanced for filtering by creation date (e.g., '3d' for last 3 days, '1w' for last week)
• DateTime Scheduling with Reminders: Extended when parameter to support datetime format with reminders (YYYY-MM-DD@HH:MM)
• HTTP Transport: Added optional HTTP transport mode via environment variables (THINGS_MCP_TRANSPORT, THINGS_MCP_HOST, THINGS_MCP_PORT). Note: HTTP transport requires running the server directly and is not available when installed via the .mcpb package.
• Background Execution Fix: Changed URL execution from AppleScript to shell script with open -g to prevent Things from coming to foreground
• Bug Fix: Fixed search_advanced type parameter causing duplicate keyword argument error
• MCP Integration Test Plan: Added Claude-executable integration test plan (docs/mcp_integration_test_plan.md) for verifying MCP tools against a live Things database

What's Changed

MCPB Package Format

• Migrated from DXT to MCPB package format for Claude Desktop extensions
• Now uses uv for runtime dependency resolution instead of bundled wheels
• Requires uv to be installed (brew install uv)

Human-Readable Age Display

• Tasks now display "Age: X ago" showing time since creation
• Tasks now display "Last modified: X ago" showing time since last update
• Ages shown in natural language (e.g., "3 days ago", "2 weeks ago")
• Thanks to @jjprior for this contribution!

Installation

1. Install uv: brew install uv
2. Download things-mcp-0.5.0.mcpb below
3. Double-click to install in Claude Desktop

• DXT Package Support: Added automated DXT packaging system with build_dxt.sh script and manifest.json configuration
• Improved README: Recommended DXT as preferred installation option

New Features

• Add get_headings() MCP tool to list/find headings by project
• Enhanced heading support throughout the system - headings now shown in project listings and todos

What's Changed

• Add initial Heading support for Todos by @JoeDuncko in #8
• Include checklist items in todo responses by @JoeDuncko in #11

New Features

• Include Heading With Todo: Todos now show their associated heading information
• Checklist Integration: All checklist items are now included in todo responses