@appsoftwareltd/etherpk-mcp 0.2.0 → 0.4.0

package/README.md

@@ -1,12 +1,14 @@
 # @appsoftwareltd/etherpk-mcp
 
-The EtherPK **Headless Client**: an [MCP](https://modelcontextprotocol.io) server over one of
-your synced [EtherPK](https://etherpk.com) knowledge graphs, run on the same computer as your AI
-agent (Claude Code, Codex, Cursor and the like).
+An [MCP](https://modelcontextprotocol.io) server that gives your AI agent (Claude Code, Codex,
+Cursor and the like) one of your synced [EtherPK](https://etherpk.com) knowledge graphs, run on
+the same computer as the agent.
 
-EtherPK's Sync Server never sees your notes in the clear, so nothing hosted can serve them to an
-agent. This program signs in as one of your devices, holds your keys, keeps one graph in sync and
-speaks MCP to the agent beside it. Protected documents are listed by name and never served.
+EtherPK's Sync Server never sees your notes in the clear, so nothing hosted can serve them. This
+program is EtherPK's **Headless Client**: to the Sync Server it is one of your devices - so it can
+hold your keys, read a graph and keep it in sync. To your agent, it is an MCP server.
+
+Protected documents are listed by name only, never served.
 
 Needs Node.js 22 or later.
 
@@ -31,11 +33,30 @@ npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com
 #   npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com --recovery-code
 
 # Tell the agent about the graph (Claude Code shown; the Agents tab has the others).
-claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --graph <graph id>
+claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>
+```client
+
+`npx @appsoftwareltd/etherpk-mcp graphs` lists the graphs each signed-in account can reach, by
+name and id. For a scripted setup, `ETHERPK_PAT` and `ETHERPK_RECOVERY_CODE` stand in for the
+prompts.
+
+## More than one Sync Server
+
+One computer can be signed in to several Sync Servers at once - your own self-hosted one beside
+the managed service, say. Run `login` once per server; every login lives in the one config file.
+`--sync-server <url>` then says which server a command means:
+
+```sh
+npx @appsoftwareltd/etherpk-mcp login  --sync-server https://sync.your-domain.example
+npx @appsoftwareltd/etherpk-mcp graphs                                   # every server, in turn
+npx @appsoftwareltd/etherpk-mcp serve  --sync-server https://sync.your-domain.example --graph <graph id>
+npx @appsoftwareltd/etherpk-mcp logout --sync-server https://sync.your-domain.example
 ```
 
-`npx @appsoftwareltd/etherpk-mcp graphs` lists the graphs the token can reach, by name and id.
-For a scripted setup, `ETHERPK_PAT` and `ETHERPK_RECOVERY_CODE` stand in for the prompts.
+While only one server is signed in, `--sync-server` can be left off `graphs`, `serve` and
+`logout`. With two or more, `serve` and `logout` refuse to guess and ask for it. The commands
+the Agents tab shows always include it, so they stay right whatever else the computer is signed
+in to. `logout --all` forgets every server at once.
 
 Every command runs through `npx`, which fetches the package but never puts `etherpk-mcp` on your
 PATH. If you'd rather type the short form, `npm install -g @appsoftwareltd/etherpk-mcp` once and
@@ -48,10 +69,44 @@ unique old→new replacement that merges with anyone typing elsewhere on the pag
 `append_document` (a page, or a day's journal entry, created if needed) and `create_page`.
 One running instance serves one graph.
 
-## What it keeps on your computer
+## Searching by meaning
+
+`search` matches words. With one more step it can also match **meaning** - "when do I pay my
+taxes" finds the note that says "due 31 January" - by running a small embedding model on this
+computer; nothing is sent anywhere, and protected documents are never embedded. Once per
+computer:
+
+```sh
+npx @appsoftwareltd/etherpk-mcp semantic setup     # ~300 MB runtime (via your npm) + a 23 MB model, into the cache dir
+```
 
-- **Keys**: `~/.config/etherpk/mcp.json`, readable only by your user - the same trust as a browser
-  you've signed in on.
+Semantic setup installs the native runtime into `~/.cache/etherpk/mcp/runtime/` and the three
+model files into `~/.cache/etherpk/mcp/models/all-MiniLM-L6-v2-int8/`.
+
+- **Any order, no restart.** Run it before or after registering the agent, even while an agent
+  is connected: a running `serve` notices within 30 seconds and starts building; until
+  then a search by meaning is refused with this command in the message, so the agent can tell
+  you what to run. Nothing in the registration changes (`--no-semantic` on `serve` is the only
+  switch, to keep one agent text-only).
+- **What the agent gets.** `search` accepts `mode: "semantic"` (and `"hybrid"`, both groups
+  side by side). Every result carries the document, its kind, the breadcrumb of headings and
+  parent bullets, the passage's 0-based line range and its text with a similarity score - the
+  agent is told to cite them. Passage text has bullet markers and `[[ ]]` stripped: right for
+  quoting, wrong as the `old` text of `edit_document`, which should come from `read_document`.
+- **Progress.** The first pass over a large graph takes minutes and runs in the background;
+  after that only edits are processed. `semantic status` lists each cached graph with how many
+  passages are done; every semantic result says `embedded`/`total` and `complete`; run by
+  hand, `serve` prints a line every 30 seconds. `semantic remove` deletes runtime and model.
+- **One cache directory for both.** Setup and `serve` must see the same cache root - by default
+  `~/.cache/etherpk/mcp` (`C:\Users\<you>\.cache\etherpk\mcp` on Windows). If you set
+  `ETHERPK_MCP_CACHE_DIR` in your shell, put it in the agent registration's `env` too, since
+  the agent spawns `serve` with its own environment.
+
+## What this client keeps on your computer
+
+- **Keys**: `~/.config/etherpk/mcp.json`, one entry per Sync Server, readable only by your user -
+  the same trust as a browser you've signed in on. (On Windows both paths sit under your user
+  folder: `C:\Users\<you>\.config\etherpk\` and `C:\Users\<you>\.cache\etherpk\`.)
 - **A cache of each graph you serve**: `~/.cache/etherpk/mcp/`, so a restart catches up on what
   changed instead of downloading everything again. It holds your notes readably, like a signed-in
   browser's own storage does. It is never the source of truth: on every start the Sync Server is
@@ -59,7 +114,8 @@ One running instance serves one graph.
   newer version of this program discards a cache it no longer understands and rebuilds it.
 
 Revoke the token at the portal to cut the agent off, and `npx @appsoftwareltd/etherpk-mcp logout`
-to forget the keys and delete the cache on that computer.
+to forget that server's keys and delete its cache on that computer (`--all` for every server,
+which also removes the semantic runtime and model).
 
 ## Building and publishing