things-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,187 @@
+# things-mcp-server
+
+A local MCP server for controlling [Things](https://culturedcode.com/things/) on macOS.
+
+## Features
+
+- Read:
+  - `things_get_server_status`
+  - `things_list_todos`
+  - `things_list_projects`
+  - `things_list_areas`
+  - `things_list_area_items`
+  - `things_list_project_todos`
+  - `things_search_todos`
+  - `things_get_todo`
+- Write:
+  - `things_add_area`
+  - `things_add_todo`
+  - `things_add_project`
+  - `things_update_todo`
+  - `things_complete_todo`
+  - `things_move_todo`
+  - `things_delete_todo`
+- UI helper:
+  - `things_show_item`
+
+## Security Model
+
+- Strict command whitelist: only `osascript` and `open` are executable.
+- No shell interpolation: subprocesses run with `shell: false`.
+- Things URL command whitelist: only approved commands (`add`, `add-project`, `update`, `show`, `search`).
+- Input validation for IDs, dates, title/notes/tag sizes.
+- All write/modify operations require `confirm=true`.
+- Sensitive strings (auth token) are redacted from tool error output.
+
+## Requirements
+
+- macOS with Things installed (`Things3` AppleScript app name)
+- Node.js 20+
+- Things URL Scheme auth token (`THINGS_AUTH_TOKEN`) for URL-scheme write operations
+
+Get auth token in Things:
+
+1. Open Things.
+2. Go to Settings/Preferences.
+3. Open URL scheme settings and copy the token.
+
+## Setup
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
+## Run
+
+```bash
+THINGS_AUTH_TOKEN=your_token_here pnpm start
+```
+
+Use the same Node runtime for install/build/start and MCP host process. Native dependency (`better-sqlite3`) must match Node ABI.
+
+Or in development:
+
+```bash
+THINGS_AUTH_TOKEN=your_token_here pnpm dev
+```
+
+## MCP Config (Local Source Checkout)
+
+This repository includes `mcp.config.example.json` for running the built local server:
+
+```json
+{
+  "mcpServers": {
+    "things": {
+      "command": "/opt/homebrew/bin/node",
+      "args": ["/Users/your-user/Code/things-mcp/dist/index.js"],
+      "env": {
+        "THINGS_AUTH_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- Run `pnpm build` first so `dist/index.js` exists.
+- Update `args[0]` to your actual local absolute path.
+- Keep `command` aligned with the same Node runtime used for install/build to avoid `better-sqlite3` ABI mismatch.
+
+## Publish and Install (No Source Checkout)
+
+You can publish to npm and run it via `npx`, so client machines do not need this source repo.
+
+Publish:
+
+```bash
+pnpm test
+pnpm publish --access public
+```
+
+MCP config example (installed on demand from npm):
+
+```json
+{
+  "mcpServers": {
+    "things": {
+      "command": "npx",
+      "args": ["-y", "things-mcp-server"],
+      "env": {
+        "THINGS_AUTH_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+Optional SQLite read path override:
+
+```bash
+THINGS_DB_PATH="/Users/you/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/ThingsData-XXXX/Things Database.thingsdatabase/main.sqlite"
+```
+
+By default, the server auto-discovers Things databases under Group Containers, including backup bundles. In most setups, `THINGS_DB_PATH` is not required.
+
+Troubleshooting recurring items with missing date:
+
+1. Call `things_get_server_status` and verify `sqlite.enabled=true`.
+2. If false, inspect `resolvedPath`, `existingCandidateCount`, and `lastOpenError` from `things_get_server_status`.
+3. If still false, set `THINGS_DB_PATH` explicitly to your `main.sqlite`.
+4. If `lastOpenError` indicates permissions, grant your MCP host app (for example Alma) Full Disk Access.
+5. Restart the MCP server and reconnect client.
+
+If `lastOpenError` includes `NODE_MODULE_VERSION` mismatch:
+
+1. Align Node runtime used by MCP host and by local install.
+2. Rebuild native module with that runtime: `pnpm rebuild better-sqlite3`.
+3. In MCP host config, prefer absolute Node path in `command` (for example `/opt/homebrew/bin/node`) instead of plain `node`.
+
+## Tool Safety Notes
+
+- `things_add_area`, `things_add_todo`, `things_add_project`, `things_update_todo`, `things_complete_todo`, `things_move_todo`, and `things_delete_todo` all require `confirm=true`.
+- This server does not execute arbitrary scripts.
+- Reads are done via AppleScript.
+- URL-scheme-supported operations use Things URL scheme (`add_todo`, `add_project`, `update_todo`, `move_todo`, `complete_todo`, `show_item`).
+- AppleScript is used for unsupported write operations (`add_area`, `delete_todo`) and read operations.
+
+## Read Detail Fields
+
+`things_get_todo` returns extended metadata, including:
+
+- `dueDate`, `activationDate`
+- `creationDate`, `modificationDate`, `completionDate`, `cancellationDate`
+- `reminderTime` (best-effort, extracted from private JSON when available)
+- `tagNames`, `project`, `area`, `contactName`
+- `rawJson` (best-effort from Things private experimental JSON field when available)
+
+`things_list_todos`, `things_search_todos`, `things_list_area_items`, and `things_list_project_todos` also return:
+
+- `inferredDate`: fallback date inferred from direct fields or recurring metadata
+- `isRepeating` / `recurrenceRule`: best-effort recurring task hints
+- `recurrence`: structured recurring info (`mode`, `nextDate`, `interval`, `frequency`, `byDay`, `byMonthDay`, `byMonth`, `byWeekNo`, `byYearDay`, `bySetPos`, `byHour`, `byMinute`, `bySecond`, `weekStart`, `count`, `until`, `anchorDate`, `offsets`, `rrule`, `rruleParts`, `rawFields`)
+
+Read path strategy:
+
+- AppleScript is still used to preserve Things list/search semantics.
+- SQLite (read-only) is used to enrich due/start/reminder/recurrence details, especially repeating templates.
+- If SQLite is unavailable, the server automatically falls back to AppleScript-only reads.
+
+Container support:
+
+- `things_add_area` creates a new area.
+- `things_add_project` supports creating projects inside area via `area` or `areaId`.
+- `things_add_todo` supports direct placement via `list/listId` and optional `heading/headingId`.
+- `things_move_todo` supports moving into standard list, project, area, or heading.
+
+## Known Limitations
+
+- AppleScript access requires first-run macOS Automation permission approval.
+- If Things is not running, macOS may launch it during tool execution.
+- URL scheme writes are asynchronous from Things' perspective; tool success means request dispatch succeeded.
+- Advanced recurring metadata is parsed from Things hidden `_private_experimental_ json` and may change across app versions.
+- SQLite recurrence internals (`rt1_*`) are private implementation details and can also change across Things versions.
+- Some repeating tasks may not expose a concrete upcoming date in public fields; in those cases `nextDate` can be empty while `recurrence`/`rawFields` still provide rule details.