mindwtr-mcp 1.0.5 → 1.1.2

package/README.md

@@ -1,8 +1,8 @@
 # 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 in read-only mode.
+MCP server for Mindwtr. Connect MCP clients (Claude Desktop, etc.) to either your local Mindwtr SQLite database or a self-hosted Mindwtr Cloud endpoint.
 
-This is a **stdio** server (no hosted HTTP endpoint). MCP clients launch it as a subprocess and talk over JSON-RPC on stdin/stdout.
+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.
 
 ---
 
@@ -21,7 +21,7 @@ On desktop, the app shows the exact local data path in **Settings -> Sync -> Loc
 - Node.js 18+ (for the MCP client that spawns the server)
 - 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 read-only Cloud mode
+- 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`
@@ -74,11 +74,11 @@ 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 against a local database.
+The npm package is read-only by default. Add `--write` only when you explicitly want add/update/complete/delete tools enabled.
 
-### Read-only self-hosted Cloud mode
+### Self-hosted Cloud mode
 
-Use Cloud mode when you run your own Mindwtr Cloud server and want MCP read tools without pointing the helper at a local SQLite database:
+Use Cloud mode when you run your own Mindwtr Cloud server and want MCP tools without pointing the helper at a local SQLite database:
 
 ```bash
 npx -y mindwtr-mcp \
@@ -94,12 +94,31 @@ MINDWTR_MCP_CLOUD_TOKEN="$MINDWTR_TOKEN" \
 npx -y mindwtr-mcp
 ```
 
-Cloud mode uses the self-hosted Cloud API and is always read-only. It reads the current `/v1/data` snapshot, exposes task/project/section/area/person read tools through MCP, and returns `read_only` for write tools. Do not pass `--write` with `--cloud-url`.
+Cloud mode uses the self-hosted Cloud API. Reads come from the current `/v1/data` snapshot; with `--write`, task/project/section/area writes go through the Cloud server's per-resource REST endpoints (`POST /v1/tasks`, `PATCH /v1/tasks/:id`, and so on), so they get the same validation and revision stamping as any other client. Without `--write`, write tools return `read_only`. Person edits and restoring deleted tasks are not available in Cloud mode yet.
 
 This does not make Mindwtr Cloud itself a hosted MCP server. It is still the same stdio helper, backed by a Cloud URL that you operate.
 
 For private HTTP test deployments, local/private HTTP URLs are allowed by the shared Cloud client rules. Use `--cloud-allow-insecure-http=true` only for a self-hosted endpoint you intentionally trust.
 
+### 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).
+
+```bash
+mindwtr-mcp --http --http-token "$(openssl rand -hex 32)" --db "/path/to/mindwtr.db"
+```
+
+Flags (all have `MINDWTR_MCP_HTTP*` env var equivalents):
+
+- `--http` / `MINDWTR_MCP_HTTP` — enable HTTP mode. Also implied by setting `--http-host`, `--http-port`, or `--http-token`.
+- `--http-token <token>` / `MINDWTR_MCP_HTTP_TOKEN` — **required** whenever HTTP mode is on, at least 16 characters. Generate one with `openssl rand -hex 32`. The server refuses to start without it — there is no way to expose HTTP mode unauthenticated, even on loopback.
+- `--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.
+
+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.
+
 ### Run directly from the repo
 
 ```bash