@koneeric/onetool 0.0.0-stage → 0.3.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.
@@ -0,0 +1,810 @@
1
+ # Installing onetool
2
+
3
+ onetool is one MCP server that stands in front of your other MCP servers. Your host program (the assistant
4
+ you talk to) sees two tools, `run` and `search`, instead of every tool of every server. The assistant finds a
5
+ tool with `search`, then writes a short JavaScript program for `run` that calls the tools it needs. Only what
6
+ the program returns or prints comes back to the assistant.
7
+
8
+ This page takes you from nothing to a working setup. It follows the order of the work: check what you need,
9
+ try onetool on the practice server, add it to your host program, then write your own settings file.
10
+
11
+ ## What you need
12
+
13
+ - Node 22 or later. Check with `node --version`.
14
+ - The repository of onetool on your machine.
15
+ - The MCP package, installed once. In the root of the repository, run:
16
+
17
+ ```sh
18
+ npm ci
19
+ ```
20
+
21
+ This one command needs the network or npm's cache. After it, onetool itself opens no connection except to
22
+ the address of a listed server that you gave as a `url`. Servers started by a command, such as the practice
23
+ server, need no network at all.
24
+
25
+ ## Start with onetool init
26
+
27
+ The first thing to do is run one command. In a terminal:
28
+
29
+ ```sh
30
+ npx @koneeric/onetool init
31
+ ```
32
+
33
+ From the repository, `node bin/onetool.js init` is the same command. It sets up your settings file, then ends by
34
+ itself. It starts no server and connects to nothing.
35
+
36
+ **The file.** It makes the settings file when it is not there, with no server in it:
37
+ `~/.config/onetool/settings.json`. Give `--config` and a path to use another place. It never removes or changes what the file already holds.
38
+
39
+ **Claude Code.** When the command `claude` is found on your machine, and the file has no server that is Claude
40
+ Code, `init` proposes to add Claude Code as a server behind onetool. The answer by default is yes. What this
41
+ gives: the assistant's programs can run commands and read, search and edit files through Claude Code's own
42
+ tools. What it costs: Claude Code as a server asks no permission question: the rules of onetool are the control.
43
+
44
+ Two options answer for you. `--yes` adds it without asking. `--no-claude` proposes nothing. With nobody to ask (no
45
+ terminal) and no `--yes`, nothing is added, and the command says how to accept.
46
+
47
+ **What it adds.** This, to the file:
48
+
49
+ ```json
50
+ {
51
+ "mcpServers": {
52
+ "claude": { "command": "/absolute/path/to/claude", "args": ["mcp", "serve"], "tools": ["Bash", "Read", "Edit", "Write", "Grep", "Glob"] }
53
+ },
54
+ "onetool": { "hostServers": ["claude"] }
55
+ }
56
+ ```
57
+
58
+ The command is written with the full path where `claude` was found. The key `tools` keeps six of its tools,
59
+ and closes no tool of the other servers. The key `hostServers` makes onetool apply the host program's own rules
60
+ to them: see "Folders and rules from the host program".
61
+
62
+ **The entry.** `init` ends by printing the entry to paste into your host program's MCP settings, with the full
63
+ path of the settings file. It changes no file of your host program: you paste it yourself, as the next sections
64
+ say.
65
+
66
+ **Again.** Run it again on a file that has Claude Code already, and it proposes nothing and says so.
67
+
68
+ ## Try it first
69
+
70
+ You can try everything with no account and no network, from the root of the repository, once `npm ci` has run.
71
+ `npm test` runs every test of onetool, many of them through the real command and the real practice server.
72
+
73
+ The example settings file is `guide/pages/settings.example.json`. It lists the practice server, refuses the
74
+ tool `practice.fail` and asks the person before `practice.wipe`. It works from the root of the repository
75
+ only: the path of the practice server in it is relative, and onetool starts a listed server in its own
76
+ working folder, so the path means something only when onetool itself is started in the root of the
77
+ repository. From any other folder, give the path in full.
78
+
79
+ To start it by hand, from the root of the repository:
80
+
81
+ ```sh
82
+ node bin/onetool.js --config guide/pages/settings.example.json
83
+ ```
84
+
85
+ onetool then waits for a host program on its standard input. Press Ctrl-C to end it.
86
+
87
+ To try it in a host program, put the example file in the host program's settings as the next section says, then
88
+ ask the assistant to count the rows of Lyon with onetool. The answer is 625.
89
+
90
+ ## Add onetool to your host program
91
+
92
+ You add one server, onetool, to the MCP settings of your host program, by hand. onetool never changes the
93
+ settings file of another program.
94
+
95
+ Add this entry to the `mcpServers` of your host program:
96
+
97
+ ```json
98
+ {
99
+ "mcpServers": {
100
+ "onetool": {
101
+ "command": "node",
102
+ "args": ["/absolute/path/to/onetool/bin/onetool.js", "--config", "/absolute/path/to/settings.json"]
103
+ }
104
+ }
105
+ }
106
+ ```
107
+
108
+ Both paths must be absolute, and both are your own: the first is where the repository is on your machine,
109
+ the second is your onetool settings file (see the next section). A relative path would be read from whatever
110
+ folder the host program was started in.
111
+
112
+ Your other servers move. Take each of them out of the host program's file and put it in the onetool settings
113
+ file instead. If you leave a server in both, the assistant still sees its tools twice: once by itself and once
114
+ through onetool.
115
+
116
+ `onetool init` prints this entry for you, with the full path of your settings file; you only paste it.
117
+
118
+ Then start the host program again, so that it reads its settings.
119
+
120
+ - **Claude desktop** reads `claude_desktop_config.json`. On macOS it is in
121
+ `~/Library/Application Support/Claude/`. On Windows it is in `%APPDATA%\Claude\`. In JSON, write the
122
+ backslashes of a Windows path twice.
123
+ - **Any other program that speaks MCP**: the same entry, in that program's own MCP settings. Look in its
124
+ documentation for where they are.
125
+
126
+ onetool uses only what the MCP standard defines, so nothing of it is special to one host program.
127
+
128
+ ## The settings file
129
+
130
+ The settings file is JSON. It has two top-level keys: `mcpServers`, the servers onetool connects to, and
131
+ `onetool`, its own options (optional). The names of servers are yours, but a name may not be empty and may
132
+ not hold a dot.
133
+
134
+ An entry may also have the key `tools`: the names of the tools of that server that onetool keeps. The others do
135
+ not exist for `search` or for a program. It closes no tool of another server.
136
+
137
+ A server is one of two kinds of entry. One is started by a command, with `command`, `args` and `env`; only
138
+ `command` is required:
139
+
140
+ ```json
141
+ {
142
+ "mcpServers": {
143
+ "files": {
144
+ "command": "node",
145
+ "args": ["/absolute/path/to/server.js"],
146
+ "env": { "FILES_ROOT": "/absolute/path/to/folder" }
147
+ }
148
+ }
149
+ }
150
+ ```
151
+
152
+ The other is reached at an address, with `url` and `headers`; only `url` is required, and it must be an http
153
+ or https address:
154
+
155
+ ```json
156
+ {
157
+ "mcpServers": {
158
+ "far": {
159
+ "url": "https://example.com/mcp",
160
+ "headers": { "Authorization": "Bearer YOUR-TOKEN" }
161
+ }
162
+ }
163
+ }
164
+ ```
165
+
166
+ An entry may not have both `command` and `url`. An entry that breaks a rule is left out and does not stop the
167
+ others: onetool writes one line about it (see "When something does not work").
168
+
169
+ An entry reached at an address may also have the key `oauth`, for a server that asks you to sign in. It is
170
+ only needed when the server does not let a client register itself. See "Signing in".
171
+
172
+ The keys of `onetool`, all optional:
173
+
174
+ | Key | What it is | Default |
175
+ |---|---|---|
176
+ | `answerLimit` | The most characters any answer of onetool may have; a longer one is cut, with a notice | 8000 |
177
+ | `timeoutSeconds` | How long one program of `run` may take before it is stopped | 60 |
178
+ | `connectSeconds` | How long a server has to connect and list its tools | 30 |
179
+ | `searchLimit` | The most tools `search` lists in one answer | 10 |
180
+ | `stateLimit` | The most characters `state` may take as JSON between two calls of `run` | 10000000 |
181
+ | `allow` | Patterns of the tools a program may call; empty allows every tool | `[]` |
182
+ | `deny` | Patterns of the tools a program may not call | `[]` |
183
+ | `ask` | Patterns of the tools the person is asked about before each call | `[]` |
184
+ | `shell` | Switches the shell and files on for programs; its `folders`, the folders they may use, may be left out (see "The shell and files") | absent: the shell is off |
185
+ | `trail` | `true` or `false`: whether the answer of `run` ends with one line per call the program made | on |
186
+ | `log` | `true` or `false`: whether every call is written to the log file | `true` |
187
+ | `logFolder` | The full path of the folder of the log files | absent: the folder `logs` of onetool's own folder |
188
+ | `hostRules` | `true` or `false`: whether the host program's own permission rules are taken, only to tighten (see "Folders and rules from the host program") | on |
189
+ | `hostServers` | The names of the listed servers that are the host program itself, Claude Code started as a server | none |
190
+ | `backgroundSeconds` | How long a job, a program started in the background, may take before it is stopped (see "Background jobs") | 7200 |
191
+ | `maxJobs` | How many jobs may run at once; `0` lets none start | 3 |
192
+ | `libraryCap` | The most saved programs one library holds (see "The library") | 50 |
193
+ | `instructions` | `true` or `false`: whether onetool gives the host program its text for the session when it connects (see "Grouping the work") | on |
194
+
195
+ The file is read once, at the start. To change it, end onetool and start it again (for a host program, start
196
+ the host program again). A key of `onetool` that onetool does not know stops the start, with a line on
197
+ standard error. onetool never puts a value of the file, such as a key, a header or an environment value, in an
198
+ answer or on standard error. It may name a server, and the pattern of a rule when it refuses a call.
199
+
200
+ A server of yours may not be named `library`: that name is the built-in library's (see "The library"), and an
201
+ entry with it is not connected.
202
+
203
+ ## Signing in
204
+
205
+ Some servers reached at an address ask you to sign in by OAuth. onetool can sit in front of such a server too.
206
+ It applies to a server reached at an address, with no `Authorization` header in the settings file. A server
207
+ with that header, and a server started by a command, never sign in this way. This entry is all it takes:
208
+
209
+ ```json
210
+ {
211
+ "mcpServers": {
212
+ "notes": { "url": "https://example.com/mcp" }
213
+ }
214
+ }
215
+ ```
216
+
217
+ **What you see before you sign in.** `search` with no words lists the server as `notes: sign in needed`. A
218
+ call of one of its tools fails with a message that gives the command to run. The other servers work as usual.
219
+
220
+ **The command.** In a terminal, run:
221
+
222
+ ```sh
223
+ node /absolute/path/to/onetool/bin/onetool.js login notes --config /absolute/path/to/settings.json
224
+ ```
225
+
226
+ `npx @koneeric/onetool login notes --config ...` is the same command. It prints the address to open, opens it
227
+ in your browser, and listens on `127.0.0.1` for the browser to come back. It waits 300 seconds at most, then
228
+ says in one line that it worked or why not. Two options change it:
229
+
230
+ - `--no-browser`: the address is only printed. Use it on a machine with no browser of its own: open the
231
+ address in a browser on that same machine, or forward the port.
232
+ - `--wait`, with a number of seconds: how long to wait for the browser, instead of 300.
233
+
234
+ **No restart.** A running onetool picks the sign-in up at the next `search` or `run`. A token that runs out
235
+ is refreshed by itself, with nothing asked. When the server refuses the refresh, it is `sign in needed` again,
236
+ and the same command repairs it.
237
+
238
+ **Where the sign-in is.** In `~/.onetool/auth`: one file per server, readable by you only (mode `600`). It is
239
+ tied to the name and the address of the server: when the address changes in the settings file, the sign-in is
240
+ not used, and you sign in again. Nothing of a sign-in is ever in an answer, in the trail, in the log or on
241
+ standard error.
242
+
243
+ **Forgetting it.** Run `onetool logout notes --config /absolute/path/to/settings.json`, in the same way. The
244
+ file is removed. Nothing is sent to the server.
245
+
246
+ **A server that does not let a client register itself.** Some services want you to get a client id from them
247
+ first. Put it in the key `oauth` of that server's entry. The keys are `clientId`, `clientSecret`, `scopes`
248
+ and `port`. You get the client id from the service. `port` is the port to listen on when the service wants a
249
+ fixed address to come back to, `http://127.0.0.1:<port>/callback`; by default any free port is used. The
250
+ key `redirectHost` is the host name written in that address: `127.0.0.1` by default, or `localhost` for a
251
+ service that wants `http://localhost:<port>/callback`. onetool listens on `127.0.0.1` either way, and you leave
252
+ the key out unless the service asks for the name. The
253
+ secret stays in the settings file and is never copied anywhere else.
254
+
255
+ ```json
256
+ {
257
+ "mcpServers": {
258
+ "tracker": {
259
+ "url": "https://example.com/tracker/mcp",
260
+ "oauth": { "clientId": "your-client-id", "scopes": ["read"], "port": 8765 }
261
+ }
262
+ }
263
+ }
264
+ ```
265
+
266
+ **What cannot be put behind onetool.** The connectors a host program signs in to itself cannot be put behind onetool.
267
+ They live in the host program, not in a settings file. Only servers you list by address can be signed in to
268
+ here.
269
+
270
+ **What it speaks to.** For a sign-in, and only then, onetool speaks to the sign-in server that the listed
271
+ server names. It writes nothing of OAuth itself: the official MCP package does all of it.
272
+
273
+ ## Rules: allow, deny, ask
274
+
275
+ A pattern is matched against the whole id of a tool, `<server>.<tool>`, and upper and lower case count. A
276
+ `*` stands for any run of characters, dots included: `practice.*` is every tool of `practice`, `*.delete*`
277
+ every tool whose name starts with `delete`, and `*` is everything.
278
+
279
+ The three lists are applied in this order:
280
+
281
+ 1. `deny`: a call that matches a pattern is refused.
282
+ 2. `allow`: when the list is empty, every call is allowed. Otherwise only a call that matches a pattern is.
283
+ 3. `ask`: a call that passed the first two and matches a pattern is made only after the person says yes.
284
+
285
+ `deny` wins over `allow`, and a refused call is never asked about. A tool that is refused is hidden from
286
+ `search`. A tool under `ask` is not hidden: it is listed like any other.
287
+
288
+ ```json
289
+ {
290
+ "mcpServers": {
291
+ "practice": { "command": "node", "args": ["practice/src/server.js"] }
292
+ },
293
+ "onetool": {
294
+ "allow": ["practice.*"],
295
+ "deny": ["practice.fail"],
296
+ "ask": ["practice.wipe"]
297
+ }
298
+ }
299
+ ```
300
+
301
+ For `ask`, onetool asks the person through the host program, before each such call, each time: a yes is not
302
+ remembered, so two calls are two questions. The question names the tool, its arguments and the rule. When
303
+ the host program cannot ask, the call is refused. The time the person takes counts in the program's time
304
+ limit, so if you use `ask`, you may want a larger `timeoutSeconds`.
305
+
306
+ A program that is refused gets an error it can catch, and the answer of `run` says why. After the rule, the
307
+ cause is one of four:
308
+
309
+ - `the host program cannot ask the person`
310
+ - `the person said no`
311
+ - `the person gave no answer`
312
+ - `the question failed`
313
+
314
+ `the person gave no answer` is also what a program gets when the host program closes the question
315
+ without showing it to anyone. The usual case is a host program run with no person in front of it, such as a
316
+ script or a scheduled run: it says it can ask, then closes the question at once. The call was not made: the
317
+ tool behind the rule did nothing. For runs with no person, take the tool out of `ask` and put it under `allow` or `deny`
318
+ in the settings file of those runs.
319
+
320
+ This page does not say which host programs can ask: that changes with their versions.
321
+
322
+ ## The shell and files
323
+
324
+ The shell is off by default. A program of `run` then has no shell and no files: it can only call the tools of
325
+ the listed servers. You switch it on with the key `shell` of `onetool` (named `onetool.shell` in messages),
326
+ with `folders`: one or more full paths. The first folder is where a command starts and where a relative path
327
+ begins. `folders` may be left out: the folders are then those the host program gives (see
328
+ "Folders and rules from the host program" below). A folder that does not exist stops the start. A server of yours named `shell` is not connected while
329
+ the shell is on, because onetool has a server of that name of its own.
330
+
331
+ ```json
332
+ {
333
+ "mcpServers": {
334
+ "practice": { "command": "node", "args": ["practice/src/server.js"] }
335
+ },
336
+ "onetool": {
337
+ "shell": { "folders": ["/absolute/path/to/project"], "deny": ["rm *"], "ask": ["git push*"] }
338
+ }
339
+ }
340
+ ```
341
+
342
+ Inside `shell`, `allow`, `deny` and `ask` are lists of patterns matched against the text of a command; each is
343
+ optional. A program then gets four things:
344
+
345
+ - ``$`command` `` runs the text in the first folder with `/bin/sh` and gives back an object. `.text()` on it
346
+ gives what the command wrote. A command that fails throws in the program, unless it ends with `.nothrow()`.
347
+ A value put into a command with `${...}` is quoted as one word.
348
+ - `read(path)` gives the text of a file.
349
+ - `write(path, text)` writes a file.
350
+ - `edit(path, old, new)` replaces a text that must be in the file exactly once.
351
+
352
+ ```js
353
+ const found = (await $`grep -l needle *.txt`.text()).trim().split("\n");
354
+ await edit(found[0], "needle", "thread");
355
+ ```
356
+
357
+ The work is done by onetool's main process. The process of the program stays walled and gets no new right.
358
+
359
+ The folders limit `read`, `write` and `edit`. A path outside them is refused, also through `..` or a symbolic
360
+ link, and the message names the path and says it is outside the listed folders, as in
361
+ `onetool: shell.read is refused: ../x.txt is outside the listed folders`. Nothing is read or written.
362
+
363
+ The listed folders do not wall a shell command. A command can read, write and delete anywhere your own
364
+ account can, can use the network, and gets the environment of onetool's process. Switching the shell on is
365
+ your choice.
366
+
367
+ The four tools have the ids `shell.run`, `shell.read`, `shell.write` and `shell.edit`. They go in the lists
368
+ `allow`, `deny` and `ask` of `onetool` like any tool, and `search` lists them under `shell`. Rules on the text
369
+ of a command, the lists inside `shell`, are not the same thing. Rules on the text of a command are weak. A
370
+ denied command can be written another way: `rm *` does not stop `ls; rm x`. What is strong is `"deny":
371
+ ["shell.run"]` in `onetool`, which allows no command at all, or `ask` on `shell.run`, which has the person read
372
+ each command before it runs.
373
+
374
+ A command is stopped with its program at the time limit, together with everything it started, and nothing a
375
+ command started keeps running after it. The shell is built for macOS and Linux.
376
+
377
+ ### Another way: Claude Code as a listed server
378
+
379
+ Claude Code can itself be a listed server behind onetool. Started with `claude mcp serve`, it gives a program
380
+ its tools:
381
+
382
+ ```json
383
+ {
384
+ "mcpServers": {
385
+ "claude": { "command": "claude", "args": ["mcp", "serve"], "tools": ["Bash", "Read", "Edit", "Write", "Grep", "Glob"] }
386
+ },
387
+ "onetool": { "hostServers": ["claude"] }
388
+ }
389
+ ```
390
+
391
+ That server offers many more tools than you may want behind onetool (it names at least `Agent` and
392
+ `WebFetch`), so the list `tools` keeps six. It closes no tool of the other servers, which a list `allow` would
393
+ do. `onetool init` writes this for you: see "Start with onetool init".
394
+
395
+ No permission question was shown in the try. The rules of onetool, `allow`, `deny` and `ask`, are therefore your
396
+ control over these tools. `hostServers` makes onetool apply the `Bash`, `Read`, `Edit` and `Write` rules of
397
+ Claude Code's own settings files to them, when Claude Code is also the host program.
398
+
399
+ Which to prefer: the built-in shell needs nothing installed and limits files to the listed folders. Claude Code
400
+ as a server needs Claude Code installed and brings its own tools as they are.
401
+
402
+ ## Folders and rules from the host program
403
+
404
+ The shell does not need `folders` in the settings file. MCP lets a host program say which folders the session
405
+ works in: its `roots`. When `onetool.shell` is there and has no `folders`, those are the folders. The first one
406
+ is where commands start and where relative paths begin, and a change of roots told by the host program is
407
+ followed. Folders given in the settings file win. With neither, the shell stays off, and `search` with no words
408
+ says why: `no folder: onetool.shell.folders is not set and the host program gave none`.
409
+
410
+ ```json
411
+ {
412
+ "mcpServers": {
413
+ "practice": { "command": "node", "args": ["practice/src/server.js"] }
414
+ },
415
+ "onetool": { "shell": {} }
416
+ }
417
+ ```
418
+
419
+ onetool also takes the host program's own permission rules, where it can read them, and only to tighten.
420
+ A host rule can only tighten. A `deny` of the host refuses the call. An `ask` of the host asks the person, as
421
+ the `ask` of onetool does. An `allow` of the host changes nothing, and never undoes a `deny` or an `ask` of
422
+ onetool. The refusal names the file and the rule. This is on by default; `"hostRules": false` switches it off.
423
+
424
+ The host program gives its name when it connects. onetool knows Claude Code. For any other host program it
425
+ applies its own rules only, and says so once on standard error. For Claude Code it reads the lists `deny`,
426
+ `ask` and `allow` under `permissions` of three files: `~/.claude/settings.json`, `.claude/settings.json` and
427
+ `.claude/settings.local.json`, the last two in each folder the host gives. They are read again before each
428
+ program. A file that cannot be read is said once on standard error, and the others apply.
429
+
430
+ The rules apply to these pairs of names:
431
+
432
+ | Rule of the host program | Tool of the shell |
433
+ |---|---|
434
+ | `Bash` | `shell.run` |
435
+ | `Read` | `shell.read` |
436
+ | `Edit` | `shell.edit` |
437
+ | `Write` | `shell.write` |
438
+
439
+ An `Edit` rule also holds for `shell.write`. The same rules hold for the tools of those names of a listed
440
+ server named in `hostServers`.
441
+
442
+ The matching is onetool's own close copy of the host program's. It does not copy everything: not the
443
+ approvals given during the session, not the permission mode, not the hooks.
444
+
445
+ Rules on the text of a command are weak. It is the same sentence as in "The shell and files": a command can be
446
+ written another way.
447
+
448
+ ## Background jobs
449
+
450
+ Some programs take longer than the assistant should wait. A program of `run` can be started in the background
451
+ instead: `run` is called with `background: true`, answers at once with the id of a job, and the program goes
452
+ on. The tools stay two, `run` and `search`: a job is one more way to call `run`, not a new tool.
453
+
454
+ Two limits are in the settings file. This block shows them at their defaults:
455
+
456
+ ```json
457
+ {
458
+ "mcpServers": {
459
+ "practice": { "command": "node", "args": ["practice/src/server.js"] }
460
+ },
461
+ "onetool": { "backgroundSeconds": 7200, "maxJobs": 3 }
462
+ }
463
+ ```
464
+
465
+ The assistant asks for a job with `run` and the id, `job: "j1"`. The answer is the state of the job, the lines
466
+ the program posted and, once the job has ended, its answer. A program posts a line with `progress(text)`. The
467
+ state is one of four: `running`, `done`, `failed` or `stopped`. Of the lines posted, the last 10 are shown, and
468
+ a line says how many earlier ones are not. The answer is cut like any other answer, and asking again gives the
469
+ answer again. This is what asking answers for a job that has ended (the number of seconds is the job's own):
470
+
471
+ ```text
472
+ job j1: done, 2 s
473
+ --- progress ---
474
+ half
475
+ --- answer ---
476
+ 625
477
+ ```
478
+
479
+ To stop a job, `run` is called with `job: "j1"` and `stop: true`; the job is stopped with every command it
480
+ started, and nothing it started keeps running. Stopping a job that has ended changes nothing. To see all the
481
+ jobs of the session, `run` is called with `jobs: true`: one line each, `j1: done, 2 s`, in the order they were
482
+ started.
483
+
484
+ Two limits hold the jobs. A job is stopped after `backgroundSeconds` (7200 by default), and `timeoutSeconds`
485
+ does not hold it: that key is the limit of a program that is not in the background. At most `maxJobs` jobs (3
486
+ by default) run at once; one more is refused with a message that says so, and `0` lets none start. The last 20
487
+ jobs that have ended are kept, so the list stays short.
488
+
489
+ The rest stays as it was. The rules `allow`, `deny` and `ask` apply to the calls of a job as to any other, and so
490
+ do the trail and the log. A question under `ask` may reach the person while the assistant is doing something
491
+ else; when the host program cannot ask, the call is refused. `state` is shared with the other programs.
492
+
493
+ Jobs end when onetool ends. Nothing of a job is kept for the next start.
494
+
495
+ ## The library
496
+
497
+ onetool keeps a library of saved programs, so that a task done before is not written again. A program saves
498
+ one with `library.save(name, { about, params, code })`, and any later program calls it as
499
+ `await lib.<name>(args)`. The library is always there: no key switches it on or off.
500
+
501
+ A saved program is four things: a name (letters, digits and `_`, starting with a letter, at most 40
502
+ characters), one sentence that says what it does, the names of its arguments, and the text. The arguments are
503
+ given as one object, `lib.cityCount({ city: "Lyon" })`, and are variables in the text. Saved programs may call
504
+ each other.
505
+
506
+ This block sets the cap of programs at its default and asks the person before each save and each removal:
507
+
508
+ ```json
509
+ {
510
+ "mcpServers": {
511
+ "practice": { "command": "node", "args": ["practice/src/server.js"] }
512
+ },
513
+ "onetool": { "libraryCap": 50, "ask": ["library.save", "library.remove"] }
514
+ }
515
+ ```
516
+
517
+ **Where the files are.** The project's library is in the folder `.onetool/library` of the first folder the
518
+ shell works in, when there is one. The user's library is in `~/.onetool/library`. Both are read, and the
519
+ project's wins on a same name. Each program is one plain file, `<name>.js`, that you can read, edit, delete
520
+ and keep in git. This is the file of a program that counts the rows of one city:
521
+
522
+ ```js
523
+ // about: Counts the rows of one city.
524
+ // params: city
525
+ const { rows } = await tools.practice.rows({});
526
+ rows.filter((row) => row.city === city).length
527
+ ```
528
+
529
+ A file that does not fit this form is left out, and said once on standard error. A project's library comes
530
+ with the project: read what a repository you did not write holds before an assistant calls it.
531
+
532
+ **Finding them.** `search` shows the matching saved programs first, one line each. With no words it counts
533
+ them, in a last line `library: <n> programs`. The description of `run` says how many there are and names the
534
+ five most used.
535
+
536
+ **What keeps it small.** Beside the programs onetool keeps `stats.json`: for each program, its uses, its last
537
+ use and its failures in a row.
538
+
539
+ - A save whose text names the same tools in the same order as a saved program is refused, with a message that
540
+ names that program. `replace: true` in the arguments of the save puts the new program in its place.
541
+ The same tools in the same order is read from the text, not from a run. So two programs that call one tool
542
+ with different arguments count as the same, and one program with an argument serves both.
543
+ - A library holds at most `libraryCap` programs (50 by default). A save at the cap is refused, and the message
544
+ names the three least used.
545
+ - A program that failed 5 times in a row is moved to the archive.
546
+
547
+ **Lines of the trail.** Three lines, in parentheses, may end the trail of a program: one when a sequence of
548
+ calls that is not saved has run 3 times in the session (`save it as a program` with `library.save`), one when
549
+ a program did what a saved one does (`does this`: call it), and one when a failing program was moved. They
550
+ are part of the trail: with the trail off, they are not shown.
551
+
552
+ **Removing, and the archive.** `library.remove(name)` moves a program to the folder `archive` beside the
553
+ library. What a save replaces goes there too. Each file has its date in its name. To bring one back, call
554
+ `library.restore(name)`: see "Tidying the library".
555
+
556
+ **The rules.** Nothing is saved without a call of library.save. The two ids `library.save` and
557
+ `library.remove` go in `allow`, `deny` and `ask` like any tool, so you can be asked before each save, as the
558
+ block above does. Every call inside a saved program goes through the rules, the trail and the log as any
559
+ other.
560
+
561
+ ## Tidying the library
562
+
563
+ onetool has no model of its own. So the work of tidying a library that grew is split. onetool gives the
564
+ account and the means; the session of your host program reads, compares and proposes; you decide.
565
+
566
+ **The rules.** The three new ids, `library.report`, `library.restore` and `library.read`, go in `allow`,
567
+ `deny` and `ask` like any tool. This block asks you before each change of the library, so that nothing of a
568
+ tidy-up is applied without you, whatever the session does:
569
+
570
+ ```json
571
+ {
572
+ "mcpServers": {
573
+ "practice": { "command": "node", "args": ["practice/src/server.js"] }
574
+ },
575
+ "onetool": { "ask": ["library.save", "library.remove", "library.restore"] }
576
+ }
577
+ ```
578
+
579
+ **The report.** A program that returns `library.report()` gets a compact account of the library, 6,000
580
+ characters at most (the default `answerLimit` of 8000 holds it whole). For each saved program it gives its
581
+ uses, its failures in a row and its last use, the least used first. It lists the pairs of programs that share
582
+ most of their tools, and the programs not used for 30 days; a program never used is not among them. It ends
583
+ with the sequences of calls that ran 3 times or more and are not saved. The report changes no file. This is
584
+ one, as a person would see it:
585
+
586
+ ```text
587
+ Library report: 3 programs
588
+ --- programs: uses, failures in a row, last use ---
589
+ lib.cityShare (user): 0 uses, 0 failures, never
590
+ lib.old (user): 1 uses, 0 failures, 2026-10-09
591
+ lib.cityCount (user): 2 uses, 0 failures, 2026-11-18
592
+ --- programs that share most of their tools ---
593
+ lib.cityCount and lib.cityShare: 1 of 2 tools (practice.rows)
594
+ --- not used for 30 days ---
595
+ lib.old
596
+ --- sequences of calls run 3 times or more and not saved ---
597
+ 3 times: practice.count
598
+ ```
599
+
600
+ **Where the sequences come from.** One line per program that ended well and named a tool is added to
601
+ `~/.onetool/sequences.jsonl`, with the names of its tools and never its text. The file is kept from one
602
+ session to the next, for every project, so the report can count a sequence that ran in three different
603
+ sessions. It is not written when the log is switched off, and it is a file you may delete.
604
+
605
+ **Reading one program.** `library.read(name)` gives the text of a saved program as its file holds it, so
606
+ that the session opens only the programs worth comparing and not all of them.
607
+
608
+ **The prompt.** onetool offers one MCP prompt, `tidy-library`, that you start from your host program, where
609
+ the host shows prompts. How a host shows them is the host's business, and this page names no host as the
610
+ only one. The text of the prompt tells the session to read the report, to open only the programs worth
611
+ comparing, to propose what to merge, retire, rename or save, and to wait for your yes. Only then does it apply
612
+ what you agreed to, with `library.save` and `library.remove`. Nothing is changed before you say yes. A host
613
+ that shows no prompt changes nothing else: you ask for the same work in your own words.
614
+
615
+ **Bringing one back.** Whatever a save replaces or a removal takes is in the folder `archive` beside its
616
+ library, with its date. `library.restore(name)` brings the newest file of that name back, with its counts at
617
+ zero. It is refused when a program of that name is saved, or when the library is at its cap.
618
+
619
+ ## Grouping the work
620
+
621
+ onetool saves context only when one program does several steps: a program that makes one call saves nothing.
622
+ So onetool leads the session to group its work. Put every step that needs no decision into one program.
623
+
624
+ **The instructions.** When the host program connects, onetool gives it a text for the session, the
625
+ instructions the MCP standard defines: 600 characters at most, the same whatever the servers. It asks the
626
+ assistant to list the steps before the first `run`, to put every step that needs no decision into one program,
627
+ to return only the small result needed to decide what comes next, to keep large results in `state`, and never
628
+ to use `run` for one tool call when the next call is already known. Whether the assistant reads it is the host
629
+ program's doing. `"instructions": false` switches the text off, and nothing else:
630
+
631
+ ```json
632
+ {
633
+ "mcpServers": {
634
+ "practice": { "command": "node", "args": ["practice/src/server.js"] }
635
+ },
636
+ "onetool": { "instructions": false }
637
+ }
638
+ ```
639
+
640
+ **The line of the trail.** When three programs in a row, in the foreground, each made exactly one call, and
641
+ nobody was asked a question in between, the trail of the third ends with this line. It is said again only after
642
+ three more programs. A program that calls a saved program does not count.
643
+
644
+ ```
645
+ (the last 3 programs each made one call: they could have been one program)
646
+ ```
647
+
648
+ **The number.** `search` with no words ends with one line for the session. Nothing is shown before the first
649
+ program. A low number of calls per program means the work is not grouped.
650
+
651
+ ```
652
+ this session: 3 programs, 3 calls, 1.0 calls per program
653
+ ```
654
+
655
+ **A paragraph to paste.** A host program that does not pass on the instructions of a server may still be told:
656
+ paste this paragraph into the standing instructions of your assistant, the file or the setting where the host
657
+ program keeps what the assistant is always told.
658
+
659
+ ```text
660
+ When you use onetool, group the work. Before the first run, list the steps of the task. Put every step that needs no decision into one program: loops, filters, several tools. Return only the small result you need to decide what comes next, and keep large results in state. Never use run for one tool call when the next call is already known.
661
+ ```
662
+
663
+ ## The trail and the log
664
+
665
+ Every call a program makes through `run` is recorded, a tool of a listed server and a tool of the shell alike,
666
+ made or refused. The record has two forms. Each works without the other.
667
+
668
+ The trail comes after the answer of `run`: the line `--- calls ---`, then one line per call the program made,
669
+ in the order the calls began, with its id, its milliseconds and the size of its answer, or `refused`,
670
+ `failed` or `unfinished` when it had none:
671
+
672
+ ```text
673
+ --- calls ---
674
+ practice.count 12 ms 13 chars
675
+ shell.read 0 ms refused
676
+ ```
677
+
678
+ With more than 20 calls, the first 20 are shown, then one line with the count of the rest. The trail counts in
679
+ `answerLimit`, and it is what is kept when an answer is cut: the answer is cut before it. A program that made
680
+ no call has no trail, unless a line of the library ends it. The key `trail` switches it on or off; it is on by default.
681
+
682
+ A trail may end with a line of the library, in parentheses, after the lines of the calls: see "The library".
683
+
684
+ The log is one JSON line per call, in a file per day named `calls-<date>.jsonl`, in the folder `logs` of
685
+ onetool's own folder unless `logFolder` says another. A line has eight keys: `time`, `session` (the same in
686
+ every line of one start of onetool), `id`, `args`, `decision` (what the rules said), `ms`, `size` and `fault`
687
+ (why a call did not end well, or null). The log never holds the answer of a call, the text written or edited
688
+ (the path and the sizes are there), or a value of the settings file. A log that cannot be written is said once
689
+ on standard error and stops nothing. `"log": false` switches it off, and then no folder is made. onetool
690
+ never deletes a log file: that is yours to do. Of a `library.save`, the log keeps the name and the size of the
691
+ code, never the text.
692
+
693
+ Beside the log of the calls, onetool keeps one line per program that ended well and named a tool, in the
694
+ file `~/.onetool/sequences.jsonl` of your home folder. A line holds the names of the tools the text of the
695
+ program names, and never the text, an argument or an answer. `"log": false` switches this file off with the
696
+ log. See "Tidying the library" for what it is for.
697
+
698
+ ```json
699
+ {
700
+ "mcpServers": {
701
+ "practice": { "command": "node", "args": ["practice/src/server.js"] }
702
+ },
703
+ "onetool": { "trail": true, "log": true, "logFolder": "/absolute/path/to/logs" }
704
+ }
705
+ ```
706
+
707
+ ## When something does not work
708
+
709
+ onetool speaks to a person on standard error. A host program keeps it in its logs; look there first.
710
+ Standard output carries only MCP messages.
711
+
712
+ - `usage: onetool --config <settings file>`: the command was started with anything but `--config` and one
713
+ path. Fix the `args` of the entry: exactly `--config` and then the path.
714
+ - `settings file not found`: the path after `--config` is not a readable file. Give the full path, and check
715
+ the spelling.
716
+ - `not connected (could not start)`: the command of a listed server could not be started, or it ended before it
717
+ listed its tools. Run that command yourself in a terminal to see why.
718
+ - `not connected (could not connect)`: a server reached at an address could not be reached, or did not answer
719
+ as an MCP server does. Check the `url`, the `headers` and that the server runs.
720
+ - `not connected (refused the connection)`: the server answered with an error when onetool began. Check that
721
+ the server is the one you meant and that it is configured as it asks.
722
+ - `not connected (bad entry:`, followed by a reason: the entry of that server in the settings file breaks a
723
+ rule, for instance it has both `command` and `url`. Correct the entry.
724
+ - `no answer in`, followed by a number of seconds (the reason reads `no answer in 30 seconds`): the server did
725
+ not list its tools in time. Make sure it starts, or raise `connectSeconds`. It also covers the `login` that
726
+ waited for the browser: no browser came back in time. Run it again, with `--wait` if you need longer.
727
+ - `nobody to ask`, said by `onetool init` when it proposes Claude Code and no terminal is there to answer: nothing
728
+ was added. Run the command the line gives, with `--yes`, or run `init` in a terminal.
729
+ - `sign in needed`, as `notes: sign in needed` in `search`, or in the message of a failed call: the server asks
730
+ for a sign-in and you have none, or it is no longer valid. Run the `login` command the message gives, in a
731
+ terminal. See "Signing in".
732
+ - `the sign-in could not be started`: the server names no sign-in server, or does not let a client register
733
+ itself. Give it a client id in the key `oauth` of its entry. See "Signing in".
734
+
735
+ Each of these lines has the form `onetool: server <name>: not connected (<reason>)`. A server that fails does
736
+ not stop the others, and does not stop onetool.
737
+
738
+ With the shell switched on or off, four more texts:
739
+
740
+ - `the shell is not switched on`, in the answer of a program that used `$`, `read`, `write` or `edit`: the
741
+ shell is off. Add `shell` with `folders` to `onetool` in the settings file, and start again.
742
+ - `is outside the listed folders`, in the answer of a program: a path given to `read`, `write` or `edit` is
743
+ not under any listed folder. Use a path inside them, or add the folder to `folders`.
744
+ - `is not a folder`, on standard error at the start (`onetool: onetool.shell.folders: item <n> is not a
745
+ folder`): the folder in that place of `folders` does not exist. Make it, or correct the path.
746
+ - `onetool: the log cannot be written`, once on standard error: the log folder could not be made or a file
747
+ could not be written. Check `logFolder` and who may write there; calls go on without a log.
748
+
749
+ With the host program, three more texts:
750
+
751
+ - `no folder: onetool.shell.folders is not set and the host program gave none`, in the line of `shell` in the
752
+ answer of `search`: `shell` has no `folders` and the host program gave none. Add `folders` to `shell`, or
753
+ give the host program a folder to work in.
754
+ - `onetool: host rules: this host program is not known`, once on standard error: onetool applies its own rules
755
+ only. Nothing is wrong; add the rules you want to the settings file of onetool.
756
+ - `cannot be read, its rules are not applied`, once on standard error after `onetool: host rules:` and a path:
757
+ that settings file of the host program is not readable. Fix the file or who may read it; the other files
758
+ apply.
759
+
760
+ With jobs, two more texts:
761
+
762
+ - `jobs may run at once`, in the answer of `run` when a job was not started: as many jobs as `maxJobs` allows
763
+ are running. Wait for one to end, stop one, or raise `maxJobs`.
764
+ - `no job`, in the answer of `run` when it is asked for a job: `onetool: no job j99 in this session.` The id is
765
+ not one of this session. Ask `run` with `jobs: true` for the ids.
766
+
767
+ With the library, six more texts:
768
+
769
+ - `calls the same tools in the same order`, in the answer of a refused `library.save`: a saved program does
770
+ what the new one does. Call the program the message names, or save again with `replace: true`.
771
+ - `the limit is`, in the answer of a refused `library.save`: the library holds as many programs as
772
+ `libraryCap`. The message names the three least used: remove one with `library.remove(name)`, replace one,
773
+ or raise `libraryCap`.
774
+ - `is not a saved program`, once on standard error (`onetool: library: <path> is not a saved program, it is
775
+ left out`): a file in a library folder is not of the form of a program file. Correct the file or delete it.
776
+ - `the name is taken by the built-in library`, as the reason a server is not connected: a server of yours is
777
+ named `library`. Give it another name.
778
+ - `is in the archive`, in the answer of a refused `library.restore` (`no program named <name> is in the
779
+ archive`): the archive holds no file of that name. Check the name; the archive is the folder `archive`
780
+ beside the library.
781
+ - `remove it first`, in the answer of a refused `library.restore` (`a program named <name> is saved
782
+ already: remove it first`): a program of that name is saved. Call `library.remove(name)` first, or keep the
783
+ one that is saved.
784
+
785
+ To see all of this from the assistant, ask `search` with no words. It lists every server with its count of
786
+ tools, or with the reason it is not connected.
787
+
788
+ ## What onetool does not do
789
+
790
+ - It does not change the settings file of another program.
791
+ - It does not speak the old SSE transport of MCP, the one with two addresses.
792
+ - It never opens a browser by itself. You sign in with `onetool login`, from a terminal (see "Signing in").
793
+ - It does not connect again to a server that went away, and it does not follow a change of a server's list of
794
+ tools. Both need a new start.
795
+ - It writes its log; the settings file that `onetool init` is given, and only that one (see "Start with onetool
796
+ init"); the sign-ins, one file per server, in the folder `~/.onetool/auth`; the file of the
797
+ sequences, `sequences.jsonl`, in `~/.onetool`; the files of the library,
798
+ which are the programs that calls of `library.save` keep, their `stats.json` and their archive, in the
799
+ library folders; and, only with the shell switched on, what programs
800
+ write in the listed folders. It writes nothing else.
801
+ - It does not wall a shell command: the listed folders limit `read`, `write` and `edit`, not what a command
802
+ does.
803
+ - It does not copy everything of the host program's permissions: not the approvals given during the session,
804
+ not the permission mode, not the hooks.
805
+ - It never writes a settings file of the host program. It only reads them.
806
+ - It does not keep a job after onetool itself ends. Jobs end when onetool ends. It writes nothing of a job to a
807
+ file, except the lines of its calls in the log.
808
+ - It saves no program by itself. Nothing is saved without a call of library.save.
809
+ - It tidies nothing by itself. onetool has no model of its own.
810
+ - It remembers `state` only as long as its process lives.