@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.
- package/LICENSE +21 -0
- package/README.md +76 -2
- package/auth/src/index.js +302 -0
- package/bin/onetool.js +4 -0
- package/core/src/index.js +843 -0
- package/guide/pages/INSTALL.md +810 -0
- package/guide/pages/settings.example.json +6 -0
- package/hosts/src/adapters/claude-code.js +136 -0
- package/hosts/src/index.js +107 -0
- package/library/src/index.js +544 -0
- package/package.json +36 -4
- package/practice/src/rows.js +15 -0
- package/practice/src/server.js +187 -0
- package/practice/src/signin.js +242 -0
- package/sandbox/src/child.mjs +441 -0
- package/sandbox/src/index.js +301 -0
- package/sandbox/src/last-expression.mjs +134 -0
- package/sandbox/src/probe.mjs +42 -0
- package/server/src/connect.js +190 -0
- package/server/src/descriptions.js +62 -0
- package/server/src/host.js +116 -0
- package/server/src/init.js +243 -0
- package/server/src/library.js +207 -0
- package/server/src/main.js +142 -0
- package/server/src/prompt.js +15 -0
- package/server/src/record.js +131 -0
- package/server/src/sign.js +98 -0
- package/server/src/tools.js +553 -0
- package/shell/src/index.js +270 -0
|
@@ -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.
|