@appsoftwareltd/etherpk-mcp 0.7.0 → 0.8.0
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 +188 -138
- package/dist/main.js +402 -165
- package/dist/main.js.map +1 -1
- package/package.json +6 -5
package/README.md
CHANGED
|
@@ -1,25 +1,19 @@
|
|
|
1
1
|
# @appsoftwareltd/etherpk-mcp
|
|
2
2
|
|
|
3
|
-
An [MCP](https://modelcontextprotocol.io) server that gives
|
|
4
|
-
|
|
5
|
-
computer as the agent
|
|
6
|
-
|
|
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
|
|
9
|
-
|
|
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
|
-
##
|
|
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,171 +29,227 @@ 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
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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:
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --folder /path/to/your/notes
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The folder must already be an EtherPK graph: open it in EtherPK once.
|
|
42
|
+
|
|
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.
|
|
43
51
|
|
|
44
|
-
|
|
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.
|
|
52
|
+
## What the agent can do
|
|
47
53
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
off while only one is signed in, and the commands the Agents tab shows always include it.
|
|
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.
|
|
51
56
|
|
|
52
|
-
|
|
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; `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. |
|
|
65
|
+
|
|
66
|
+
## Search by meaning
|
|
53
67
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
68
|
+
`search` matches words. After one setup step it also matches **meaning**: "when do I pay my taxes"
|
|
69
|
+
finds the note that says "due 31 January". A small embedding model runs on this computer; nothing is
|
|
70
|
+
sent anywhere, and protected documents are never embedded.
|
|
57
71
|
|
|
58
72
|
```sh
|
|
59
|
-
|
|
73
|
+
npx @appsoftwareltd/etherpk-mcp semantic setup
|
|
60
74
|
```
|
|
61
75
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
76
|
+
Setup installs a native runtime of about 300 MB through your npm, and a 23 MB model, into the cache
|
|
77
|
+
directory, once per computer.
|
|
78
|
+
|
|
79
|
+
- **No restart needed.** A running `serve` checks every 30 seconds and starts building once setup
|
|
80
|
+
has run. Until then a search by meaning is refused, and the message names the setup command so
|
|
81
|
+
the agent can tell you what to run.
|
|
82
|
+
- **Modes.** `search` accepts `mode: "semantic"`, and `"hybrid"` for words and meaning side by side.
|
|
83
|
+
Each result carries the document, its breadcrumb of headings and parent bullets, the passage's
|
|
84
|
+
lines and text, and a similarity score. Passage text has bullet markers and `[[ ]]` removed, so
|
|
85
|
+
quote it, but take the `old` text for `edit_document` from `read_document`.
|
|
86
|
+
- **Progress.** The first pass over a large graph takes minutes and runs in the background; after
|
|
87
|
+
that only changed documents are embedded. Every semantic result reports `embedded`, `total` and
|
|
88
|
+
`complete`, and `semantic status` shows each cached graph.
|
|
89
|
+
- **Only while `serve` runs.** `serve` builds and updates the store, and runs only while an agent
|
|
90
|
+
session has it open. To keep a graph current without an agent, run
|
|
91
|
+
`npx @appsoftwareltd/etherpk-mcp serve --graph <id> </dev/null &` (or `--folder <path>`).
|
|
92
|
+
- **Load.** The model uses a quarter of the cores, at most four, and pauses for a tenth of a second
|
|
93
|
+
between batches. `ETHERPK_MCP_SEMANTIC_THREADS` changes the thread count; set it in the agent
|
|
94
|
+
registration's `env`.
|
|
95
|
+
- **Per agent.** `serve --no-semantic` keeps one registration text-only.
|
|
96
|
+
|
|
97
|
+
## Synced graphs in detail
|
|
98
|
+
|
|
99
|
+
### Signing in
|
|
100
|
+
|
|
101
|
+
`login` makes this computer a device of your account:
|
|
102
|
+
|
|
103
|
+
- It asks for an account-wide Personal Access Token, from `<Sync Server>/account/tokens` or
|
|
104
|
+
**Access tokens** in EtherPK's account menu. `--pat` or `ETHERPK_PAT` supplies it instead.
|
|
105
|
+
- It unlocks your keys by Device Approval: it shows a short code, which you confirm in EtherPK in
|
|
106
|
+
any browser signed in to the account with its graphs unlocked.
|
|
107
|
+
- With no EtherPK to hand, press `r` while it waits, or pass `--recovery-code`, and type your
|
|
108
|
+
Recovery Code instead. `ETHERPK_RECOVERY_CODE` supplies the code for a scripted setup.
|
|
109
|
+
|
|
110
|
+
When it is done it lists the graphs the account can reach. A self-hosted Sync Server works the same
|
|
111
|
+
way: give its address to `login`.
|
|
112
|
+
|
|
113
|
+
### Choosing a graph
|
|
114
|
+
|
|
115
|
+
`graphs` lists the synced graphs each signed-in account can reach, with the name, the id and your
|
|
116
|
+
role. `serve --graph` takes the id or the name. A graph nobody has opened since names were first
|
|
117
|
+
stored on the server is opened once to read its name; `(unnamed)` means it has none.
|
|
67
118
|
|
|
68
|
-
|
|
119
|
+
### Several Sync Servers
|
|
120
|
+
|
|
121
|
+
One computer can be signed in to several Sync Servers, your own beside EtherPK's, say. Run `login`
|
|
122
|
+
once for each. `--sync-server` then says which server a command means. It can be left out while only
|
|
123
|
+
one server is signed in, and the commands the Agents tab shows always include it.
|
|
124
|
+
|
|
125
|
+
## Local folders in detail
|
|
126
|
+
|
|
127
|
+
- The folder must hold `pages/` and `journals/`. `serve` never creates them, so a mistyped path is
|
|
128
|
+
refused rather than turned into an empty graph.
|
|
129
|
+
- Edits made in an editor, or by the agent writing files directly, are picked up before the next
|
|
130
|
+
tool call, and the index follows within a second or so.
|
|
131
|
+
- A tool's write is in the file when the tool returns. If a write fails, the agent is told why and
|
|
132
|
+
the edit is retried on the next write.
|
|
133
|
+
- The index lives under the cache directory, never in the folder. Moving or renaming the folder
|
|
134
|
+
starts the index again.
|
|
135
|
+
|
|
136
|
+
## Publishing a site
|
|
137
|
+
|
|
138
|
+
`publish` renders one publication of a graph into a folder on this computer and prints the report:
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
npx @appsoftwareltd/etherpk-mcp publish --graph <id or name> --publication <id> --out <dir>
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- `--out` is remembered for that graph and publication. Later runs without it, and the agent's
|
|
145
|
+
`publish` tool, write to the same folder. The agent can't choose a folder.
|
|
146
|
+
- In that folder, the top-level `.html` files, `assets/`, `theme/` and the search, feed and report
|
|
147
|
+
files are rewritten, and files that no longer belong are removed. Everything else is left alone.
|
|
148
|
+
- Deploying the folder, with a git push say, is up to you. Run the command from cron for a site that
|
|
149
|
+
republishes itself.
|
|
150
|
+
- Mermaid diagrams need a browser. `diagrams setup` installs a Chromium of about 170 MB into the
|
|
151
|
+
cache directory, once per computer, and a publish whose pages hold diagrams refuses until then.
|
|
152
|
+
`ETHERPK_CHROMIUM` names a Chromium already on the computer instead; NixOS needs this.
|
|
153
|
+
- `list_publications`, or **Settings → Publish** in EtherPK, shows the publication ids.
|
|
154
|
+
|
|
155
|
+
## Reference
|
|
69
156
|
|
|
70
157
|
Every command is `npx @appsoftwareltd/etherpk-mcp <command>`. `npx` never puts `etherpk-mcp` on
|
|
71
|
-
your PATH; for the short form,
|
|
72
|
-
|
|
158
|
+
your PATH; for the short form, install the package globally once:
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
npm install -g @appsoftwareltd/etherpk-mcp
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
`--help` (`-h`) prints the command reference and `--version` (`-v`) the version.
|
|
165
|
+
|
|
166
|
+
### Commands
|
|
73
167
|
|
|
74
168
|
| Command | What it does |
|
|
75
169
|
| --- | --- |
|
|
76
|
-
| `login --sync-server <url> [--pat <token>] [--recovery-code]` | Sign this computer in as a device of your account on that Sync Server
|
|
170
|
+
| `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
171
|
| `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
172
|
| `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.
|
|
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.
|
|
81
|
-
| `semantic setup` | Install the embedding runtime
|
|
173
|
+
| `serve --folder <path> [--no-semantic]` | Serve a local graph folder the same way. |
|
|
174
|
+
| `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. |
|
|
175
|
+
| `semantic setup` | Install the embedding runtime and model into the cache directory. |
|
|
82
176
|
| `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
|
|
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.
|
|
85
|
-
| `diagrams setup` | Install a Chromium
|
|
177
|
+
| `semantic remove` | Delete the runtime and model. Each graph's stored embeddings stay in its cache and are reused if you set up again. |
|
|
178
|
+
| `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. |
|
|
179
|
+
| `diagrams setup` | Install a Chromium into the cache directory so a publish can draw Mermaid diagrams. |
|
|
86
180
|
| `diagrams status` | Which browser a publish would use, if any. |
|
|
87
181
|
|
|
182
|
+
### Flags
|
|
183
|
+
|
|
88
184
|
| Flag | Applies to | Meaning |
|
|
89
185
|
| --- | --- | --- |
|
|
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. |
|
|
186
|
+
| `--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
187
|
| `--pat <token>` | `login` | The Personal Access Token, instead of the prompt. |
|
|
92
188
|
| `--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
|
|
94
|
-
| `--folder <path>` | `serve` | The local graph folder
|
|
189
|
+
| `--graph <id or name>` | `serve`, `publish` | The synced graph. Not with `--folder`. |
|
|
190
|
+
| `--folder <path>` | `serve`, `publish` | The local graph folder. Not with `--graph` or `--sync-server`. |
|
|
95
191
|
| `--no-semantic` | `serve` | Keep this agent text-only even when semantic search is set up. |
|
|
96
192
|
| `--all` | `logout` | Every server at once. |
|
|
97
|
-
| `--publication <id>` | `publish` | Which publication of the graph.
|
|
193
|
+
| `--publication <id>` | `publish` | Which publication of the graph. |
|
|
98
194
|
| `--out <dir>` | `publish` | Where the site goes on this computer. Remembered for the graph and publication. |
|
|
99
195
|
|
|
100
|
-
|
|
196
|
+
### Environment variables
|
|
197
|
+
|
|
198
|
+
| Variable | Meaning |
|
|
101
199
|
| --- | --- |
|
|
102
|
-
| `ETHERPK_PAT` |
|
|
103
|
-
| `ETHERPK_RECOVERY_CODE` |
|
|
104
|
-
| `ETHERPK_MCP_CONFIG` | The
|
|
105
|
-
| `ETHERPK_MCP_CACHE_DIR` | The cache
|
|
200
|
+
| `ETHERPK_PAT` | The Personal Access Token, for a scripted `login`. |
|
|
201
|
+
| `ETHERPK_RECOVERY_CODE` | The Recovery Code, for a scripted `login --recovery-code`. |
|
|
202
|
+
| `ETHERPK_MCP_CONFIG` | The file holding the logins. Default `~/.config/etherpk/mcp.json`, under `XDG_CONFIG_HOME` when that is set. |
|
|
203
|
+
| `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. |
|
|
204
|
+
| `ETHERPK_MCP_PUBLISH_CONFIG` | The file remembering each publication's publish folder. Default `publish.json` beside the login file. |
|
|
106
205
|
| `ETHERPK_MCP_SEMANTIC_THREADS` | Threads for the embedding model. Default a quarter of the cores, at most four. |
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
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.
|
|
206
|
+
| `ETHERPK_CHROMIUM` | A Chromium on this computer for drawing diagrams, instead of the one `diagrams setup` installs. |
|
|
207
|
+
| `PLAYWRIGHT_BROWSERS_PATH` | Where `diagrams setup` installs Chromium and a publish looks for it. Default `browsers/` in the cache directory. |
|
|
208
|
+
| `ETHERPK_MCP_DEBUG_MEMORY` | `1` logs the process's memory use every 10 seconds and with every progress line. |
|
|
140
209
|
|
|
141
|
-
|
|
142
|
-
npx @appsoftwareltd/etherpk-mcp semantic setup
|
|
143
|
-
```
|
|
210
|
+
## What stays on your computer
|
|
144
211
|
|
|
145
|
-
- **
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
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.
|
|
212
|
+
- **Keys** in the login file, `~/.config/etherpk/mcp.json`, one entry per Sync Server, readable only
|
|
213
|
+
by your user: the same trust as a browser you've signed in on.
|
|
214
|
+
- **A cache of each synced graph you serve** under `~/.cache/etherpk/mcp/`, so a restart fetches what
|
|
215
|
+
changed rather than everything. It holds your notes readably, as a signed-in browser's storage
|
|
216
|
+
does. The Sync Server stays the source of truth: each start asks it what changed, edits made
|
|
217
|
+
elsewhere arrive as they happen, and a newer version of this package discards a cache it can't
|
|
218
|
+
read and rebuilds it.
|
|
219
|
+
- **For a folder**, only its index and, once semantic search is set up, its embeddings, under
|
|
220
|
+
`local/<folder name>-<hash of its path>/` in the cache directory. Nothing is written into the
|
|
221
|
+
folder.
|
|
162
222
|
|
|
163
|
-
|
|
223
|
+
On Windows both directories are under your user folder: `C:\Users\<you>\.config\etherpk\` and
|
|
224
|
+
`C:\Users\<you>\.cache\etherpk\`.
|
|
164
225
|
|
|
165
|
-
|
|
166
|
-
|
|
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.
|
|
226
|
+
To cut an agent off, revoke its Personal Access Token on the Sync Server. `logout` forgets the token
|
|
227
|
+
and keys on this computer and deletes that server's cached graphs.
|
|
175
228
|
|
|
176
|
-
|
|
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.
|
|
229
|
+
## Build from source
|
|
179
230
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
index code in through a `$lib` alias, so it builds from the repo, not from this folder alone:
|
|
231
|
+
The package lives at `apps/mcp` in the etherpk-client repository. It compiles the Client's sync,
|
|
232
|
+
crypto and index code in through a `$lib` alias, so it builds from the repository root, not from
|
|
233
|
+
this folder alone:
|
|
184
234
|
|
|
185
235
|
```sh
|
|
186
|
-
pnpm install
|
|
187
|
-
pnpm --filter @appsoftwareltd/etherpk-mcp check # type
|
|
236
|
+
pnpm install --frozen-lockfile
|
|
237
|
+
pnpm --filter @appsoftwareltd/etherpk-mcp check # type check
|
|
188
238
|
pnpm --filter @appsoftwareltd/etherpk-mcp test # unit tests, no server needed
|
|
189
239
|
pnpm --filter @appsoftwareltd/etherpk-mcp build # dist/main.js; run it with node dist/main.js
|
|
190
240
|
```
|
|
191
241
|
|
|
192
|
-
|
|
193
|
-
|
|
242
|
+
Releases are published to npm by the repository's CI, at the version the Client and the Sync Server
|
|
243
|
+
share. To check that a version is on the registry:
|
|
194
244
|
|
|
195
245
|
```sh
|
|
196
|
-
|
|
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
|
|
246
|
+
npx -y @appsoftwareltd/etherpk-mcp@<version> --version
|
|
199
247
|
```
|
|
200
248
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
249
|
+
## Documentation and licence
|
|
250
|
+
|
|
251
|
+
The full guide is [Using AI agents with your notes](https://docs.etherpk.com/using-ai-agents-with-your-notes).
|
|
204
252
|
|
|
205
|
-
|
|
253
|
+
The package is available under the Elastic License 2.0 ([LICENSE](LICENSE)): you may use, copy,
|
|
254
|
+
modify and self-host it, but not offer it to others as a hosted or managed service. It is
|
|
255
|
+
source-available, not open source.
|