@appsoftwareltd/etherpk-mcp 0.9.2 → 0.9.3
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.
- package/README.md +154 -128
- package/dist/main.js +14332 -12119
- package/dist/main.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -3,13 +3,13 @@
|
|
|
3
3
|
[](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
|
|
7
|
-
computer
|
|
8
|
-
|
|
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
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
|
|
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.
|
|
25
|
-
#
|
|
26
|
-
|
|
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
|
-
#
|
|
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
|
|
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
|
|
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
|
|
48
|
-
|
|
49
|
-
|
|
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
|
|
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-
|
|
57
|
-
|
|
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. `
|
|
62
|
-
| Edit | `edit_document`, `append_document`, `create_page`, `set_task`, `set_frontmatter`, `set_aliases` | `edit_document` replaces one exact, unique piece of text
|
|
63
|
-
| Tasks handed over | `read_task`, `add_task_note`, `set_task` |
|
|
64
|
-
| Rename | `plan_rename`, `rename` | Links to the old name are rewritten
|
|
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.
|
|
66
|
-
| Publishing | `list_publications`, `create_publication`, `update_publication`, `publish` | `publish` writes
|
|
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
|
|
68
|
-
|
|
69
|
-
`read_asset`, `read_theme` and `preview_theme` write only
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
|
78
|
-
finds the note that says "due 31 January". A small embedding model runs on this computer
|
|
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
|
|
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
|
|
89
|
-
has run. Until then a search by meaning is refused, and the message names the setup command
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
|
102
|
-
between batches. `ETHERPK_MCP_SEMANTIC_THREADS` changes the thread count
|
|
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
|
|
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
|
-
-
|
|
113
|
-
**
|
|
114
|
-
|
|
115
|
-
your
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
-
|
|
121
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
135
|
-
|
|
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
|
|
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.
|
|
145
|
-
|
|
146
|
-
- The index is
|
|
147
|
-
starts
|
|
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,101 @@ 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.
|
|
159
|
-
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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.
|
|
163
176
|
- Mermaid diagrams need a browser. `diagrams setup` installs a Chromium of about 170 MB into the
|
|
164
177
|
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
|
|
178
|
+
`ETHERPK_CHROMIUM` names a Chromium already on the computer instead, which NixOS needs.
|
|
166
179
|
- `list_publications`, or **Settings → Publish** in EtherPK, shows the publication ids.
|
|
167
180
|
|
|
168
181
|
## Reference
|
|
169
182
|
|
|
170
|
-
Every command is `npx @appsoftwareltd/etherpk-mcp <command>`.
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
```sh
|
|
174
|
-
npm install -g @appsoftwareltd/etherpk-mcp
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
`--help` (`-h`) prints the command reference and `--version` (`-v`) the version.
|
|
183
|
+
Every command is `npx @appsoftwareltd/etherpk-mcp <command>`. For the short form, `etherpk-mcp`,
|
|
184
|
+
install the package globally once with `npm install -g @appsoftwareltd/etherpk-mcp`. `--help`
|
|
185
|
+
(`-h`) prints the command reference and `--version` (`-v`) the version.
|
|
178
186
|
|
|
179
187
|
### Commands
|
|
180
188
|
|
|
181
189
|
| Command | What it does |
|
|
182
190
|
| --- | --- |
|
|
183
|
-
| `login --sync-server <url> [--
|
|
184
|
-
| `graphs [--sync-server <url>]` | List the synced graphs each signed-in account can reach,
|
|
191
|
+
| `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. |
|
|
192
|
+
| `graphs [--sync-server <url>]` | List the synced graphs each signed-in account can reach, with name, id and your role. |
|
|
185
193
|
| `serve --graph <id or name> [--sync-server <url>] [--no-semantic]` | Serve one synced graph to the agent over stdio. |
|
|
186
194
|
| `serve --folder <path> [--no-semantic]` | Serve a local graph folder the same way. |
|
|
187
|
-
| `
|
|
195
|
+
| `running` | List the graphs served on this computer, with each one's background process, agents and log. |
|
|
196
|
+
| `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. |
|
|
197
|
+
| `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
198
|
| `semantic setup` | Install the embedding runtime and model into the cache directory. |
|
|
189
|
-
| `semantic status` | Whether semantic search is set up
|
|
190
|
-
| `semantic remove` | Delete the runtime and model.
|
|
191
|
-
| `publish (--graph <id or name> \| --folder <path>) --publication <id> [--out <dir>]` | Publish one publication of a graph to a folder
|
|
192
|
-
| `diagrams setup` | Install a Chromium into the cache directory so a publish can draw Mermaid diagrams. |
|
|
199
|
+
| `semantic status` | Whether semantic search is set up, and each cached graph's embedding progress. |
|
|
200
|
+
| `semantic remove` | Delete the runtime and model. Stored embeddings stay, and are reused if you set up again. |
|
|
201
|
+
| `publish (--graph <id or name> \| --folder <path>) --publication <id> [--out <dir>]` | Publish one publication of a graph to a folder and print the report. |
|
|
202
|
+
| `diagrams setup` | Install a Chromium into the cache directory, so a publish can draw Mermaid diagrams. |
|
|
193
203
|
| `diagrams status` | Which browser a publish would use, if any. |
|
|
194
204
|
|
|
195
205
|
### Flags
|
|
196
206
|
|
|
197
207
|
| Flag | Applies to | Meaning |
|
|
198
208
|
| --- | --- | --- |
|
|
199
|
-
| `--sync-server <url>` | `login`, `graphs`, `serve --graph`, `publish --graph`, `logout` | Which Sync Server the command means. Required for `login
|
|
200
|
-
| `--
|
|
201
|
-
| `--
|
|
202
|
-
| `--
|
|
203
|
-
| `--
|
|
209
|
+
| `--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. |
|
|
210
|
+
| `--code <setup code>` | `login` | The one-time setup code. It works once, within 10 minutes. |
|
|
211
|
+
| `--pat <token>` | `login` | An account-wide access token instead of a setup code. `login` swaps it for an agent token and revokes it. |
|
|
212
|
+
| `--recovery-code` | `login` | Unlock with your Recovery Code instead of Device Approval. Pressing `r` while `login` waits does the same. |
|
|
213
|
+
| `--graph <id or name>` | `serve`, `publish`, `stop` | The synced graph. Not with `--folder`. |
|
|
214
|
+
| `--folder <path>` | `serve`, `publish`, `stop` | The local graph folder. Not with `--graph` or `--sync-server`. |
|
|
204
215
|
| `--no-semantic` | `serve` | Keep this agent text-only even when semantic search is set up. |
|
|
205
|
-
| `--all` | `logout` | Every server
|
|
216
|
+
| `--all` | `logout`, `stop` | Every server, or every graph. |
|
|
206
217
|
| `--publication <id>` | `publish` | Which publication of the graph. |
|
|
207
|
-
| `--out <dir>` | `publish` | Where the site goes
|
|
218
|
+
| `--out <dir>` | `publish` | Where the site goes. Remembered for the graph and publication. |
|
|
208
219
|
|
|
209
220
|
### Environment variables
|
|
210
221
|
|
|
222
|
+
Set a variable that `serve` should see in the agent registration's `env` as well as your shell,
|
|
223
|
+
because the agent starts `serve` with its own environment.
|
|
224
|
+
|
|
211
225
|
| Variable | Meaning |
|
|
212
226
|
| --- | --- |
|
|
213
|
-
| `ETHERPK_PAT` |
|
|
214
|
-
| `ETHERPK_RECOVERY_CODE` | The Recovery Code
|
|
215
|
-
| `
|
|
216
|
-
| `
|
|
217
|
-
| `
|
|
227
|
+
| `ETHERPK_PAT` | An account-wide access token for a scripted `login`, swapped for an agent token and revoked. |
|
|
228
|
+
| `ETHERPK_RECOVERY_CODE` | The Recovery Code for a scripted `login --recovery-code`. |
|
|
229
|
+
| `ETHERPK_MCP_SECRETS` | `file` keeps the agent token and Encryption Keys in the login file even where there is a keychain. |
|
|
230
|
+
| `ETHERPK_MCP_CONFIG` | The login file. Default `~/.config/etherpk/mcp.json`, or under `XDG_CONFIG_HOME` when that is set. |
|
|
231
|
+
| `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. |
|
|
232
|
+
| `ETHERPK_MCP_PUBLISH_CONFIG` | The file that remembers each publication's folder. Default `publish.json` beside the login file. |
|
|
218
233
|
| `ETHERPK_MCP_SEMANTIC_THREADS` | Threads for the embedding model. Default a quarter of the cores, at most four. |
|
|
234
|
+
| `ETHERPK_MCP_HOST_IDLE_SECONDS` | How long a graph's background process stays after its last agent has gone. Default 300. |
|
|
219
235
|
| `ETHERPK_CHROMIUM` | A Chromium on this computer for drawing diagrams, instead of the one `diagrams setup` installs. |
|
|
220
236
|
| `PLAYWRIGHT_BROWSERS_PATH` | Where `diagrams setup` installs Chromium and a publish looks for it. Default `browsers/` in the cache directory. |
|
|
221
237
|
| `ETHERPK_MCP_DEBUG_MEMORY` | `1` logs the process's memory use every 10 seconds and with every progress line. |
|
|
222
238
|
|
|
223
239
|
## What stays on your computer
|
|
224
240
|
|
|
225
|
-
- **
|
|
226
|
-
|
|
227
|
-
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
- **
|
|
241
|
+
- **The agent token and your Encryption Keys.** They go in the system keychain where `login` can
|
|
242
|
+
use one: the macOS Keychain, or a Linux desktop's keyring through `secret-tool` (the
|
|
243
|
+
`libsecret-tools` package on Debian and Ubuntu). The login file, `~/.config/etherpk/mcp.json`,
|
|
244
|
+
then names only the server. Otherwise they are in the login file, readable only by your user,
|
|
245
|
+
like a signed-in browser's storage. `login` says which. Any program running as you can ask the
|
|
246
|
+
keychain for them, so run only agents you trust with your account, and never let one read, print
|
|
247
|
+
or search `~/.config/etherpk`.
|
|
248
|
+
- **A cache of each synced graph you serve**, under `~/.cache/etherpk/mcp/`, so a restart fetches
|
|
249
|
+
only what changed. It holds your notes readably. The Sync Server stays the source of truth, and a
|
|
250
|
+
newer version of this package rebuilds a cache it can't read.
|
|
251
|
+
- **For a folder**, its index and, with semantic search, its embeddings, under
|
|
233
252
|
`local/<folder name>-<hash of its path>/` in the cache directory. Nothing is written into the
|
|
234
253
|
folder.
|
|
254
|
+
- **Beside each graph's cache**, `host.json` while its background process runs, and `host.log`,
|
|
255
|
+
which names the graph's documents and is deleted with the cache. The process listens on a socket
|
|
256
|
+
in a directory only your user can open (`$XDG_RUNTIME_DIR/etherpk-mcp`, or `etherpk-mcp-<uid>` in
|
|
257
|
+
the temporary directory), or on Windows on a named pipe with a random name.
|
|
235
258
|
|
|
236
|
-
On Windows
|
|
259
|
+
On Windows the login file and the cache are under `C:\Users\<you>\.config\etherpk\` and
|
|
237
260
|
`C:\Users\<you>\.cache\etherpk\`.
|
|
238
261
|
|
|
239
|
-
To cut an agent off, revoke its
|
|
240
|
-
|
|
241
|
-
may have been copied, also
|
|
242
|
-
devices
|
|
262
|
+
To cut an agent off, revoke its agent token on the Sync Server's **Access tokens** page. `logout`
|
|
263
|
+
revokes the token itself and deletes the keys and cached graphs on this computer. If the computer
|
|
264
|
+
or its login file may have been copied, also select **Replace Encryption Keys and lock out other
|
|
265
|
+
devices** in EtherPK, so the keys saved there no longer open your account.
|
|
243
266
|
|
|
244
267
|
## Build from source
|
|
245
268
|
|
|
@@ -251,11 +274,11 @@ this folder alone:
|
|
|
251
274
|
pnpm install --frozen-lockfile
|
|
252
275
|
pnpm --filter @appsoftwareltd/etherpk-mcp check # type check
|
|
253
276
|
pnpm --filter @appsoftwareltd/etherpk-mcp test # unit tests, no server needed
|
|
254
|
-
pnpm --filter @appsoftwareltd/etherpk-mcp build # dist/main.js
|
|
277
|
+
pnpm --filter @appsoftwareltd/etherpk-mcp build # dist/main.js, run with node dist/main.js
|
|
255
278
|
```
|
|
256
279
|
|
|
257
|
-
|
|
258
|
-
|
|
280
|
+
The repository's CI publishes each release to npm, at the same version as the Client. To check that
|
|
281
|
+
a version is on the registry:
|
|
259
282
|
|
|
260
283
|
```sh
|
|
261
284
|
npx -y @appsoftwareltd/etherpk-mcp@<version> --version
|
|
@@ -264,6 +287,9 @@ npx -y @appsoftwareltd/etherpk-mcp@<version> --version
|
|
|
264
287
|
## Documentation and licence
|
|
265
288
|
|
|
266
289
|
The full guide is [Using AI agents with your notes](https://docs.etherpk.com/using-ai-agents-with-your-notes).
|
|
290
|
+
What changed in each release is in the
|
|
291
|
+
[changelog](https://github.com/appsoftwareltd/etherpk-client/blob/main/CHANGELOG.md), which covers
|
|
292
|
+
this package and the EtherPK Client, released together under one version.
|
|
267
293
|
|
|
268
294
|
The package is available under the Elastic License 2.0 ([LICENSE](LICENSE)): you may use, copy,
|
|
269
295
|
modify and self-host it, but not offer it to others as a hosted or managed service. It is
|