@appsoftwareltd/etherpk-mcp 0.7.1 → 0.8.1

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 (4) hide show
  1. package/README.md +193 -143
  2. package/dist/main.js +844 -232
  3. package/dist/main.js.map +1 -1
  4. package/package.json +14 -13
package/README.md CHANGED
@@ -1,25 +1,19 @@
1
1
  # @appsoftwareltd/etherpk-mcp
2
2
 
3
- An [MCP](https://modelcontextprotocol.io) server that gives your AI agent (Claude Code, Codex,
4
- Cursor and the like) one of your [EtherPK](https://etherpk.com) knowledge graphs, run on the same
5
- computer as the agent. The agent can search your notes by words or by meaning, follow links,
6
- list tasks, and read and edit documents without breaking EtherPK's format.
3
+ An [MCP](https://modelcontextprotocol.io) server that gives an AI agent (Claude Code, Codex, Cursor
4
+ and others) one of your [EtherPK](https://etherpk.com) knowledge graphs. It runs on the same
5
+ computer as the agent, which can then search your notes by words or by meaning, follow links, list
6
+ tasks, and read and edit documents without breaking EtherPK's format.
7
7
 
8
- This is EtherPK's **Headless Client**: EtherPK with no editor. Set up depends on where the graph
9
- lives:
10
-
11
- - **A local graph folder.** Point it at the folder. It reads and writes the markdown there and
12
- keeps a search index of it. No sign-in, no server.
13
- - **A synced graph.** EtherPK's Sync Server never sees your notes unencrypted. The Headless
14
- Client signs in as one of your devices, holds your keys, keeps the graph in sync and serves it
15
- from your own computer.
16
-
17
- The agent gets the same tools either way. Protected documents are listed by name only and never
18
- served.
8
+ This package is EtherPK's **Headless Client**: EtherPK without an editor. It serves either a graph
9
+ folder on your computer or a graph synced through a Sync Server, and the agent gets the same tools
10
+ for both. Protected documents are listed by name only and never served.
19
11
 
20
12
  Needs Node.js 22 or later.
21
13
 
22
- ## Set up: a synced graph
14
+ ## Get started
15
+
16
+ ### A synced graph
23
17
 
24
18
  Open the graph in EtherPK, pick **Settings → Agents**, and copy the two commands it shows with your
25
19
  server and graph filled in:
@@ -35,177 +29,233 @@ npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com
35
29
  claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>
36
30
  ```
37
31
 
38
- Self-hosting? Give your own server's address to `login`. By default `login` gets your keys by
39
- Device Approval: confirm the code it shows in EtherPK on any device where your account is
40
- unlocked. If there's no EtherPK to hand, press `r` while `login` is waiting, or add
41
- `--recovery-code`, and type your Recovery Code instead. For a scripted setup, `ETHERPK_PAT` and
42
- `ETHERPK_RECOVERY_CODE` stand in for the prompts.
32
+ ### A local graph folder
33
+
34
+ No sign-in and no Sync Server. **Settings → Agents** shows the command with your folder's path
35
+ filled in once you've recorded the path on the General tab:
43
36
 
44
- `npx @appsoftwareltd/etherpk-mcp graphs` lists the graphs each signed-in account can reach, by
45
- name and id. A graph nobody has opened since names started being stored on the server is opened
46
- once to read its name; `(unnamed)` means it has none.
37
+ ```sh
38
+ claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --folder /path/to/your/notes
39
+ ```
47
40
 
48
- One computer can be signed in to several Sync Servers - your own beside the managed service, say.
49
- Run `login` once per server. `--sync-server` then says which one a command means; it can be left
50
- off while only one is signed in, and the commands the Agents tab shows always include it.
41
+ The folder must already be an EtherPK graph: open it in EtherPK once.
51
42
 
52
- ## Set up: a local graph folder
43
+ ### Ask about your notes
44
+
45
+ The server describes its tools and the graph to the agent, so no skill or extra setup is needed. Ask
46
+ about something you've written down and the agent uses the tools. To make that a rule rather than
47
+ the agent's judgement, add a line to your `CLAUDE.md`, or your agent's equivalent:
48
+
49
+ > My notes live in EtherPK; use the etherpk MCP tools for anything I've written down, and `search`
50
+ > in semantic mode for questions.
51
+
52
+ ## What the agent can do
53
+
54
+ Thirty-two tools, the same over a synced graph and a folder. One running server serves one graph,
55
+ and every tool refuses a protected document.
56
+
57
+ | Group | Tools | Notes |
58
+ | --- | --- | --- |
59
+ | 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. |
60
+ | 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. |
61
+ | 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. |
62
+ | 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. |
63
+ | 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. |
64
+ | 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. |
53
65
 
54
- No sign-in and no Sync Server required. The agent gets the same tools over the folder's
55
- markdown, beside the files themselves, which it can still read and write directly. **Settings → Agents** shows the
56
- command with your folder's path filled in once you've recorded the path on the General tab:
66
+ `read_asset`, `read_theme` and `preview_theme` write only under the graph's **downloads directory**,
67
+ `downloads` inside the graph's folder in the cache directory, and `import_theme_folder` reads only
68
+ from there. An agent names a folder relative to it and gets the full path back; a folder outside it
69
+ is refused, so a prompt hidden in a note cannot steer the agent into writing or reading elsewhere.
70
+ Copy a file out with your own tools when you want it somewhere else.
71
+
72
+ ## Search by meaning
73
+
74
+ `search` matches words. After one setup step it also matches **meaning**: "when do I pay my taxes"
75
+ finds the note that says "due 31 January". A small embedding model runs on this computer; nothing is
76
+ sent anywhere, and protected documents are never embedded.
57
77
 
58
78
  ```sh
59
- claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --folder /path/to/your/notes
79
+ npx @appsoftwareltd/etherpk-mcp semantic setup
80
+ ```
81
+
82
+ Setup installs a native runtime of about 300 MB through your npm, and a 23 MB model, into the cache
83
+ directory, once per computer.
84
+
85
+ - **No restart needed.** A running `serve` checks every 30 seconds and starts building once setup
86
+ has run. Until then a search by meaning is refused, and the message names the setup command so
87
+ the agent can tell you what to run.
88
+ - **Modes.** `search` accepts `mode: "semantic"`, and `"hybrid"` for words and meaning side by side.
89
+ Each result carries the document, its breadcrumb of headings and parent bullets, the passage's
90
+ lines and text, and a similarity score. Passage text has bullet markers and `[[ ]]` removed, so
91
+ quote it, but take the `old` text for `edit_document` from `read_document`.
92
+ - **Progress.** The first pass over a large graph takes minutes and runs in the background; after
93
+ that only changed documents are embedded. Every semantic result reports `embedded`, `total` and
94
+ `complete`, and `semantic status` shows each cached graph.
95
+ - **Only while `serve` runs.** `serve` builds and updates the store, and runs only while an agent
96
+ session has it open. To keep a graph current without an agent, run
97
+ `npx @appsoftwareltd/etherpk-mcp serve --graph <id> </dev/null &` (or `--folder <path>`).
98
+ - **Load.** The model uses a quarter of the cores, at most four, and pauses for a tenth of a second
99
+ between batches. `ETHERPK_MCP_SEMANTIC_THREADS` changes the thread count; set it in the agent
100
+ registration's `env`.
101
+ - **Per agent.** `serve --no-semantic` keeps one registration text-only.
102
+
103
+ ## Synced graphs in detail
104
+
105
+ ### Signing in
106
+
107
+ `login` makes this computer a device of your account:
108
+
109
+ - It asks for an account-wide Personal Access Token, from `<Sync Server>/account/tokens` or
110
+ **Access tokens** in EtherPK's account menu. `--pat` or `ETHERPK_PAT` supplies it instead.
111
+ - It unlocks your keys by Device Approval: it shows a short code, which you confirm in EtherPK in
112
+ any browser signed in to the account with its graphs unlocked.
113
+ - With no EtherPK to hand, press `r` while it waits, or pass `--recovery-code`, and type your
114
+ Recovery Code instead. `ETHERPK_RECOVERY_CODE` supplies the code for a scripted setup.
115
+
116
+ When it is done it lists the graphs the account can reach. For a Sync Server other than EtherPK's,
117
+ give its address to `login`.
118
+
119
+ ### Choosing a graph
120
+
121
+ `graphs` lists the synced graphs each signed-in account can reach, with the name, the id and your
122
+ role. `serve --graph` takes the id or the name. A graph nobody has opened since names were first
123
+ stored on the server is opened once to read its name; `(unnamed)` means it has none.
124
+
125
+ ### Several Sync Servers
126
+
127
+ One computer can be signed in to several Sync Servers. Run `login` once for each. `--sync-server`
128
+ then says which server a command means. It can be left out while only one server is signed in,
129
+ and the commands the Agents tab shows always include it.
130
+
131
+ ## Local folders in detail
132
+
133
+ - The folder must hold `pages/` and `journals/`. `serve` never creates them, so a mistyped path is
134
+ refused rather than turned into an empty graph.
135
+ - Edits made in an editor, or by the agent writing files directly, are picked up before the next
136
+ tool call, and the index follows within a second or so.
137
+ - A tool's write is in the file when the tool returns. If a write fails, the agent is told why and
138
+ the edit is retried on the next write.
139
+ - The index lives under the cache directory, never in the folder. Moving or renaming the folder
140
+ starts the index again.
141
+
142
+ ## Publishing a site
143
+
144
+ `publish` renders one publication of a graph into a folder on this computer and prints the report:
145
+
146
+ ```sh
147
+ npx @appsoftwareltd/etherpk-mcp publish --graph <id or name> --publication <id> --out <dir>
60
148
  ```
61
149
 
62
- The folder must already be an EtherPK graph (open it in EtherPK once). Edits made in an editor,
63
- or by the agent writing files directly, are picked up before the next tool call, and the index
64
- follows within a second or so. A tool's write is in the file when the tool returns; if a write
65
- fails, the agent is told why and the edit is retried on the next write. The index lives under
66
- the cache directory, never in the folder.
150
+ - `--out` is remembered for that graph and publication. Later runs without it, and the agent's
151
+ `publish` tool, write to the same folder. The agent can't choose a folder.
152
+ - In that folder, the top-level `.html` files, `assets/`, `theme/` and the search, feed and report
153
+ files are rewritten, and files that no longer belong are removed. Everything else is left alone.
154
+ - Deploying the folder, with a git push say, is up to you. Run the command from cron for a site that
155
+ republishes itself.
156
+ - Mermaid diagrams need a browser. `diagrams setup` installs a Chromium of about 170 MB into the
157
+ cache directory, once per computer, and a publish whose pages hold diagrams refuses until then.
158
+ `ETHERPK_CHROMIUM` names a Chromium already on the computer instead; NixOS needs this.
159
+ - `list_publications`, or **Settings → Publish** in EtherPK, shows the publication ids.
67
160
 
68
- ## Commands and flags
161
+ ## Reference
69
162
 
70
163
  Every command is `npx @appsoftwareltd/etherpk-mcp <command>`. `npx` never puts `etherpk-mcp` on
71
- your PATH; for the short form, `npm install -g @appsoftwareltd/etherpk-mcp` once. `--help` (`-h`)
72
- prints this reference, `--version` (`-v`) the version.
164
+ your PATH; for the short form, install the package globally once:
165
+
166
+ ```sh
167
+ npm install -g @appsoftwareltd/etherpk-mcp
168
+ ```
169
+
170
+ `--help` (`-h`) prints the command reference and `--version` (`-v`) the version.
171
+
172
+ ### Commands
73
173
 
74
174
  | Command | What it does |
75
175
  | --- | --- |
76
- | `login --sync-server <url> [--pat <token>] [--recovery-code]` | Sign this computer in as a device of your account on that Sync Server. Asks for a Personal Access Token unless given one, then unlocks your keys by Device Approval or, with `--recovery-code`, your Recovery Code. Lists the graphs it can reach when done. |
176
+ | `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. |
77
177
  | `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. |
78
178
  | `serve --graph <id or name> [--sync-server <url>] [--no-semantic]` | Serve one synced graph to the agent over stdio. |
79
- | `serve --folder <path> [--no-semantic]` | Serve a local graph folder the same way. The folder must already be an EtherPK graph. |
80
- | `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, semantic runtime and model included. Revoke the token at the portal too if the computer isn't yours to keep. |
81
- | `semantic setup` | Install the embedding runtime (about 300 MB, through your npm) and the 23 MB model into the cache directory. Once per computer. |
179
+ | `serve --folder <path> [--no-semantic]` | Serve a local graph folder the same way. |
180
+ | `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. |
181
+ | `semantic setup` | Install the embedding runtime and model into the cache directory. |
82
182
  | `semantic status` | Whether semantic search is set up here, and each cached graph's embedding progress. |
83
- | `semantic remove` | Delete the runtime and model. Each graph's stored vectors stay in its cache and are reused if you set up again. |
84
- | `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. `--out` sets the folder for that graph and publication and is remembered: the command without `--out`, and the agent's `publish` tool, write there from then on (the agent can't choose a folder). The folder's owned files (top-level `.html`, `assets/`, `theme/`, the search, feed and report files) are rewritten and their strays removed; everything else is left alone. Writes files; deploying them is yours. |
85
- | `diagrams setup` | Install a Chromium (about 170 MB) into the cache directory so a publish can draw Mermaid diagrams. Once per computer; a publish with diagrams refuses until then. |
183
+ | `semantic remove` | Delete the runtime and model. Each graph's stored embeddings stay in its cache and are reused if you set up again. |
184
+ | `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. |
185
+ | `diagrams setup` | Install a Chromium into the cache directory so a publish can draw Mermaid diagrams. |
86
186
  | `diagrams status` | Which browser a publish would use, if any. |
87
187
 
188
+ ### Flags
189
+
88
190
  | Flag | Applies to | Meaning |
89
191
  | --- | --- | --- |
90
- | `--sync-server <url>` | `login`, `graphs`, `serve --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. |
192
+ | `--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. |
91
193
  | `--pat <token>` | `login` | The Personal Access Token, instead of the prompt. |
92
194
  | `--recovery-code` | `login` | Unlock with your Recovery Code instead of waiting for Device Approval. Pressing `r` while `login` waits does the same. |
93
- | `--graph <id or name>` | `serve` | The synced graph to serve. Exclusive with `--folder`. |
94
- | `--folder <path>` | `serve` | The local graph folder to serve. Exclusive with `--graph` and `--sync-server`. |
195
+ | `--graph <id or name>` | `serve`, `publish` | The synced graph. Not with `--folder`. |
196
+ | `--folder <path>` | `serve`, `publish` | The local graph folder. Not with `--graph` or `--sync-server`. |
95
197
  | `--no-semantic` | `serve` | Keep this agent text-only even when semantic search is set up. |
96
198
  | `--all` | `logout` | Every server at once. |
97
- | `--publication <id>` | `publish` | Which publication of the graph. `list_publications` and Settings → Publish show the ids. |
199
+ | `--publication <id>` | `publish` | Which publication of the graph. |
98
200
  | `--out <dir>` | `publish` | Where the site goes on this computer. Remembered for the graph and publication. |
99
201
 
100
- | Environment variable | Meaning |
202
+ ### Environment variables
203
+
204
+ | Variable | Meaning |
101
205
  | --- | --- |
102
- | `ETHERPK_PAT` | Stands in for the token prompt, for a scripted `login`. |
103
- | `ETHERPK_RECOVERY_CODE` | Stands in for the Recovery Code prompt, for a scripted `login --recovery-code`. |
104
- | `ETHERPK_MCP_CONFIG` | The config file holding the logins. Default `~/.config/etherpk/mcp.json` (`XDG_CONFIG_HOME` respected). |
105
- | `ETHERPK_MCP_CACHE_DIR` | The cache root for graphs, the semantic runtime and the model. Default `~/.cache/etherpk/mcp` (`XDG_CACHE_HOME` respected). Set it in the agent registration's `env` as well as your shell: the agent starts `serve` with its own environment. |
206
+ | `ETHERPK_PAT` | The Personal Access Token, for a scripted `login`. |
207
+ | `ETHERPK_RECOVERY_CODE` | The Recovery Code, for a scripted `login --recovery-code`. |
208
+ | `ETHERPK_MCP_CONFIG` | The file holding the logins. Default `~/.config/etherpk/mcp.json`, under `XDG_CONFIG_HOME` when that is set. |
209
+ | `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. |
210
+ | `ETHERPK_MCP_PUBLISH_CONFIG` | The file remembering each publication's publish folder. Default `publish.json` beside the login file. |
106
211
  | `ETHERPK_MCP_SEMANTIC_THREADS` | Threads for the embedding model. Default a quarter of the cores, at most four. |
107
- | `ETHERPK_MCP_DEBUG_MEMORY` | `1` logs the process's memory use every 10 seconds and on every progress line. |
108
- | `ETHERPK_MCP_PUBLISH_CONFIG` | The file remembering each publication's publish folder. Default `publish.json` beside the config file. |
109
- | `ETHERPK_CHROMIUM` | A Chromium on this computer for drawing diagrams, instead of the one `diagrams setup` installs. NixOS needs this. |
110
-
111
- ## What the agent gets
112
-
113
- Thirty-two tools, the same over a synced graph and a folder. Reading: `graph_info`,
114
- `list_documents` (with a range of journal days), `read_document` (the body as text, the
115
- frontmatter as data), `read_documents`, `search`, `backlinks`, `tasks`, `list_assets`,
116
- `read_asset`, `list_publications`. Writing: `edit_document` (an exact, unique old→new
117
- replacement; on a synced graph it merges with anyone typing elsewhere on the page),
118
- `append_document` (a page, or a day's journal entry, created if needed), `create_page`,
119
- `set_frontmatter` (`public`, `publications`, `date`, any key; never the title or aliases),
120
- `set_task`, `set_aliases`, `plan_rename` and `rename` (scoped concepts carried along, links
121
- rewritten by default, a merge only when confirmed), `upload_asset` (returns the markdown to
122
- paste), `create_publication`, `update_publication` and `publish` (into the folder you set with
123
- the `publish` command; it can't choose one). Themes: `list_themes`, `read_theme` and
124
- `read_theme_file` (a theme's files out to disk to edit), `create_theme` and
125
- `customise_publication_theme` (a copy in the graph, since a bundled theme is never edited in
126
- place), `write_theme_file`, `delete_theme_file`, `import_theme_folder`, `delete_theme`, and
127
- `preview_theme` (a rendered site to inspect, with screenshots when a browser is set up). A
128
- protected document is refused by every one of them. One running instance serves one graph.
129
-
130
- No skill or extra setup is needed: the server describes its tools and the graph, and Claude Code
131
- reaches for them when you ask about your notes. To make that a rule rather than a good guess, add
132
- one line to your `CLAUDE.md`: *"My notes live in EtherPK; use the etherpk MCP tools for anything
133
- I've written down, and `search` in semantic mode for questions."*
134
-
135
- ## Searching by meaning
136
-
137
- `search` matches words. With one more step it also matches **meaning** - "when do I pay my taxes"
138
- finds the note that says "due 31 January" - by running a small embedding model on this computer.
139
- Nothing is sent anywhere, and protected documents are never embedded.
140
-
141
- ```sh
142
- npx @appsoftwareltd/etherpk-mcp semantic setup
143
- ```
212
+ | `ETHERPK_CHROMIUM` | A Chromium on this computer for drawing diagrams, instead of the one `diagrams setup` installs. |
213
+ | `PLAYWRIGHT_BROWSERS_PATH` | Where `diagrams setup` installs Chromium and a publish looks for it. Default `browsers/` in the cache directory. |
214
+ | `ETHERPK_MCP_DEBUG_MEMORY` | `1` logs the process's memory use every 10 seconds and with every progress line. |
144
215
 
145
- - **Any order, no restart.** Run it before or after registering the agent, even while one is
146
- connected: a running `serve` notices within 30 seconds and starts building. Until then a
147
- search by meaning is refused with this command in the message, so the agent can tell you what
148
- to run.
149
- - **What changes.** `search` accepts `mode: "semantic"` (and `"hybrid"`, both groups side by
150
- side). Each result carries the document, the breadcrumb of headings and parent bullets, the
151
- passage's line range and its text with a similarity score. Passage text has bullet markers and
152
- `[[ ]]` stripped, so it's right for quoting and wrong as the `old` text of `edit_document`,
153
- which should come from `read_document`.
154
- - **Progress.** The first pass over a large graph takes minutes, in the background; after that
155
- only edits are processed. Every semantic result says `embedded` / `total` and `complete`, and
156
- `semantic status` shows each cached graph's progress.
157
- - **Only while it runs.** The store is built and kept current by `serve`, which exists only while
158
- an agent session has it open. To keep a graph current without an agent, run it by hand:
159
- `npx @appsoftwareltd/etherpk-mcp serve --graph <id> </dev/null &` (or `--folder <path>`).
160
- - **Load.** The first pass uses a quarter of the cores, at most four, and pauses between model
161
- calls. `ETHERPK_MCP_SEMANTIC_THREADS=8` in the registration's `env` makes it faster and hotter.
216
+ ## What stays on your computer
162
217
 
163
- ## What this client keeps on your computer
218
+ - **Keys** in the login file, `~/.config/etherpk/mcp.json`, one entry per Sync Server, readable only
219
+ by your user: the same trust as a browser you've signed in on.
220
+ - **A cache of each synced graph you serve** under `~/.cache/etherpk/mcp/`, so a restart fetches what
221
+ changed rather than everything. It holds your notes readably, as a signed-in browser's storage
222
+ does. The Sync Server stays the source of truth: each start asks it what changed, edits made
223
+ elsewhere arrive as they happen, and a newer version of this package discards a cache it can't
224
+ read and rebuilds it.
225
+ - **For a folder**, only its index and, once semantic search is set up, its embeddings, under
226
+ `local/<folder name>-<hash of its path>/` in the cache directory. Nothing is written into the
227
+ folder.
164
228
 
165
- - **Keys** in `~/.config/etherpk/mcp.json`, one entry per Sync Server, readable only by your
166
- user - the same trust as a browser you've signed in on.
167
- - **A cache of each synced graph you serve** under `~/.cache/etherpk/mcp/`, so a restart fetches
168
- what changed rather than everything. It holds your notes readably, as a signed-in browser's
169
- storage does. It's never the source of truth: on every start the Sync Server is asked what
170
- moved, edits made elsewhere arrive as they happen, and a newer version of this program
171
- discards a cache it no longer understands and rebuilds it.
172
- - **For a folder**, only its index and (once set up) its vectors, under
173
- `local/<folder name>-<hash of its path>/` in the same cache directory. Nothing is written into
174
- the folder. Moving or renaming the folder starts the index over.
229
+ On Windows both directories are under your user folder: `C:\Users\<you>\.config\etherpk\` and
230
+ `C:\Users\<you>\.cache\etherpk\`.
175
231
 
176
- On Windows both paths sit under your user folder: `C:\Users\<you>\.config\etherpk\` and
177
- `C:\Users\<you>\.cache\etherpk\`. Revoke the token at the portal to cut an agent off; `logout`
178
- forgets the keys and deletes the cache on this computer.
232
+ To cut an agent off, revoke its Personal Access Token on the Sync Server. `logout` forgets the token
233
+ and keys on this computer and deletes that server's cached graphs.
179
234
 
180
- ## Building and publishing
235
+ ## Build from source
181
236
 
182
- From the EtherPK monorepo (`apps/mcp`). The bundle compiles the Client's own sync, crypto and
183
- index code in through a `$lib` alias, so it builds from the repo, not from this folder alone:
237
+ The package lives at `apps/mcp` in the etherpk-client repository. It compiles the Client's sync,
238
+ crypto and index code in through a `$lib` alias, so it builds from the repository root, not from
239
+ this folder alone:
184
240
 
185
241
  ```sh
186
- pnpm install # once, at the repo root
187
- pnpm --filter @appsoftwareltd/etherpk-mcp check # type-check
242
+ pnpm install --frozen-lockfile
243
+ pnpm --filter @appsoftwareltd/etherpk-mcp check # type check
188
244
  pnpm --filter @appsoftwareltd/etherpk-mcp test # unit tests, no server needed
189
245
  pnpm --filter @appsoftwareltd/etherpk-mcp build # dist/main.js; run it with node dist/main.js
190
246
  ```
191
247
 
192
- To release, bump `version` in `package.json` (the CLI reads it from there), then from `apps/mcp`
193
- in a real terminal, since both the login and the publish need a one-time code:
248
+ Releases are published to npm by the repository's CI, at the same version as the Client. To check
249
+ that a version is on the registry:
194
250
 
195
251
  ```sh
196
- npm whoami || npm login # needs publish rights on @appsoftwareltd
197
- pnpm publish --access public --no-git-checks # prepack builds; pnpm rewrites workspace:* deps
198
- npx -y @appsoftwareltd/etherpk-mcp@<version> --version # verify, once the registry lists it
252
+ npx -y @appsoftwareltd/etherpk-mcp@<version> --version
199
253
  ```
200
254
 
201
- From outside the `apps/mcp` directory:
202
-
203
- ```sh
204
- npx -y @appsoftwareltd/etherpk-mcp@<version> --version # verify, once the registry lists it
205
- ```
255
+ ## Documentation and licence
206
256
 
207
- The end-to-end specs in `tests-sync/agents/` build and drive this bundle against a real Sync
208
- Server and a real folder; the technical notes are in the repo under
209
- `docs/docs/technical/Headless Client.md`.
257
+ The full guide is [Using AI agents with your notes](https://docs.etherpk.com/using-ai-agents-with-your-notes).
210
258
 
211
- Full guide: <https://docs.etherpk.com/using-ai-agents-with-your-notes>.
259
+ The package is available under the Elastic License 2.0 ([LICENSE](LICENSE)): you may use, copy,
260
+ modify and self-host it, but not offer it to others as a hosted or managed service. It is
261
+ source-available, not open source.