@appsoftwareltd/etherpk-mcp 0.8.3 → 0.8.5

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 +19 -16
  2. package/dist/main.js +789 -247
  3. package/dist/main.js.map +1 -1
  4. package/package.json +3 -3
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # @appsoftwareltd/etherpk-mcp
2
2
 
3
+ [![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/m9vScxQzvp)
4
+
3
5
  An [MCP](https://modelcontextprotocol.io) server that gives an AI agent (Claude Code, Codex, Cursor
4
6
  and others) one of your [EtherPK](https://etherpk.com) knowledge graphs. It runs on the same
5
7
  computer as the agent, which can then search your notes by words or by meaning, follow links, list
@@ -25,7 +27,7 @@ server and graph filled in:
25
27
  # unlocked. The same step as adding a phone.
26
28
  npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com
27
29
 
28
- # Tell the agent about the graph (Claude Code shown; the Agents tab has the others).
30
+ # Tell the agent about the graph (Claude Code shown - the Agents tab has the others).
29
31
  claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>
30
32
  ```
31
33
 
@@ -46,7 +48,7 @@ The server describes its tools and the graph to the agent, so no skill or extra
46
48
  about something you've written down and the agent uses the tools. To make that a rule rather than
47
49
  the agent's judgement, add a line to your `CLAUDE.md`, or your agent's equivalent:
48
50
 
49
- > My notes live in EtherPK; use the etherpk MCP tools for anything I've written down, and `search`
51
+ > My notes are stored in EtherPK - use the etherpk MCP tools for anything I've written down, and `search`
50
52
  > in semantic mode for questions.
51
53
 
52
54
  ## What the agent can do
@@ -57,22 +59,23 @@ and every tool refuses a protected document.
57
59
  | Group | Tools | Notes |
58
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. |
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. |
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. `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. |
61
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. |
62
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. |
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. |
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. |
65
68
 
66
69
  `read_asset`, `read_theme` and `preview_theme` write only under the graph's **downloads directory**,
67
70
  `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
71
+ from there. An agent names a folder relative to it and gets the full path back - a folder outside it
69
72
  is refused, so a prompt hidden in a note cannot steer the agent into writing or reading elsewhere.
70
73
  Copy a file out with your own tools when you want it somewhere else.
71
74
 
72
75
  ## Search by meaning
73
76
 
74
77
  `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
78
+ finds the note that says "due 31 January". A small embedding model runs on this computer - nothing is
76
79
  sent anywhere, and protected documents are never embedded.
77
80
 
78
81
  ```sh
@@ -89,14 +92,14 @@ directory, once per computer.
89
92
  Each result carries the document, its breadcrumb of headings and parent bullets, the passage's
90
93
  lines and text, and a similarity score. Passage text has bullet markers and `[[ ]]` removed, so
91
94
  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
95
+ - **Progress.** The first pass over a large graph takes minutes and runs in the background - after
93
96
  that only changed documents are embedded. Every semantic result reports `embedded`, `total` and
94
97
  `complete`, and `semantic status` shows each cached graph.
95
98
  - **Only while `serve` runs.** `serve` builds and updates the store, and runs only while an agent
96
99
  session has it open. To keep a graph current without an agent, run
97
100
  `npx @appsoftwareltd/etherpk-mcp serve --graph <id> </dev/null &` (or `--folder <path>`).
98
101
  - **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
102
+ between batches. `ETHERPK_MCP_SEMANTIC_THREADS` changes the thread count - set it in the agent
100
103
  registration's `env`.
101
104
  - **Per agent.** `serve --no-semantic` keeps one registration text-only.
102
105
 
@@ -120,7 +123,7 @@ give its address to `login`.
120
123
 
121
124
  `graphs` lists the synced graphs each signed-in account can reach, with the name, the id and your
122
125
  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.
126
+ stored on the server is opened once to read its name - `(unnamed)` means it has none.
124
127
 
125
128
  ### Several Sync Servers
126
129
 
@@ -136,7 +139,7 @@ and the commands the Agents tab shows always include it.
136
139
  tool call, and the index follows within a second or so.
137
140
  - A tool's write is in the file when the tool returns. If a write fails, the agent is told why and
138
141
  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
142
+ - The index is stored under the cache directory, never in the folder. Moving or renaming the folder
140
143
  starts the index again.
141
144
 
142
145
  ## Publishing a site
@@ -155,13 +158,13 @@ npx @appsoftwareltd/etherpk-mcp publish --graph <id or name> --publication <id>
155
158
  republishes itself.
156
159
  - Mermaid diagrams need a browser. `diagrams setup` installs a Chromium of about 170 MB into the
157
160
  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.
161
+ `ETHERPK_CHROMIUM` names a Chromium already on the computer instead - NixOS needs this.
159
162
  - `list_publications`, or **Settings → Publish** in EtherPK, shows the publication ids.
160
163
 
161
164
  ## Reference
162
165
 
163
166
  Every command is `npx @appsoftwareltd/etherpk-mcp <command>`. `npx` never puts `etherpk-mcp` on
164
- your PATH; for the short form, install the package globally once:
167
+ your PATH - for the short form, install the package globally once:
165
168
 
166
169
  ```sh
167
170
  npm install -g @appsoftwareltd/etherpk-mcp
@@ -189,7 +192,7 @@ npm install -g @appsoftwareltd/etherpk-mcp
189
192
 
190
193
  | Flag | Applies to | Meaning |
191
194
  | --- | --- | --- |
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. |
195
+ | `--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. |
193
196
  | `--pat <token>` | `login` | The Personal Access Token, instead of the prompt. |
194
197
  | `--recovery-code` | `login` | Unlock with your Recovery Code instead of waiting for Device Approval. Pressing `r` while `login` waits does the same. |
195
198
  | `--graph <id or name>` | `serve`, `publish` | The synced graph. Not with `--folder`. |
@@ -234,7 +237,7 @@ and keys on this computer and deletes that server's cached graphs.
234
237
 
235
238
  ## Build from source
236
239
 
237
- The package lives at `apps/mcp` in the etherpk-client repository. It compiles the Client's sync,
240
+ The package's source is `apps/mcp` in the etherpk-client repository. It compiles the Client's sync,
238
241
  crypto and index code in through a `$lib` alias, so it builds from the repository root, not from
239
242
  this folder alone:
240
243
 
@@ -242,7 +245,7 @@ this folder alone:
242
245
  pnpm install --frozen-lockfile
243
246
  pnpm --filter @appsoftwareltd/etherpk-mcp check # type check
244
247
  pnpm --filter @appsoftwareltd/etherpk-mcp test # unit tests, no server needed
245
- pnpm --filter @appsoftwareltd/etherpk-mcp build # dist/main.js; run it with node dist/main.js
248
+ pnpm --filter @appsoftwareltd/etherpk-mcp build # dist/main.js - run it with node dist/main.js
246
249
  ```
247
250
 
248
251
  Releases are published to npm by the repository's CI, at the same version as the Client. To check