mindwtr-mcp 1.1.10 → 1.1.12

package/README.md

@@ -1,6 +1,6 @@
 # Mindwtr MCP Server
 
-MCP server for Mindwtr. Connect MCP clients (Claude Desktop, etc.) to either your local Mindwtr SQLite database or a self-hosted Mindwtr Cloud endpoint.
+MCP server for Mindwtr. Connect MCP clients (Claude Desktop, etc.) to your local SQLite database, the desktop Local API, or a self-hosted Mindwtr Cloud endpoint.
 
 By default this is a **stdio** server: MCP clients launch it as a subprocess and talk over JSON-RPC on stdin/stdout. It also has an opt-in **HTTP transport** (see [Remote access (HTTP)](#remote-access-http)) for self-hosters who want to expose it at a URL instead.
 
@@ -8,22 +8,24 @@ By default this is a **stdio** server: MCP clients launch it as a subprocess and
 
 ## App Binaries vs. MCP Helper
 
-The desktop and mobile app binaries include the Mindwtr app, but they do **not** currently include a desktop start/stop toggle or a standalone `mindwtr-mcp` command on your `PATH`.
+The desktop app includes a built-in MCP server in **Settings → Integrations → Local MCP server (advanced)**. It requires no separately installed runtime or helper. The desktop installer does not add a standalone `mindwtr-mcp` command to your `PATH`; mobile apps do not host MCP.
 
-You do **not** need to run the whole app from source to use MCP. You can use the normal desktop app binary for your tasks, then run this separate MCP helper from the repository with Bun, or build the helper once and run it with Node. Point the helper at the desktop app's local `mindwtr.db`.
+You do **not** need to run the whole app from source to use MCP. You can use the normal desktop app binary for your tasks, then run this separate MCP helper from the repository with Bun, or build the helper once and run it with Node. Point the helper at the desktop app's local `mindwtr.db`, or use the Local API backend below.
 
-On desktop, the app shows the exact local data path in **Settings -> Sync -> Local Data**. Mobile binaries do not expose a local MCP server surface.
+On desktop, find the database in the default database locations listed under [Requirements](#requirements). Mobile binaries do not expose a local MCP server surface.
 
 ---
 
 ## Requirements
 
+These requirements apply to the standalone helper, not the built-in desktop 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.
+- Node-based SQLite mode uses the optional better-sqlite3 native addon. API-only installs can omit it with `--omit=optional`. 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
+- A local database (`mindwtr.db`) for SQLite mode, a running desktop Local API and bearer token for API mode, or a self-hosted Mindwtr Cloud URL and bearer token for Cloud mode
 
-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`:
+For **SQLite mode 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`:
 
 ```bash
 npx --allow-scripts=better-sqlite3 -y mindwtr-mcp --db "/path/to/mindwtr.db"
@@ -34,7 +36,7 @@ In MCP client configurations using `npx`, add `"--allow-scripts=better-sqlite3"`
 
 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`)
+- Linux: `~/.local/share/mindwtr/mindwtr.db` (Flatpak: `~/.var/app/tech.dongdongbh.mindwtr/data/mindwtr/mindwtr.db`; Snap: `~/snap/mindwtr/current/.local/share/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`
@@ -47,7 +49,7 @@ Additional macOS paths for sandboxed builds:
 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.
+The desktop data folder is the folder that holds `mindwtr.db` in the default locations above.
 
 You can override local mode with:
 - `--db /path/to/mindwtr.db`
@@ -91,6 +93,49 @@ Or let an MCP client launch it through npx:
 
 The npm package is read-only by default. Add `--write` only when you explicitly want add/update/complete/delete tools enabled.
 
+### Desktop Local API mode
+
+> Requires mindwtr-mcp 1.1.11 or later.
+
+Enable the desktop app's **Local API** in Settings and copy its bearer token. Keep the app and API running. This backend uses the app's REST endpoints and never opens a database or falls back to SQLite.
+
+For an API-only installation, omit the optional native SQLite addon:
+
+```bash
+npm install -g --omit=optional mindwtr-mcp
+```
+
+Configure your MCP client to pass the token through its environment, rather than putting it in command-line arguments:
+
+```json
+{
+  "command": "mindwtr-mcp",
+  "args": ["--api-url", "http://127.0.0.1:3456"],
+  "env": {
+    "MINDWTR_MCP_API_TOKEN": "<token from desktop settings>"
+  }
+}
+```
+
+Use the port shown in Settings. `MINDWTR_MCP_API_URL` can replace `--api-url`. URLs must use literal `127.0.0.1` or `[::1]`, with no credentials, path, query or fragment; redirects are refused. Do not combine API and Cloud/`--db` options. Existing database-path environment variables are ignored in API mode.
+
+Writes remain disabled unless explicitly enabled with `--write`. If the app is closed or the token is invalid, the helper returns an error. A timed-out write may have reached the app: inspect the task before retrying, as the helper does not retry writes automatically.
+
+| MCP capability | Desktop Local API support |
+| --- | --- |
+| List/get tasks | Supported, including rich search operators, date filters, sorting and pagination |
+| Create tasks | Explicit title and fields; `quickAdd` is unavailable |
+| Update/complete/delete/restore tasks | Supported through the API's corresponding endpoints; terminal status changes cannot be submitted as ordinary edits |
+| List/get/create/update/delete projects | Supported for the API's basic project fields: title, color, status, Area and sequential behavior |
+| List areas | Supported |
+| Sections, managed people, Area writes | Unavailable; these tools are hidden in API mode |
+| GTD availability `view` | Unavailable because the API does not expose the required section snapshot |
+| Replacing attachment links | Unavailable because the API does not provide conditional attachment updates |
+
+Other unsupported fields are rejected before a write. The desktop API's recurrence limitations also apply; some recurring completions must be performed in the app. This backend does not promise full SQLite/Cloud tool parity.
+
+`--api-url` selects the helper's **data source**. `--http` instead selects how an MCP client connects **to the helper**; it can be used with any backend and has a separate authentication token.
+
 ### Self-hosted Cloud mode
 
 Use Cloud mode when you run your own Mindwtr Cloud server and want MCP tools without pointing the helper at a local SQLite database:
@@ -117,7 +162,7 @@ For private HTTP test deployments, local/private HTTP URLs are allowed by the sh
 
 ### Remote access (HTTP)
 
-By default `mindwtr-mcp` only speaks stdio. Pass `--http` to also (instead of stdio) serve a stateless streamable-HTTP MCP endpoint, so you can point a remote MCP client at a URL — the motivating case is [Gemini Spark](https://gemini.google.com) "custom apps", which take an MCP server URL. HTTP mode works with either backend (local SQLite or self-hosted Cloud).
+By default `mindwtr-mcp` only speaks stdio. Pass `--http` to also (instead of stdio) serve a stateless streamable-HTTP MCP endpoint, so you can point a remote MCP client at a URL — the motivating case is [Gemini Spark](https://gemini.google.com) "custom apps", which take an MCP server URL. HTTP mode works with all three backends.
 
 ```bash
 mindwtr-mcp --http --http-token "$(openssl rand -hex 32)" --db "/path/to/mindwtr.db"
@@ -130,6 +175,8 @@ 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 desktop app's built-in MCP server also uses port `8722`. If it is on, pass another port with `--http-port`, for example `--http-port 8723`.
+
 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 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.
@@ -222,7 +269,13 @@ mindwtr-mcp --db "/path/to/mindwtr.db"
 
 ### Desktop app toggle?
 
-Not yet. Start/stop is still manual.
+The desktop app has **Settings → Integrations → Local MCP server (advanced)**. Access is disabled and read-only by default. Enable it and copy connection details for a client supporting authenticated Streamable HTTP at `http://127.0.0.1:8722/mcp`. Configuration syntax depends on the client; stdio-only clients can continue using this standalone helper.
+
+Enable **Allow changes** only to permit creating, editing, and deleting tasks and projects, including completing tasks. Connected AI clients can read exposed Mindwtr data and may send it to their provider. Keep the copied bearer token private; regenerating it disconnects old clients.
+
+The built-in server runs inside the desktop app and shares its task and project operations with the Local API. You do not need to enable the Local API. Closing to the tray keeps it running; disabling MCP or quitting stops it. A startup failure or occupied port is shown in Settings with Retry. The app must stay available. This mode does not provide remote ChatGPT access, a tunnel, or hosting, and has the same supported operations as the Local API backend above.
+
+Source builds compile the built-in server with the desktop Rust application; no separate MCP executable or runtime is bundled.
 
 ---
 
@@ -537,6 +590,8 @@ claude mcp add mindwtr -- \
 
 ## Safety & Concurrency
 
+The SQLite details below apply to direct database mode. Local API mode uses the desktop app's native handlers, and Cloud mode uses the self-hosted server.
+
 - The server uses **SQLite WAL mode**. Read-only tools can run while the desktop app is open.
 - Write tools fail fast on SQLite writer locks, then retry the whole Mindwtr write operation. Each retry reloads current data before applying the requested change, so a delayed MCP write does not keep working from a stale pre-lock snapshot.
 - Writes are **disabled by default**. Use `--write` to enable edits.