mindwtr-mcp 1.1.8 → 1.1.10

package/README.md

@@ -18,18 +18,33 @@ On desktop, the app shows the exact local data path in **Settings -> Sync -> Loc
 
 ## Requirements
 
-- Node.js 18+ (for the MCP client that spawns the server)
+- Node.js 20+ to run the helper. Prefer Node.js 22+ for prebuilt SQLite binaries on supported platforms; Node 20 requires a native build toolchain.
 - npm package installs use better-sqlite3, a native SQLite addon. If no prebuilt binary is available for your platform, npm needs a working C/C++ build toolchain and Python for node-gyp.
 - Bun (recommended for development in this repo)
 - A local Mindwtr database (`mindwtr.db`) for local mode, or a self-hosted Mindwtr Cloud URL and bearer token for Cloud mode
 
-Default database locations:
-- Linux: `~/.local/share/mindwtr/mindwtr.db`
-- macOS: `~/Library/Application Support/mindwtr/mindwtr.db`
-- Windows: `%APPDATA%\mindwtr\mindwtr.db`
+With **npm 12**, approve the SQLite dependency's install script; otherwise a successful install can still fail at startup with a missing native binding. For `npx` or global installs, allow only `better-sqlite3`:
 
-Additional macOS path for sandboxed builds:
-- `~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/mindwtr.db`
+```bash
+npx --allow-scripts=better-sqlite3 -y mindwtr-mcp --db "/path/to/mindwtr.db"
+npm install -g --allow-scripts=better-sqlite3 mindwtr-mcp
+```
+
+In MCP client configurations using `npx`, add `"--allow-scripts=better-sqlite3"` before `"mindwtr-mcp"` in `args`. For an existing project-local install, run `npm install-scripts approve better-sqlite3`, then `npm rebuild better-sqlite3` from that project. Review the dependency before approving; do not enable all dependency scripts.
+
+Default database locations. The installed Windows and macOS apps keep the database in a `data` subfolder from version 1.3.2 on; Linux and the portable builds are unchanged. The server looks in both places, so it finds the database either way.
+
+- Linux: `~/.local/share/mindwtr/mindwtr.db` (Flatpak: `~/.var/app/tech.dongdongbh.mindwtr/data/mindwtr/mindwtr.db`)
+- macOS, 1.3.2 and later: `~/Library/Application Support/mindwtr/data/mindwtr.db`
+- macOS, 1.3.1 and earlier: `~/Library/Application Support/mindwtr/mindwtr.db`
+- Windows, 1.3.2 and later: `%APPDATA%\mindwtr\data\mindwtr.db`
+- Windows, 1.3.1 and earlier: `%APPDATA%\mindwtr\mindwtr.db`
+
+Additional macOS paths for sandboxed builds:
+- 1.3.2 and later: `~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/data/mindwtr.db`
+- 1.3.1 and earlier: `~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/mindwtr.db`
+
+A `--db` path pinned in an MCP client configuration keeps working across that move: if the file is not at the configured path, the server checks the matching `data` subfolder (or the parent folder) and reports on stderr which database it opened.
 
 If `mindwtr.db` is missing but `data.json` exists in the same desktop data folder, the MCP server will bootstrap a fresh SQLite database from that local data snapshot on first start.
 Desktop Settings → Sync → Local Data shows the exact storage location used by the app.
@@ -115,9 +130,9 @@ Flags (all have `MINDWTR_MCP_HTTP*` env var equivalents):
 - `--http-host <host>` / `MINDWTR_MCP_HTTP_HOST` — bind address, default `127.0.0.1`.
 - `--http-port <port>` / `MINDWTR_MCP_HTTP_PORT` — bind port, default `8722`.
 
-The MCP endpoint is `POST /mcp` and requires `Authorization: Bearer <token>` on every request; `GET /healthz` returns `200 ok` without auth for reverse-proxy health checks. Requests without a valid token get `401`; bodies over 1 MiB get `413`. When HTTP mode is on, the server does not also connect a stdio transport — it stays alive as long as the HTTP server is listening, not stdin.
+The MCP endpoint is `POST /mcp` and requires `Authorization: Bearer <token>` on every request; `GET /healthz` returns `200 ok` without auth for reverse-proxy health checks. Requests without a valid token get `401`; repeated authentication failures get `429` with a `Retry-After` header. Bodies over 1 MiB get `413`. When HTTP mode is on, the server does not also connect a stdio transport — it stays alive as long as the HTTP server is listening, not stdin.
 
-There is no built-in TLS termination or rate limiting. If you're exposing this beyond localhost, put a reverse proxy (e.g. Caddy, nginx) in front for TLS and put the resulting `https://` URL (plus your token) into the remote MCP client.
+There is no built-in TLS termination or rate limiting for authenticated requests. If you're exposing this beyond localhost, put a reverse proxy (e.g. Caddy, nginx) in front for TLS and put the resulting `https://` URL (plus your token) into the remote MCP client.
 
 ### Run directly from the repo
 
@@ -389,7 +404,8 @@ Any MCP-compatible client can work as long as it can launch a **stdio** server w
 ## Tools
 
 - `mindwtr_list_tasks`
-  - Input: `{ status?, projectId?, includeDeleted?, limit?, offset?, search?, dueDateFrom?, dueDateTo?, sortBy?, sortOrder? }`
+  - Input: `{ status?, projectId?, includeDeleted?, limit?, offset?, search?, dueDateFrom?, dueDateTo?, isFocusedToday?, view?, sortBy?, sortOrder? }`
+  - `view` narrows by GTD availability: `available`, `deferred` or `blocked`
 - `mindwtr_list_projects`
   - Input: `{}`
 - `mindwtr_get_project`
@@ -407,11 +423,12 @@ Any MCP-compatible client can work as long as it can launch a **stdio** server w
 - `mindwtr_get_task`
   - Input: `{ id, includeDeleted? }`
 - `mindwtr_add_task` **(requires `--write`)**
-  - Input: `{ title? | quickAdd?, status?, projectId?, sectionId?, areaId?, dueDate?, startTime?, reviewAt?, recurrence?, contexts?, tags?, description?, priority?, energyLevel?, assignedTo?, timeEstimate?, taskMode?, relativeStartOffset?, showFutureRecurrence?, pushCount?, checklist?, textDirection?, location?, isFocusedToday?, timeSpentMinutes?, suppressMindwtrReminders?, repeatReminderMinutes?, attachments? }`
+  - Input: `{ title? | quickAdd?, status?, projectId?, sectionId?, areaId?, dueDate?, startTime?, cancelledAt?, reviewAt?, recurrence?, contexts?, tags?, description?, priority?, energyLevel?, assignedTo?, timeEstimate?, taskMode?, relativeStartOffset?, showFutureRecurrence?, pushCount?, checklist?, textDirection?, location?, isFocusedToday?, timeSpentMinutes?, suppressMindwtrReminders?, repeatReminderMinutes?, attachments? }`
 - `mindwtr_update_task` **(requires `--write`)**
-  - Input: `{ id, title?, status?, projectId?, sectionId?, areaId?, dueDate?, startTime?, reviewAt?, recurrence?, contexts?, tags?, description?, priority?, energyLevel?, assignedTo?, timeEstimate?, taskMode?, relativeStartOffset?, showFutureRecurrence?, pushCount?, checklist?, textDirection?, location?, isFocusedToday?, timeSpentMinutes?, suppressMindwtrReminders?, repeatReminderMinutes?, order?, boardOrder?, focusOrder?, attachments? }`
+  - Input: `{ id, title?, status?, projectId?, sectionId?, areaId?, dueDate?, startTime?, cancelledAt?, reviewAt?, recurrence?, contexts?, tags?, description?, priority?, energyLevel?, assignedTo?, timeEstimate?, taskMode?, relativeStartOffset?, showFutureRecurrence?, pushCount?, checklist?, textDirection?, location?, isFocusedToday?, timeSpentMinutes?, suppressMindwtrReminders?, repeatReminderMinutes?, order?, boardOrder?, focusOrder?, attachments? }`
   - `recurrence` accepts a recurrence object or an RFC 5545 RRULE string. Pass `null` to clear it.
   - `attachments` holds link attachments only (`{ id?, title?, uri }`, e.g. `obsidian://`, `file://` or `https://`). The list you pass is the complete set of links: links you leave out are removed, file attachments are never touched, and `null` clears every link.
+  - `cancelledAt` is an ISO timestamp with timezone. Setting it closes the task as cancelled (`archived`) without counting it as completed or generating its next recurrence. Moving it to an active status or completing it clears cancellation. Update every syncing client before using cancellation; older writers can discard the marker.
 - `mindwtr_complete_task` **(requires `--write`)**
   - Input: `{ id }`
 - `mindwtr_delete_task` **(requires `--write`)**
@@ -419,9 +436,9 @@ Any MCP-compatible client can work as long as it can launch a **stdio** server w
 - `mindwtr_restore_task` **(requires `--write`)**
   - Input: `{ id }`
 - `mindwtr_add_project` **(requires `--write`)**
-  - Input: `{ title, color?, status?, areaId?, isSequential?, isFocused?, dueDate?, startDate?, reviewAt?, supportNotes?, attachments? }`
+  - Input: `{ title, color?, status?, areaId?, isSequential?, isFocused?, dueDate?, startDate?, cancelledAt?, reviewAt?, supportNotes?, attachments? }`
 - `mindwtr_update_project` **(requires `--write`)**
-  - Input: `{ id, title?, color?, status?, areaId?, isSequential?, isFocused?, dueDate?, startDate?, reviewAt?, supportNotes?, attachments? }`
+  - Input: `{ id, title?, color?, status?, areaId?, isSequential?, isFocused?, dueDate?, startDate?, cancelledAt?, reviewAt?, supportNotes?, attachments? }`
   - `attachments` follows the same rule as `mindwtr_update_task`: link attachments only, the list is the complete set of links, and `null` clears them.
 - `mindwtr_delete_project` **(requires `--write`)**
   - Input: `{ id }`