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