toolnexus 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +142 -63
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,9 +7,9 @@
|
|
|
7
7
|
and you have a working agent — MCP servers, agent skills, your own functions, and HTTP endpoints
|
|
8
8
|
unified as one tool set, driving any LLM.
|
|
9
9
|
|
|
10
|
-
> **Right-sized.** Not a framework (no builders, advisors, runnables, config), not a toy
|
|
11
|
-
> falls over the moment you need streaming or a retry. Everything a real agent needs — the
|
|
12
|
-
> hooks, streaming, retries, memory — and nothing it doesn't.
|
|
10
|
+
> **Right-sized.** Not a framework (no builders, advisors, runnables, config graphs), not a toy
|
|
11
|
+
> that falls over the moment you need streaming or a retry. Everything a real agent needs — the
|
|
12
|
+
> loop, hooks, streaming, retries, memory — and nothing it doesn't.
|
|
13
13
|
|
|
14
14
|
The JS/TypeScript port of [toolnexus](https://github.com/muthuishere/toolnexus) — the same
|
|
15
15
|
library, byte-identical, also in **Python, Go, Java, and C#**. Built on
|
|
@@ -21,30 +21,89 @@ library, byte-identical, also in **Python, Go, Java, and C#**. Built on
|
|
|
21
21
|
npm install toolnexus
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
##
|
|
24
|
+
## Quick start
|
|
25
|
+
|
|
26
|
+
Built-in tools are on by default, so an empty toolkit can already act:
|
|
25
27
|
|
|
26
28
|
```ts
|
|
27
29
|
import { createToolkit, createClient } from "toolnexus"
|
|
28
30
|
|
|
29
|
-
|
|
30
|
-
const tk = await createToolkit({ mcpConfig: "./mcp.json", skillsDir: "./skills" })
|
|
31
|
-
|
|
32
|
-
// 2. point at any OpenAI- or Anthropic-style endpoint
|
|
31
|
+
const tk = await createToolkit() // 10 built-in tools, on by default
|
|
33
32
|
const agent = createClient({
|
|
34
|
-
baseUrl: "https://openrouter.ai/api/v1",
|
|
35
|
-
style: "openai",
|
|
33
|
+
baseUrl: "https://openrouter.ai/api/v1", // any OpenAI- or Anthropic-style endpoint
|
|
34
|
+
style: "openai", // or "anthropic"
|
|
36
35
|
model: "openai/gpt-4o-mini",
|
|
37
36
|
})
|
|
38
37
|
|
|
39
|
-
|
|
40
|
-
const { text } = await agent.run("Refund order 1234 for the customer.", { toolkit: tk })
|
|
38
|
+
const { text } = await agent.run("What files are in this folder?", { toolkit: tk })
|
|
41
39
|
console.log(text)
|
|
42
|
-
await tk.close()
|
|
43
40
|
```
|
|
44
41
|
|
|
45
42
|
`createClient` reads the key from `OPENROUTER_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`
|
|
46
|
-
|
|
47
|
-
with hooks, streaming (`agent.stream(...)`), retries/backoff, and
|
|
43
|
+
(or pass `apiKey`). The loop runs call → execute tools → feed back → repeat (up to `maxTurns`,
|
|
44
|
+
default 10), with hooks, streaming (`agent.stream(...)`), retries/backoff, timeout, and
|
|
45
|
+
conversation memory available.
|
|
46
|
+
|
|
47
|
+
## With MCP + skills
|
|
48
|
+
|
|
49
|
+
Point the toolkit at an `mcp.json` and a `skills/` folder — every MCP server tool and every
|
|
50
|
+
`SKILL.md` becomes part of the same tool set. Skills are injected into the system prompt; a
|
|
51
|
+
single `skill` tool loads each on demand (progressive disclosure).
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
const tk = await createToolkit({
|
|
55
|
+
mcpConfig: "./mcp.json", // path or a config object; local stdio + remote streamable-HTTP
|
|
56
|
+
skillsDir: "./skills", // a folder of <name>/SKILL.md (string or string[])
|
|
57
|
+
})
|
|
58
|
+
|
|
59
|
+
const { text } = await agent.run("Refund order 1234 for the customer.", { toolkit: tk })
|
|
60
|
+
console.log(text)
|
|
61
|
+
await tk.close() // disconnect MCP servers
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Conversations / memory
|
|
65
|
+
|
|
66
|
+
`run()` is stateless — each call starts fresh. To keep a thread's history, use `ask()` with an
|
|
67
|
+
`id`, or a `conversation()` object.
|
|
68
|
+
|
|
69
|
+
**`ask(prompt, { toolkit, id? })`** — with an `id`, the client's `ConversationStore` remembers
|
|
70
|
+
the thread: it *loads* that id's transcript, *runs*, *saves* the updated transcript, and returns
|
|
71
|
+
the answer. The next `ask` with the same `id` continues it. Without an `id` it's a stateless
|
|
72
|
+
one-shot (identical to `run`).
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
const agent = createClient({
|
|
76
|
+
baseUrl: "https://openrouter.ai/api/v1",
|
|
77
|
+
style: "openai",
|
|
78
|
+
model: "openai/gpt-4o-mini",
|
|
79
|
+
// store defaults to InMemoryConversationStore (process lifetime).
|
|
80
|
+
})
|
|
81
|
+
|
|
82
|
+
await agent.ask("My name is Muthu.", { toolkit: tk, id: "user-42" })
|
|
83
|
+
const { text } = await agent.ask("What's my name?", { toolkit: tk, id: "user-42" })
|
|
84
|
+
console.log(text) // → "Your name is Muthu."
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
**Persist across processes.** A `ConversationStore` is two methods — implement it for a file, DB,
|
|
88
|
+
or Redis and pass it as `store`:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import type { ConversationStore } from "toolnexus"
|
|
92
|
+
|
|
93
|
+
interface ConversationStore {
|
|
94
|
+
get(id: string): Promise<any[] | undefined> // stored transcript for id, or undefined
|
|
95
|
+
save(id: string, messages: any[]): Promise<void>
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const agent = createClient({ baseUrl, style: "openai", model, store: myFileStore })
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The default is `InMemoryConversationStore` (also exported). For a quick in-process thread without
|
|
102
|
+
ids, `agent.conversation({ toolkit })` returns an object whose `.send(prompt)` retains history
|
|
103
|
+
automatically (`.messages`, `.reset()`).
|
|
104
|
+
|
|
105
|
+
The same `store` powers inbound A2A: `toolkit.serve` keys each peer's turns by the A2A
|
|
106
|
+
`contextId` through `client.ask`, so a remote agent's conversation is remembered too (see below).
|
|
48
107
|
|
|
49
108
|
## Add your own tools
|
|
50
109
|
|
|
@@ -52,64 +111,53 @@ with hooks, streaming (`agent.stream(...)`), retries/backoff, and conversation m
|
|
|
52
111
|
import { defineTool, httpTool } from "toolnexus"
|
|
53
112
|
|
|
54
113
|
tk.register(
|
|
55
|
-
// a plain function → a tool
|
|
114
|
+
// a plain function → a tool (run returns a string or a full ToolResult)
|
|
56
115
|
defineTool({
|
|
57
|
-
name: "add",
|
|
58
|
-
|
|
59
|
-
|
|
116
|
+
name: "add",
|
|
117
|
+
description: "Add two numbers",
|
|
118
|
+
inputSchema: {
|
|
119
|
+
type: "object",
|
|
120
|
+
properties: { a: { type: "number" }, b: { type: "number" } },
|
|
121
|
+
required: ["a", "b"],
|
|
122
|
+
},
|
|
123
|
+
run: (args) => `${(args.a as number) + (args.b as number)}`,
|
|
60
124
|
}),
|
|
61
125
|
// a REST endpoint → a tool
|
|
62
126
|
httpTool({
|
|
63
|
-
name: "create_ticket",
|
|
127
|
+
name: "create_ticket",
|
|
128
|
+
description: "Create a ticket",
|
|
129
|
+
method: "POST",
|
|
64
130
|
url: "https://api.example.com/tickets",
|
|
65
131
|
headers: { Authorization: "Bearer ${API_TOKEN}" }, // ${ENV} expands from process.env, never logged
|
|
66
|
-
inputSchema: {
|
|
132
|
+
inputSchema: {
|
|
133
|
+
type: "object",
|
|
134
|
+
properties: { title: { type: "string" } },
|
|
135
|
+
required: ["title"],
|
|
136
|
+
},
|
|
67
137
|
}),
|
|
68
138
|
)
|
|
69
139
|
```
|
|
70
140
|
|
|
71
|
-
URL `{placeholders}` are filled from args; `query`
|
|
72
|
-
the JSON body
|
|
73
|
-
|
|
74
|
-
## Bring your own loop
|
|
75
|
-
|
|
76
|
-
Don't want the host loop? Use the schema adapters and execute calls yourself:
|
|
77
|
-
|
|
78
|
-
```ts
|
|
79
|
-
const tools = tk.toOpenAI() // or tk.toAnthropic() / tk.toGemini()
|
|
80
|
-
const system = tk.skillsPrompt() // skills catalog for your system prompt (opens with a preamble telling the model to use the skill tool)
|
|
81
|
-
// when the model returns a tool call { name, arguments }:
|
|
82
|
-
const res = await tk.execute(name, args) // -> { output, isError, metadata }
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
## The four sources
|
|
86
|
-
|
|
87
|
-
| Source | How |
|
|
88
|
-
|--------|-----|
|
|
89
|
-
| **MCP servers** | an `mcp.json` (`mcpServers`/`servers`/`mcp`); local stdio + remote streamable-HTTP, `headers` for auth |
|
|
90
|
-
| **Agent skills** | a folder of `<name>/SKILL.md`; a `skill` tool loads each on demand + a system-prompt catalog |
|
|
91
|
-
| **Native tools** | `defineTool({...})` — a function becomes a tool |
|
|
92
|
-
| **HTTP / REST** | `httpTool({...})` — an endpoint becomes a tool, `${ENV}` headers |
|
|
93
|
-
|
|
94
|
-
All four appear as one uniform `Tool` in `tk.tools()`. Each is à la carte — use just `loadMcp(config)`
|
|
95
|
-
or `loadSkills(dir)` if that's all you need.
|
|
141
|
+
For `httpTool`: URL `{placeholders}` are filled from args; `query` arg names go to the
|
|
142
|
+
querystring (all args on GET); the rest become the JSON body (`body: "json" | "form" | "raw"`).
|
|
143
|
+
Non-2xx → `{ isError: true, output: "HTTP <status>: <body>" }`.
|
|
96
144
|
|
|
97
145
|
## Built-in tools
|
|
98
146
|
|
|
99
147
|
A fifth source ships **10 built-in tools** — `bash`, `read`, `write`, `edit`, `grep`, `glob`,
|
|
100
|
-
`webfetch`, `question`, `apply_patch`, `todowrite` (names + input schemas match
|
|
101
|
-
|
|
148
|
+
`webfetch`, `question`, `apply_patch`, `todowrite` (names + input schemas match opencode) — so an
|
|
149
|
+
agent can act with zero wiring. They appear in the tool schema
|
|
102
150
|
(`toOpenAI()`/`toAnthropic()`/`toGemini()`), like MCP tools — not the system prompt.
|
|
103
151
|
|
|
104
152
|
**On by default.** One global toggle turns the whole source off, or a per-tool `tools` map
|
|
105
153
|
disables individual builtins on the all-on baseline:
|
|
106
154
|
|
|
107
155
|
```ts
|
|
108
|
-
const tk = await createToolkit({
|
|
156
|
+
const tk = await createToolkit({ builtins: false })
|
|
109
157
|
// also accepts { disabled: true } or { enabled: false }
|
|
110
158
|
|
|
111
159
|
// per-tool: drop bash, keep the other nine (unknown names ignored; whole-source-off still wins)
|
|
112
|
-
const tk2 = await createToolkit({
|
|
160
|
+
const tk2 = await createToolkit({ builtins: { tools: { bash: false } } })
|
|
113
161
|
```
|
|
114
162
|
|
|
115
163
|
`bash`/`write`/`edit`/`apply_patch` run commands and mutate the filesystem — the toggle is the
|
|
@@ -136,7 +184,7 @@ await tk.addAgent("https://writer.example.com/.well-known/agent-card.json")
|
|
|
136
184
|
```
|
|
137
185
|
|
|
138
186
|
`agent({ card, headers?, timeout?, pollEvery? })` — `headers` support `${ENV}` expansion (never
|
|
139
|
-
logged); `timeout` defaults to 300000ms, `pollEvery` to 1000ms. A config
|
|
187
|
+
logged); `timeout` defaults to 300000ms, `pollEvery` to 1000ms. A config object can also carry an
|
|
140
188
|
`agents` block (mirrors `mcpServers`). A failing agent is isolated — logged, contributes no tools,
|
|
141
189
|
never fatal.
|
|
142
190
|
|
|
@@ -144,12 +192,8 @@ never fatal.
|
|
|
144
192
|
built from your **SKILL.md skills** (never raw tools):
|
|
145
193
|
|
|
146
194
|
```ts
|
|
147
|
-
import { createClient } from "toolnexus"
|
|
148
|
-
|
|
149
|
-
const agent = createClient({ baseUrl: "https://openrouter.ai/api/v1", style: "openai", model: "openai/gpt-4o-mini" })
|
|
150
|
-
|
|
151
195
|
const handle = await tk.serve("127.0.0.1:0", {
|
|
152
|
-
client: agent,
|
|
196
|
+
client: agent, // a createClient(...) instance fulfils each task
|
|
153
197
|
a2a: {
|
|
154
198
|
name: "research-agent",
|
|
155
199
|
description: "Answers research questions.",
|
|
@@ -161,26 +205,61 @@ console.log(handle.url) // GET /.well-known/agent-card.json ; POST / (SendMess
|
|
|
161
205
|
await handle.stop()
|
|
162
206
|
```
|
|
163
207
|
|
|
164
|
-
`serve(addr, { client, a2a?, onTask? })` fulfils each inbound `SendMessage` task via
|
|
165
|
-
Task persistence is a pluggable `TaskStore` — in-memory default, `"file:<dir>"`, or your own.
|
|
208
|
+
`serve(addr, { client, a2a?, onTask? })` fulfils each inbound `SendMessage` task via the client.
|
|
209
|
+
Task persistence is a pluggable `TaskStore` — in-memory default, `"file:<dir>"`, or your own. And
|
|
210
|
+
it **remembers**: a message's A2A `contextId` keys the conversation through `client.ask`, so a
|
|
211
|
+
peer's turns in the same context carry history via the client's `ConversationStore`.
|
|
212
|
+
|
|
213
|
+
## Bring your own loop
|
|
214
|
+
|
|
215
|
+
Don't want the host loop? Use the schema adapters and execute calls yourself:
|
|
216
|
+
|
|
217
|
+
```ts
|
|
218
|
+
const tools = tk.toOpenAI() // or tk.toAnthropic() / tk.toGemini()
|
|
219
|
+
const system = tk.skillsPrompt() // skills catalog for your system prompt
|
|
220
|
+
// when the model returns a tool call { name, arguments }:
|
|
221
|
+
const res = await tk.execute(name, args) // → { output, isError, metadata }
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
## The four sources
|
|
225
|
+
|
|
226
|
+
| Source | How |
|
|
227
|
+
|--------|-----|
|
|
228
|
+
| **MCP servers** | an `mcp.json` (`mcpServers`/`servers`/`mcp`); local stdio + remote streamable-HTTP, `headers` for auth |
|
|
229
|
+
| **Agent skills** | a folder of `<name>/SKILL.md`; a `skill` tool loads each on demand + a system-prompt catalog |
|
|
230
|
+
| **Native tools** | `defineTool({...})` — a function becomes a tool |
|
|
231
|
+
| **HTTP / REST** | `httpTool({...})` — an endpoint becomes a tool, `${ENV}` headers |
|
|
232
|
+
|
|
233
|
+
All appear as one uniform `Tool` in `tk.tools()`. Built-ins are a fifth source; remote A2A agents
|
|
234
|
+
a sixth.
|
|
166
235
|
|
|
167
236
|
## API
|
|
168
237
|
|
|
169
238
|
| Member | Description |
|
|
170
239
|
|--------|-------------|
|
|
171
|
-
| `createToolkit(opts)` | async factory → `Toolkit` |
|
|
172
|
-
| `createClient(opts)` | the unified host loop (`
|
|
240
|
+
| `createToolkit(opts)` | async factory → `Toolkit` (`mcpConfig`, `skillsDir`, `builtins`, `agents`, `extraTools`) |
|
|
241
|
+
| `createClient(opts)` | the unified host loop (`baseUrl`, `style`, `model`, `store?`, `hooks?`, `maxTurns?`, `retries?`, `timeoutMs?`) |
|
|
242
|
+
| `client.run(prompt, { toolkit, signal?, history? })` | stateless run → `RunResult` |
|
|
243
|
+
| `client.ask(prompt, { toolkit, id?, signal? })` | stateful with `id` (loads → runs → saves via `store`); one-shot without `id` |
|
|
244
|
+
| `client.conversation({ toolkit })` | in-process multi-turn object — `.send(prompt)`, `.messages`, `.reset()` |
|
|
245
|
+
| `client.stream(prompt, { toolkit })` | async-iterate `StreamEvent`s (text deltas, tool calls/results, usage, done) |
|
|
246
|
+
| `ConversationStore` | `get(id)` / `save(id, messages)` — implement for file/db; default `InMemoryConversationStore` |
|
|
173
247
|
| `tk.tools()` / `tk.get(name)` | the uniform tools |
|
|
248
|
+
| `tk.register(...tools)` | add native/http/custom tools at runtime |
|
|
174
249
|
| `tk.execute(name, args, ctx?)` | run a tool → `ToolResult` |
|
|
175
250
|
| `tk.skillsPrompt()` | system-prompt skill catalog |
|
|
176
251
|
| `tk.mcpStatus()` | per-server connection status |
|
|
177
252
|
| `tk.toOpenAI()` / `toAnthropic()` / `toGemini()` | provider tool schemas |
|
|
178
|
-
| `tk.
|
|
253
|
+
| `tk.serve(addr, { client, a2a?, onTask? })` | serve the toolkit as an A2A agent → `ServeHandle` |
|
|
254
|
+
| `tk.addAgent(cardUrl \| Agent)` | fetch a remote agent's card and register its skills as tools |
|
|
179
255
|
| `tk.close()` | disconnect MCP servers |
|
|
256
|
+
| `defineTool` / `httpTool` / `agent` | build native / HTTP / A2A tools |
|
|
257
|
+
| `InMemoryConversationStore` · `InMemoryTaskStore` / `FileTaskStore` | default stores (memory / A2A tasks) |
|
|
180
258
|
|
|
181
259
|
## More
|
|
182
260
|
|
|
183
|
-
Full docs, the other four language ports, the shared behavior
|
|
184
|
-
|
|
261
|
+
Full docs, the other four language ports, and the shared cross-language behavior contract
|
|
262
|
+
([`SPEC.md`](https://github.com/muthuishere/toolnexus/blob/main/SPEC.md)) — plus runnable
|
|
263
|
+
`examples/`: **https://github.com/muthuishere/toolnexus**
|
|
185
264
|
|
|
186
265
|
MIT licensed.
|