@appsoftwareltd/etherpk-mcp 0.9.2 → 0.9.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +160 -131
  2. package/dist/main.js +14894 -12105
  3. package/dist/main.js.map +1 -1
  4. package/dist/map-picture-page.js +292 -0
  5. package/package.json +9 -6
package/README.md CHANGED
@@ -3,13 +3,13 @@
3
3
  [![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/m9vScxQzvp)
4
4
 
5
5
  An [MCP](https://modelcontextprotocol.io) server that gives an AI agent (Claude Code, Codex, Cursor
6
- and others) one of your [EtherPK](https://etherpk.com) knowledge graphs. It runs on the same
7
- computer as the agent, which can then search your notes by words or by meaning, follow links, list
8
- tasks, and read and edit documents without breaking EtherPK's format.
6
+ and others) one of your [EtherPK](https://etherpk.com) knowledge graphs. It runs on the agent's
7
+ computer. The agent can search your notes by words or by meaning, follow links, list tasks, and
8
+ read and edit documents without breaking EtherPK's format.
9
9
 
10
- This package is EtherPK's **Headless Client**: EtherPK without an editor. It serves either a graph
11
- folder on your computer or a graph synced through a Sync Server, and the agent gets the same tools
12
- for both. Protected documents are listed by name only and never served.
10
+ This package is EtherPK's **Headless Client**, EtherPK without an editor. It serves a graph folder
11
+ on your computer or a graph synced through a Sync Server, with the same tools for both. Protected
12
+ documents are listed by name only and never served.
13
13
 
14
14
  Needs Node.js 24 or later.
15
15
 
@@ -17,134 +17,147 @@ Needs Node.js 24 or later.
17
17
 
18
18
  ### A synced graph
19
19
 
20
- Open the graph in EtherPK, pick **Settings → Agents**, and copy the two commands it shows with your
21
- server and graph filled in:
20
+ In EtherPK, open the graph's **Settings → Agents** and select **Make a setup code**. The tab shows
21
+ two commands with your server, the code and the graph filled in. On your own Sync Server, the tab
22
+ links to the server's **Access tokens** page, which makes the code.
22
23
 
23
24
  ```sh
24
- # Once per computer. Asks for an account-wide Personal Access Token (from
25
- # https://sync.etherpk.com/account/tokens, or "Access tokens" in EtherPK's account menu),
26
- # then shows a short code once a browser tab where EtherPK is unlocked answers. Approve there
27
- # if the tab shows the same code, then press y here. The same step as adding a phone.
28
- npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com
25
+ # Once per computer. When this terminal and an unlocked EtherPK tab show the same code,
26
+ # approve in the tab, then press y here.
27
+ npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com --code <setup code>
29
28
 
30
- # Tell the agent about the graph (Claude Code shown - the Agents tab has the others).
29
+ # Register the graph with your agent (Claude Code shown, the Agents tab has the others).
31
30
  claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>
32
31
  ```
33
32
 
34
33
  ### A local graph folder
35
34
 
36
- No sign-in and no Sync Server. **Settings → Agents** shows the command with your folder's path
37
- filled in once you've recorded the path on the General tab:
35
+ No sign-in and no Sync Server:
38
36
 
39
37
  ```sh
40
38
  claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --folder /path/to/your/notes
41
39
  ```
42
40
 
43
- The folder must already be an EtherPK graph: open it in EtherPK once.
41
+ The folder must already be an EtherPK graph, so open it in EtherPK once. **Settings → Agents**
42
+ shows this command with the path filled in once the folder's path is set on the General tab.
44
43
 
45
44
  ### Ask about your notes
46
45
 
47
- The server describes its tools and the graph to the agent, so no skill or extra setup is needed. Ask
48
- about something you've written down and the agent uses the tools. To make that a rule rather than
49
- the agent's judgement, add a line to your `CLAUDE.md`, or your agent's equivalent:
46
+ The server describes its tools and the graph to the agent, so nothing else needs setting up. To
47
+ make the agent always use them, add a line like this to your `CLAUDE.md`, or your agent's
48
+ equivalent:
50
49
 
51
- > My notes are stored in EtherPK - use the etherpk MCP tools for anything I've written down, and `search`
52
- > in semantic mode for questions.
50
+ > My notes are stored in EtherPK. Use the etherpk MCP tools for anything I've written down, and
51
+ > `search` in semantic mode for questions.
53
52
 
54
53
  ## What the agent can do
55
54
 
56
- Thirty-two tools, the same over a synced graph and a folder. One running server serves one graph,
57
- and every tool refuses a protected document.
55
+ Thirty-six tools, the same for a synced graph and a folder. Each `serve` serves one graph, and
56
+ every tool refuses a protected document.
58
57
 
59
58
  | Group | Tools | Notes |
60
59
  | --- | --- | --- |
61
- | Find and read | `graph_info`, `list_documents`, `read_document`, `read_documents`, `search`, `backlinks`, `tasks` | `list_documents` can narrow to a range of journal days. `read_document` returns the body as text and the frontmatter as data. |
62
- | Edit | `edit_document`, `append_document`, `create_page`, `set_task`, `set_frontmatter`, `set_aliases` | `edit_document` replaces one exact, unique piece of text - on a synced graph it merges with edits made elsewhere at the same time. `append_document` creates a day's journal entry when there is none. `set_frontmatter` sets any key except `title`, `aliases` and `publication`, which have tools of their own. |
63
- | Tasks handed over | `read_task`, `add_task_note`, `set_task` | A person copies a task reference in EtherPK and pastes it to the agent. The server's instructions describe what a reference looks like and name these tools, so a pasted one needs no explanation. `read_task` returns the task and what is nested under it, `set_task` takes the reference in place of a document and line, and `add_task_note` writes a note under the task. The reference finds the task after lines are added above it or its tags change, and refuses once its words change. |
64
- | Rename | `plan_rename`, `rename` | Links to the old name are rewritten by default and scoped concepts move with it. Renaming onto a name that is taken merges two documents and needs confirming. |
65
- | Images and files | `upload_asset`, `read_asset`, `list_assets` | `upload_asset` returns the markdown to paste into a document. It refuses hidden files and folders (`.ssh`, `.env`), the Headless Client's own config and cache, and files over 100 MiB. `read_asset` writes an asset to a local file. |
66
- | Publishing | `list_publications`, `create_publication`, `update_publication`, `publish` | `publish` writes into the folder you set with the `publish` command - the agent can't choose one. |
67
- | Themes | `list_themes`, `read_theme`, `read_theme_file`, `create_theme`, `customise_publication_theme`, `write_theme_file`, `delete_theme_file`, `import_theme_folder`, `delete_theme`, `preview_theme` | Bundled themes are read-only - customising one copies it into the graph. `preview_theme` renders a site to inspect, with screenshots when a browser is set up. |
68
-
69
- `read_asset`, `read_theme` and `preview_theme` write only under the graph's **downloads directory**,
70
- `downloads` inside the graph's folder in the cache directory, and `import_theme_folder` reads only
71
- from there. An agent names a folder relative to it and gets the full path back - a folder outside it
72
- is refused, so a prompt hidden in a note cannot steer the agent into writing or reading elsewhere.
73
- Copy a file out with your own tools when you want it somewhere else.
60
+ | Find and read | `graph_info`, `list_documents`, `read_document`, `read_documents`, `search`, `backlinks`, `tasks`, `graph_insights`, `graph_path` | `list_documents` can narrow to a range of journal days. `graph_insights` lists the most-linked concepts, clusters and bridges, and `graph_path` finds how two concepts connect. |
61
+ | Edit | `edit_document`, `append_document`, `create_page`, `set_task`, `set_frontmatter`, `set_aliases` | `edit_document` replaces one exact, unique piece of text, and on a synced graph it merges with edits made elsewhere. `append_document` creates the day's journal entry when there is none. |
62
+ | Tasks handed over | `read_task`, `add_task_note`, `set_task` | Paste the agent a task reference copied in EtherPK. The reference still finds the task after lines are added above it, and refuses once the task's words change. |
63
+ | Rename | `plan_rename`, `rename` | Links to the old name are rewritten. Renaming onto a name in use merges two documents and needs confirming. |
64
+ | Images and files | `upload_asset`, `read_asset`, `list_assets` | `upload_asset` returns the markdown to paste into a document. It refuses hidden files and folders (`.ssh`, `.env`), the Headless Client's own config and cache, and files over 100 MiB. |
65
+ | Publishing | `list_publications`, `create_publication`, `update_publication`, `publish` | `publish` writes to the folder set with the `publish` command. The agent can't choose one. |
66
+ | Themes | `list_themes`, `read_theme`, `read_theme_file`, `create_theme`, `customise_publication_theme`, `write_theme_file`, `delete_theme_file`, `import_theme_folder`, `delete_theme`, `preview_theme` | Bundled themes are read-only, and customising one copies it into the graph. `preview_theme` renders a site, with screenshots when a browser is set up. |
67
+
68
+ `read_asset`, `read_theme` and `preview_theme` write only in the graph's `downloads` folder in the
69
+ cache directory, and `import_theme_folder` reads only from there. A folder outside it is refused,
70
+ so a prompt hidden in a note cannot steer the agent into writing or reading elsewhere.
71
+
72
+ ## Several agents on one graph
73
+
74
+ Any number of agents can use one graph at once. The first `serve` for a graph starts a background
75
+ process that holds the graph, and every `serve` passes its agent's requests to it, so there is one
76
+ copy of the graph in memory and one index on disk.
77
+
78
+ - The agent's session starts at once. A tool called before the graph has opened waits for it.
79
+ - The process saves the graph and stops five minutes after its last agent has gone
80
+ (`ETHERPK_MCP_HOST_IDLE_SECONDS`). An agent still connected starts a new one on its next request.
81
+ - `running` lists the processes with their agents and logs, and `stop` ends them.
82
+ - If the process stops during a request, the agent is told the request may or may not have been
83
+ applied. A request that never reached it goes to the next process.
84
+ - With no graph to serve (not logged in, or a folder that is not a graph yet), the agent stays
85
+ connected and each tool answers `graph_unavailable` with the reason. A request 10 seconds or
86
+ more later tries again, so fixing the cause needs no restart.
87
+ - The process logs to `host.log` in the graph's cache directory. `publish` runs in the same
88
+ process.
74
89
 
75
90
  ## Search by meaning
76
91
 
77
- `search` matches words. After one setup step it also matches **meaning**: "when do I pay my taxes"
78
- finds the note that says "due 31 January". A small embedding model runs on this computer - nothing is
79
- sent anywhere, and protected documents are never embedded.
92
+ `search` matches words. After one setup step it also matches meaning, so "when do I pay my taxes"
93
+ finds the note that says "due 31 January". A small embedding model runs on this computer. Nothing
94
+ is sent anywhere, and protected documents are never embedded.
80
95
 
81
96
  ```sh
82
97
  npx @appsoftwareltd/etherpk-mcp semantic setup
83
98
  ```
84
99
 
85
- Setup installs a native runtime of about 300 MB through your npm, and a 23 MB model, into the cache
100
+ Setup installs a native runtime of about 300 MB (through your npm) and a 23 MB model into the cache
86
101
  directory, once per computer.
87
102
 
88
- - **No restart needed.** A running `serve` checks every 30 seconds and starts building once setup
89
- has run. Until then a search by meaning is refused, and the message names the setup command so
90
- the agent can tell you what to run.
91
- - **Modes.** `search` accepts `mode: "semantic"`, and `"hybrid"` for words and meaning side by side.
92
- Each result carries the document, its breadcrumb of headings and parent bullets, the passage's
93
- lines and text, and a similarity score. Passage text has bullet markers and `[[ ]]` removed, so
94
- quote it, but take the `old` text for `edit_document` from `read_document`.
95
- - **Progress.** The first pass over a large graph takes minutes and runs in the background - after
96
- that only changed documents are embedded. Every semantic result reports `embedded`, `total` and
97
- `complete`, and `semantic status` shows each cached graph.
98
- - **Only while `serve` runs.** `serve` builds and updates the store, and runs only while an agent
99
- session has it open. To keep a graph current without an agent, run
103
+ - **No restart.** A graph's background process checks every 30 seconds and starts embedding once
104
+ setup has run. Until then a search by meaning is refused, and the message names the setup command.
105
+ - **Modes.** `search` takes `mode: "semantic"`, or `"hybrid"` for words and meaning together. Each
106
+ result has the document, its breadcrumb of headings and parent bullets, the passage and a
107
+ similarity score.
108
+ - **Progress.** The first pass over a large graph takes minutes and runs in the background. After
109
+ that only changed documents are embedded. Results report `embedded`, `total` and `complete`, and
110
+ `semantic status` shows each cached graph.
111
+ - **When it runs.** Only while the graph's background process runs, which is while an agent has
112
+ the graph open and for five minutes after. To keep a graph current without an agent, run
100
113
  `npx @appsoftwareltd/etherpk-mcp serve --graph <id> </dev/null &` (or `--folder <path>`).
101
- - **Load.** The model uses a quarter of the cores, at most four, and pauses for a tenth of a second
102
- between batches. `ETHERPK_MCP_SEMANTIC_THREADS` changes the thread count - set it in the agent
114
+ - **Load.** The model uses a quarter of the cores, at most four, and pauses a tenth of a second
115
+ between batches. `ETHERPK_MCP_SEMANTIC_THREADS` changes the thread count. Set it in the agent
103
116
  registration's `env`.
104
117
  - **Per agent.** `serve --no-semantic` keeps one registration text-only.
105
118
 
106
- ## Synced graphs in detail
119
+ ## Synced graphs
107
120
 
108
121
  ### Signing in
109
122
 
110
- `login` makes this computer a device of your account:
123
+ `login` makes this computer a device of your account.
111
124
 
112
- - It asks for an account-wide Personal Access Token, from `<Sync Server>/account/tokens` or
113
- **Access tokens** in EtherPK's account menu. `--pat` or `ETHERPK_PAT` supplies it instead. The
114
- token can reset your encryption keys, which deletes the graphs you own, so keep it as safe as
115
- your password.
116
- - It unlocks your keys by Device Approval. Open EtherPK in a browser signed in to the account with
117
- its keys unlocked. Once that browser answers, both show the same short code. Select **Approve** in
118
- the browser, then press `y` in the terminal. Press `n` if the codes differ, which cancels the
119
- request.
120
- - With no EtherPK to hand, press `r` while it waits, or pass `--recovery-code`, and type your
121
- Recovery Code instead. `ETHERPK_RECOVERY_CODE` supplies the code for a scripted setup.
125
+ - **The token.** `--code` trades a setup code for an agent token. Make the code in a synced graph's
126
+ **Settings → Agents** in EtherPK, or on the Sync Server's **Access tokens** page, where the token
127
+ is then listed as "Agent on <computer name>". An agent token can read and write your graphs. It
128
+ cannot reset or replace your Encryption Keys, make tokens, invite people or delete graphs. It
129
+ stops working after 30 days unused, when you revoke it, and when you reset your Encryption Keys.
130
+ - **For a script**, or a Sync Server too old for setup codes, `--pat` or `ETHERPK_PAT` gives an
131
+ account-wide access token instead. `login` unlocks with it, then swaps it for an agent token and
132
+ revokes it.
133
+ - **The keys** are unlocked by Device Approval. Open EtherPK in a browser where the account's
134
+ Encryption Keys are unlocked. When the browser and the terminal show the same short code, select
135
+ **Approve** in the browser and press `y` in the terminal. Press `n` if the codes differ.
136
+ - **Without EtherPK to hand**, press `r` while `login` waits, or pass `--recovery-code`, and type
137
+ your Recovery Code. `ETHERPK_RECOVERY_CODE` supplies it for a scripted setup.
122
138
 
123
- When it is done it lists the graphs the account can reach. For a Sync Server other than EtherPK's,
124
- give its address to `login`.
139
+ `login` then lists the graphs the account can reach.
125
140
 
126
141
  ### Choosing a graph
127
142
 
128
143
  `graphs` lists the synced graphs each signed-in account can reach, with the name, the id and your
129
- role. `serve --graph` takes the id or the name. A graph nobody has opened since names were first
130
- stored on the server is opened once to read its name - `(unnamed)` means it has none.
144
+ role. `serve --graph` takes the id or the name. `(unnamed)` means a graph has no name yet.
131
145
 
132
146
  ### Several Sync Servers
133
147
 
134
- One computer can be signed in to several Sync Servers. Run `login` once for each. `--sync-server`
135
- then says which server a command means. It can be left out while only one server is signed in,
136
- and the commands the Agents tab shows always include it.
148
+ Run `login` once for each Sync Server. `--sync-server` then says which server a command means. It
149
+ can be left out while only one server is signed in.
137
150
 
138
- ## Local folders in detail
151
+ ## Local folders
139
152
 
140
153
  - The folder must hold `pages/` and `journals/`. `serve` never creates them, so a mistyped path is
141
154
  refused rather than turned into an empty graph.
142
155
  - Edits made in an editor, or by the agent writing files directly, are picked up before the next
143
156
  tool call, and the index follows within a second or so.
144
- - A tool's write is in the file when the tool returns. If a write fails, the agent is told why and
145
- the edit is retried on the next write.
146
- - The index is stored under the cache directory, never in the folder. Moving or renaming the folder
147
- starts the index again.
157
+ - A tool's write is in the file when the tool returns. A failed write is reported to the agent and
158
+ retried on the next write.
159
+ - The index is kept in the cache directory, never in the folder. Moving or renaming the folder
160
+ starts a new index.
148
161
 
149
162
  ## Publishing a site
150
163
 
@@ -155,91 +168,104 @@ npx @appsoftwareltd/etherpk-mcp publish --graph <id or name> --publication <id>
155
168
  ```
156
169
 
157
170
  - `--out` is remembered for that graph and publication. Later runs without it, and the agent's
158
- `publish` tool, write to the same folder. The agent can't choose a folder.
159
- - In that folder, the top-level `.html` files, `assets/`, `theme/` and the search, feed and report
160
- files are rewritten, and files that no longer belong are removed. Everything else is left alone.
161
- - Deploying the folder, with a git push say, is up to you. Run the command from cron for a site that
162
- republishes itself.
163
- - Mermaid diagrams need a browser. `diagrams setup` installs a Chromium of about 170 MB into the
164
- cache directory, once per computer, and a publish whose pages hold diagrams refuses until then.
165
- `ETHERPK_CHROMIUM` names a Chromium already on the computer instead - NixOS needs this.
171
+ `publish` tool, write to the same folder.
172
+ - The top-level `.html` files, `assets/`, `theme/` and the search, feed and report files are
173
+ rewritten, and files that no longer belong are removed. Everything else in the folder is left
174
+ alone.
175
+ - Deploying the folder is up to you. Run the command from cron for a site that republishes itself.
176
+ - Mermaid diagrams and maps need a browser. A map is published as a picture of the map, drawn over
177
+ EtherPK's map host unless `ETHERPK_MAP_STYLE_URL` names another style. `diagrams setup` installs a
178
+ Chromium of about 170 MB into the cache directory, once per computer, and a publish whose pages
179
+ hold diagrams or maps refuses until then. `ETHERPK_CHROMIUM` names a Chromium already on the
180
+ computer instead, which NixOS needs.
166
181
  - `list_publications`, or **Settings → Publish** in EtherPK, shows the publication ids.
167
182
 
168
183
  ## Reference
169
184
 
170
- Every command is `npx @appsoftwareltd/etherpk-mcp <command>`. `npx` never puts `etherpk-mcp` on
171
- your PATH - for the short form, install the package globally once:
172
-
173
- ```sh
174
- npm install -g @appsoftwareltd/etherpk-mcp
175
- ```
176
-
177
- `--help` (`-h`) prints the command reference and `--version` (`-v`) the version.
185
+ Every command is `npx @appsoftwareltd/etherpk-mcp <command>`. For the short form, `etherpk-mcp`,
186
+ install the package globally once with `npm install -g @appsoftwareltd/etherpk-mcp`. `--help`
187
+ (`-h`) prints the command reference and `--version` (`-v`) the version.
178
188
 
179
189
  ### Commands
180
190
 
181
191
  | Command | What it does |
182
192
  | --- | --- |
183
- | `login --sync-server <url> [--pat <token>] [--recovery-code]` | Sign this computer in as a device of your account on that Sync Server, unlock your keys, and list the graphs the account can reach. |
184
- | `graphs [--sync-server <url>]` | List the synced graphs each signed-in account can reach, by name, id and your role. Without `--sync-server`, every signed-in server in turn. |
193
+ | `login --sync-server <url> [--code <setup code>] [--recovery-code]` | Sign this computer in as a device of your account, unlock your Encryption Keys, and list the graphs the account can reach. |
194
+ | `graphs [--sync-server <url>]` | List the synced graphs each signed-in account can reach, with name, id and your role. |
185
195
  | `serve --graph <id or name> [--sync-server <url>] [--no-semantic]` | Serve one synced graph to the agent over stdio. |
186
196
  | `serve --folder <path> [--no-semantic]` | Serve a local graph folder the same way. |
187
- | `logout [--sync-server <url> \| --all]` | Forget that server's token and keys and delete its cached graphs. `--all` forgets every server and clears the whole cache, the semantic runtime and model included. |
197
+ | `running` | List the graphs served on this computer, with each one's background process, agents and log. |
198
+ | `stop [--graph <id or name> [--sync-server <url>] \| --folder <path> \| --all]` | Save a graph and end its background process, or every graph's when none is named. |
199
+ | `logout [--sync-server <url> \| --all]` | Revoke that server's token, forget it and the Encryption Keys, stop its graphs' background processes and delete its cached graphs. `--all` does this for every server and clears the whole cache, the semantic runtime and model included. |
188
200
  | `semantic setup` | Install the embedding runtime and model into the cache directory. |
189
- | `semantic status` | Whether semantic search is set up here, and each cached graph's embedding progress. |
190
- | `semantic remove` | Delete the runtime and model. Each graph's stored embeddings stay in its cache and are reused if you set up again. |
191
- | `publish (--graph <id or name> \| --folder <path>) --publication <id> [--out <dir>]` | Publish one publication of a graph to a folder on this computer and print the report. |
192
- | `diagrams setup` | Install a Chromium into the cache directory so a publish can draw Mermaid diagrams. |
201
+ | `semantic status` | Whether semantic search is set up, and each cached graph's embedding progress. |
202
+ | `semantic remove` | Delete the runtime and model. Stored embeddings stay, and are reused if you set up again. |
203
+ | `publish (--graph <id or name> \| --folder <path>) --publication <id> [--out <dir>]` | Publish one publication of a graph to a folder and print the report. |
204
+ | `diagrams setup` | Install a Chromium into the cache directory, so a publish can draw Mermaid diagrams and maps. |
193
205
  | `diagrams status` | Which browser a publish would use, if any. |
194
206
 
195
207
  ### Flags
196
208
 
197
209
  | Flag | Applies to | Meaning |
198
210
  | --- | --- | --- |
199
- | `--sync-server <url>` | `login`, `graphs`, `serve --graph`, `publish --graph`, `logout` | Which Sync Server the command means. Required for `login` - elsewhere optional while only one server is signed in. `serve` and `logout` refuse to guess when several are. |
200
- | `--pat <token>` | `login` | The Personal Access Token, instead of the prompt. |
201
- | `--recovery-code` | `login` | Unlock with your Recovery Code instead of waiting for Device Approval. Pressing `r` while `login` waits does the same. |
202
- | `--graph <id or name>` | `serve`, `publish` | The synced graph. Not with `--folder`. |
203
- | `--folder <path>` | `serve`, `publish` | The local graph folder. Not with `--graph` or `--sync-server`. |
211
+ | `--sync-server <url>` | `login`, `graphs`, `serve --graph`, `publish --graph`, `stop --graph`, `logout` | Which Sync Server the command means. Required for `login`, and elsewhere optional while only one server is signed in. `serve` and `logout` refuse to guess between several. |
212
+ | `--code <setup code>` | `login` | The one-time setup code. It works once, within 10 minutes. |
213
+ | `--pat <token>` | `login` | An account-wide access token instead of a setup code. `login` swaps it for an agent token and revokes it. |
214
+ | `--recovery-code` | `login` | Unlock with your Recovery Code instead of Device Approval. Pressing `r` while `login` waits does the same. |
215
+ | `--graph <id or name>` | `serve`, `publish`, `stop` | The synced graph. Not with `--folder`. |
216
+ | `--folder <path>` | `serve`, `publish`, `stop` | The local graph folder. Not with `--graph` or `--sync-server`. |
204
217
  | `--no-semantic` | `serve` | Keep this agent text-only even when semantic search is set up. |
205
- | `--all` | `logout` | Every server at once. |
218
+ | `--all` | `logout`, `stop` | Every server, or every graph. |
206
219
  | `--publication <id>` | `publish` | Which publication of the graph. |
207
- | `--out <dir>` | `publish` | Where the site goes on this computer. Remembered for the graph and publication. |
220
+ | `--out <dir>` | `publish` | Where the site goes. Remembered for the graph and publication. |
208
221
 
209
222
  ### Environment variables
210
223
 
224
+ Set a variable that `serve` should see in the agent registration's `env` as well as your shell,
225
+ because the agent starts `serve` with its own environment.
226
+
211
227
  | Variable | Meaning |
212
228
  | --- | --- |
213
- | `ETHERPK_PAT` | The Personal Access Token, for a scripted `login`. |
214
- | `ETHERPK_RECOVERY_CODE` | The Recovery Code, for a scripted `login --recovery-code`. |
215
- | `ETHERPK_MCP_CONFIG` | The file holding the logins. Default `~/.config/etherpk/mcp.json`, under `XDG_CONFIG_HOME` when that is set. |
216
- | `ETHERPK_MCP_CACHE_DIR` | The cache directory for graphs, the semantic runtime and the model. Default `~/.cache/etherpk/mcp`, under `XDG_CACHE_HOME` when that is set. Set it in the agent registration's `env` as well as your shell: the agent starts `serve` with its own environment. |
217
- | `ETHERPK_MCP_PUBLISH_CONFIG` | The file remembering each publication's publish folder. Default `publish.json` beside the login file. |
229
+ | `ETHERPK_PAT` | An account-wide access token for a scripted `login`, swapped for an agent token and revoked. |
230
+ | `ETHERPK_RECOVERY_CODE` | The Recovery Code for a scripted `login --recovery-code`. |
231
+ | `ETHERPK_MCP_SECRETS` | `file` keeps the agent token and Encryption Keys in the login file even where there is a keychain. |
232
+ | `ETHERPK_MCP_CONFIG` | The login file. Default `~/.config/etherpk/mcp.json`, or under `XDG_CONFIG_HOME` when that is set. |
233
+ | `ETHERPK_MCP_CACHE_DIR` | The cache directory for graphs, the semantic runtime and the model. Default `~/.cache/etherpk/mcp`, or under `XDG_CACHE_HOME` when that is set. |
234
+ | `ETHERPK_MCP_PUBLISH_CONFIG` | The file that remembers each publication's folder. Default `publish.json` beside the login file. |
218
235
  | `ETHERPK_MCP_SEMANTIC_THREADS` | Threads for the embedding model. Default a quarter of the cores, at most four. |
219
- | `ETHERPK_CHROMIUM` | A Chromium on this computer for drawing diagrams, instead of the one `diagrams setup` installs. |
236
+ | `ETHERPK_MCP_HOST_IDLE_SECONDS` | How long a graph's background process stays after its last agent has gone. Default 300. |
237
+ | `ETHERPK_CHROMIUM` | A Chromium on this computer for drawing diagrams and maps, instead of the one `diagrams setup` installs. |
238
+ | `ETHERPK_MAP_STYLE_URL` | The MapLibre style a published map's picture is drawn over. Default EtherPK's map host; empty draws maps on a plain background. |
220
239
  | `PLAYWRIGHT_BROWSERS_PATH` | Where `diagrams setup` installs Chromium and a publish looks for it. Default `browsers/` in the cache directory. |
221
240
  | `ETHERPK_MCP_DEBUG_MEMORY` | `1` logs the process's memory use every 10 seconds and with every progress line. |
222
241
 
223
242
  ## What stays on your computer
224
243
 
225
- - **Keys** in the login file, `~/.config/etherpk/mcp.json`, one entry per Sync Server, readable only
226
- by your user: the same trust as a browser you've signed in on.
227
- - **A cache of each synced graph you serve** under `~/.cache/etherpk/mcp/`, so a restart fetches what
228
- changed rather than everything. It holds your notes readably, as a signed-in browser's storage
229
- does. The Sync Server stays the source of truth: each start asks it what changed, edits made
230
- elsewhere arrive as they happen, and a newer version of this package discards a cache it can't
231
- read and rebuilds it.
232
- - **For a folder**, only its index and, once semantic search is set up, its embeddings, under
244
+ - **The agent token and your Encryption Keys.** They go in the system keychain where `login` can
245
+ use one: the macOS Keychain, or a Linux desktop's keyring through `secret-tool` (the
246
+ `libsecret-tools` package on Debian and Ubuntu). The login file, `~/.config/etherpk/mcp.json`,
247
+ then names only the server. Otherwise they are in the login file, readable only by your user,
248
+ like a signed-in browser's storage. `login` says which. Any program running as you can ask the
249
+ keychain for them, so run only agents you trust with your account, and never let one read, print
250
+ or search `~/.config/etherpk`.
251
+ - **A cache of each synced graph you serve**, under `~/.cache/etherpk/mcp/`, so a restart fetches
252
+ only what changed. It holds your notes readably. The Sync Server stays the source of truth, and a
253
+ newer version of this package rebuilds a cache it can't read.
254
+ - **For a folder**, its index and, with semantic search, its embeddings, under
233
255
  `local/<folder name>-<hash of its path>/` in the cache directory. Nothing is written into the
234
256
  folder.
257
+ - **Beside each graph's cache**, `host.json` while its background process runs, and `host.log`,
258
+ which names the graph's documents and is deleted with the cache. The process listens on a socket
259
+ in a directory only your user can open (`$XDG_RUNTIME_DIR/etherpk-mcp`, or `etherpk-mcp-<uid>` in
260
+ the temporary directory), or on Windows on a named pipe with a random name.
235
261
 
236
- On Windows both directories are under your user folder: `C:\Users\<you>\.config\etherpk\` and
262
+ On Windows the login file and the cache are under `C:\Users\<you>\.config\etherpk\` and
237
263
  `C:\Users\<you>\.cache\etherpk\`.
238
264
 
239
- To cut an agent off, revoke its Personal Access Token on the Sync Server. `logout` forgets the token
240
- and keys on this computer and deletes that server's cached graphs. If the computer or its login file
241
- may have been copied, also replace your keys in EtherPK with **Replace keys and lock out other
242
- devices**: the keys saved there then no longer open your account.
265
+ To cut an agent off, revoke its agent token on the Sync Server's **Access tokens** page. `logout`
266
+ revokes the token itself and deletes the keys and cached graphs on this computer. If the computer
267
+ or its login file may have been copied, also select **Replace Encryption Keys and lock out other
268
+ devices** in EtherPK, so the keys saved there no longer open your account.
243
269
 
244
270
  ## Build from source
245
271
 
@@ -251,11 +277,11 @@ this folder alone:
251
277
  pnpm install --frozen-lockfile
252
278
  pnpm --filter @appsoftwareltd/etherpk-mcp check # type check
253
279
  pnpm --filter @appsoftwareltd/etherpk-mcp test # unit tests, no server needed
254
- pnpm --filter @appsoftwareltd/etherpk-mcp build # dist/main.js - run it with node dist/main.js
280
+ pnpm --filter @appsoftwareltd/etherpk-mcp build # dist/main.js, run with node dist/main.js
255
281
  ```
256
282
 
257
- Releases are published to npm by the repository's CI, at the same version as the Client. To check
258
- that a version is on the registry:
283
+ The repository's CI publishes each release to npm, at the same version as the Client. To check that
284
+ a version is on the registry:
259
285
 
260
286
  ```sh
261
287
  npx -y @appsoftwareltd/etherpk-mcp@<version> --version
@@ -264,6 +290,9 @@ npx -y @appsoftwareltd/etherpk-mcp@<version> --version
264
290
  ## Documentation and licence
265
291
 
266
292
  The full guide is [Using AI agents with your notes](https://docs.etherpk.com/using-ai-agents-with-your-notes).
293
+ What changed in each release is in the
294
+ [changelog](https://github.com/appsoftwareltd/etherpk-client/blob/main/CHANGELOG.md), which covers
295
+ this package and the EtherPK Client, released together under one version.
267
296
 
268
297
  The package is available under the Elastic License 2.0 ([LICENSE](LICENSE)): you may use, copy,
269
298
  modify and self-host it, but not offer it to others as a hosted or managed service. It is