@warlock.js/ai-tools 5.34.1 → 5.34.3
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/CHANGELOG.md +12 -0
- package/README.md +1 -1
- package/llms-full.txt +28 -3
- package/llms.txt +4 -3
- package/package.json +2 -2
- package/skills/index.md +2 -2
- package/skills/README.md +0 -17
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,18 @@ All notable changes to `@warlock.js/ai-tools` are documented in this file.
|
|
|
4
4
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
|
|
6
6
|
|
|
7
|
+
## 5.34.3 - 2026-10-20
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- Condensed the package agent skill description to at most 450 characters, with API names and package routing guidance.
|
|
12
|
+
|
|
13
|
+
## 5.34.2 - 2026-10-19
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- Qualify custom-tool guidance as a topic of @warlock.js/ai, remove the redundant loose skill catalog, and include package orientation in LLM projections.
|
|
18
|
+
|
|
7
19
|
## 5.34.1 - 2026-10-19
|
|
8
20
|
|
|
9
21
|
### Added
|
package/README.md
CHANGED
|
@@ -162,7 +162,7 @@ if (error instanceof HttpPolicyError && error.type === "host-not-allowed") {
|
|
|
162
162
|
|
|
163
163
|
## Skills
|
|
164
164
|
|
|
165
|
-
Progressive-disclosure, per-task docs live under [`skills/`](./skills/
|
|
165
|
+
Progressive-disclosure, per-task docs live under [`skills/`](./skills/index.md):
|
|
166
166
|
|
|
167
167
|
- [`use-web-and-http-tools/`](./skills/use-web-and-http-tools/SKILL.md) — wire `web_search`, `fetch_url`,
|
|
168
168
|
`http_request`, `calculator`, and `date_time` into an agent under their guardrails.
|
package/llms-full.txt
CHANGED
|
@@ -4,7 +4,32 @@
|
|
|
4
4
|
|
|
5
5
|
> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/ai-tools/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Package orientation
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
description: 'Ready-made AI tools and MCP client/server support: `mcp`, `serve`, `webSearchTool`, `fetchUrlTool`, `httpRequestTool`, `calculatorTool` and `dateTimeTool`; also mounts `ai.mcp` and `ai.tools`. Use for "connect an MCP server", "serve tools over MCP", "search the web" or "fetch a URL". Not this package → @warlock.js/ai for custom tools and agents; @warlock.js/ai-workspace for filesystem and shell tools.'
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# @warlock.js/ai-tools
|
|
14
|
+
|
|
15
|
+
A belt of prebuilt tools for `@warlock.js/ai` agents plus the Model Context Protocol bridge in both directions. Importing the package attaches `ai.tools.*` and `ai.mcp` onto the shared `ai` object; the factories are also exported directly.
|
|
16
|
+
|
|
17
|
+
## The 80% path
|
|
18
|
+
|
|
19
|
+
1. Give an agent web or API access with the factories (`use-web-and-http-tools.md`); pass the results in the agent's `tools` array.
|
|
20
|
+
2. Consume tools from an external MCP server (`connect-mcp-server.md`); they arrive as normal agent tools.
|
|
21
|
+
3. Publish your own tools to MCP clients such as editors or agent CLIs, over stdio or a loopback HTTP endpoint with a bearer token (`expose-as-mcp-server.md`).
|
|
22
|
+
|
|
23
|
+
## Conventions and pitfalls
|
|
24
|
+
|
|
25
|
+
- Direction A (`connect-mcp-server.md`) consumes; Direction B (`expose-as-mcp-server.md`) serves. Do not mix them up.
|
|
26
|
+
- `fetchUrlTool` and `httpRequestTool` are policy-gated: set host allowlists and byte caps rather than opening them fully.
|
|
27
|
+
- `webSearchTool` needs a search provider choice and its API key (tavily, brave, or serpapi).
|
|
28
|
+
- Every error class extends the `AIError` of `@warlock.js/ai`; catch by subclass.
|
|
29
|
+
- Writing a custom tool with `ai.tool()` is covered by the `define-ai-tool` topic of the `@warlock.js/ai` package.
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
## connect-mcp-server `@warlock.js/ai-tools/skills/connect-mcp-server/SKILL.md`
|
|
8
33
|
|
|
9
34
|
---
|
|
10
35
|
name: connect-mcp-server
|
|
@@ -143,7 +168,7 @@ The MCP client does not use `@modelcontextprotocol/sdk`: it speaks MCP's JSON-RP
|
|
|
143
168
|
- The `run-ai-agent` topic of the `warlock-js-ai` skill — running the agent that consumes the adapted tools.
|
|
144
169
|
|
|
145
170
|
|
|
146
|
-
## expose-as-mcp-server `@warlock.js/ai-tools/expose-as-mcp-server/SKILL.md`
|
|
171
|
+
## expose-as-mcp-server `@warlock.js/ai-tools/skills/expose-as-mcp-server/SKILL.md`
|
|
147
172
|
|
|
148
173
|
---
|
|
149
174
|
name: expose-as-mcp-server
|
|
@@ -565,7 +590,7 @@ Mounting it in your own server means you own Origin validation, auth and body li
|
|
|
565
590
|
- The `use-a-workspace` topic of the `warlock-js-ai-workspace` skill — a workspace whose `tools.all()` is a natural `serve` source.
|
|
566
591
|
|
|
567
592
|
|
|
568
|
-
## use-web-and-http-tools `@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md`
|
|
593
|
+
## use-web-and-http-tools `@warlock.js/ai-tools/skills/use-web-and-http-tools/SKILL.md`
|
|
569
594
|
|
|
570
595
|
---
|
|
571
596
|
name: use-web-and-http-tools
|
package/llms.txt
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
## Skills
|
|
8
8
|
|
|
9
|
-
- [
|
|
10
|
-
- [
|
|
11
|
-
- [
|
|
9
|
+
- [Package orientation](@warlock.js/ai-tools/skills/index.md): Ready-made AI tools and MCP client/server support: `mcp`, `serve`, `webSearchTool`, `fetchUrlTool`, `httpRequestTool`, `calculatorTool` and `dateTimeTool`; also mounts `ai.mcp` and `ai.tools`. Use for "connect an MCP server", "serve tools over MCP", "search the web" or "fetch a URL". Not this package → @warlock.js/ai for custom tools and agents; @warlock.js/ai-workspace for filesystem and shell tools.
|
|
10
|
+
- [connect-mcp-server](@warlock.js/ai-tools/skills/connect-mcp-server/SKILL.md): Connect a @warlock.js/ai agent to an external Model Context Protocol (MCP) server and adapt its tools as native agent tools (Direction A) with `ai.mcp(server)`. Triggers: `signal`, `ai.mcp(`, `ai.mcp.serve` (the other direction), `mcp(`, `McpClient`, `McpClientOptions`, `McpTransport`, `client.tools()`, `client.close()`, `namePrefix`, `filter`, `McpTransportError`, `{ type: "stdio" }`, `{ type: "http" }`, `tools/list`, `tools/call`, `jsonSchemaToStandard`, `@modelcontextprotocol/sdk`, `ajv`; 'consume an MCP server', 'use an external MCP server's tools in my agent', 'connect to the GitHub/Slack/Filesystem MCP server', 'adapt MCP tools as agent tools', 'bridge my agent to the MCP ecosystem', 'run an MCP server over stdio/http'; typical import `import "@warlock.js/ai-tools"; import { ai } from "@warlock.js/ai"`. Skip: exposing YOUR agent/tools AS an MCP server (the reverse direction) — the `expose-as-mcp-server` topic; the built-in web/HTTP/calc/date tools — the `use-web-and-http-tools` topic.
|
|
11
|
+
- [expose-as-mcp-server](@warlock.js/ai-tools/skills/expose-as-mcp-server/SKILL.md): Expose a @warlock.js/ai agent / supervisor / orchestrator (or a raw ToolContract[], or named tool groups) AS a Model Context Protocol (MCP) server other clients consume (Direction B) with `ai.mcp.serve(source, options)` — over stdio or authenticated Streamable HTTP. Triggers: `ai.mcp.serve(`, `serve(`, `createServeHandler`, `McpServer`, `McpServeOptions`, `McpServeSource`, `McpServeTransport`, `McpHttpServeTransport`, `McpHttpAuth`, `onAuthRefusal`, `McpHttpAuthRefusal`, `McpServeError`, `server.start()`, `server.stop()`, `{ url, close }`, `{ type: "http", host, port, path, auth }`, `bearer`, `authorize`, `authenticate`, `beforeCall`, `listFilter`, `validateCallParams`, `McpError`, `routes`, `McpHttpRouteContext`, `requestId`, `principal`, `notifications/cancelled`, `allowedOrigins`, `maxBodyBytes`, `prefixToolNames`, `groups`, `resources`, `prompts`, `ctx.request.headers`, `schemaTarget`, `tools/list`, `tools/call`, `{ type: "stdio" }`; 'expose my agent as an MCP server', 'serve my tools over HTTP', 'give each agent session its own MCP endpoint', 'protect my MCP server with a token', 'publish my tools to Cursor/Claude Desktop', 'serve MCP resources or prompts', 'tool name collision'; typical import `import "@warlock.js/ai-tools"; import { ai } from "@warlock.js/ai"`. Skip: CONSUMING an external MCP server (the reverse direction) — the `connect-mcp-server` topic; the built-in web/HTTP/calc/date tools — the `use-web-and-http-tools` topic.
|
|
12
|
+
- [use-web-and-http-tools](@warlock.js/ai-tools/skills/use-web-and-http-tools/SKILL.md): Wire the @warlock.js/ai-tools belt — web search, fetch/scrape, HTTP/REST, calculator, date-time — into an agent under their guardrails. Triggers: `ai.tools.measure`, `measureTools`, `ai.tools.webSearch`, `ai.tools.fetchUrl`, `ai.tools.http`, `ai.tools.calculator`, `ai.tools.dateTime`, `webSearchTool`, `fetchUrlTool`, `httpRequestTool`, `calculatorTool`, `dateTimeTool`, `web_search`, `fetch_url`, `http_request`, `calculator`, `date_time`, `WebToolError`, `HttpPolicyError`, `CalculatorError`, `DateTimeError`, `allowHosts`, `allowMethods`, `allowPrivateNetwork`, `baseUrl`, `maxBytes`, `guardedFetch`, `SearchProvider`, `TAVILY_API_KEY`; 'give an agent web search', 'let an agent fetch/scrape a page', 'let an agent call a REST API', 'restrict which hosts/methods an agent can hit', 'add a calculator/date tool to an agent', 'SSRF guardrail for an agent tool', 'let a tool reach an internal/dev service'; typical import `import "@warlock.js/ai-tools"; import { ai } from "@warlock.js/ai"`. Skip: connecting to an external MCP server — the `connect-mcp-server` topic; exposing tools AS an MCP server — the `expose-as-mcp-server` topic; filesystem/shell tools — the `use-a-workspace` topic of the `warlock-js-ai-workspace` skill; defining your own custom tool — the `define-ai-tool` topic of the `warlock-js-ai` skill.
|
package/package.json
CHANGED
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
"peerDependencies": {
|
|
23
23
|
"@mozilla/readability": "*",
|
|
24
24
|
"@tavily/core": "*",
|
|
25
|
-
"@warlock.js/ai": "5.34.
|
|
25
|
+
"@warlock.js/ai": "5.34.3",
|
|
26
26
|
"ajv": "*",
|
|
27
27
|
"jsdom": "*"
|
|
28
28
|
},
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
"dependencies": {
|
|
44
44
|
"@standard-schema/spec": "^1.0.0"
|
|
45
45
|
},
|
|
46
|
-
"version": "5.34.
|
|
46
|
+
"version": "5.34.3",
|
|
47
47
|
"main": "./cjs/index.cjs",
|
|
48
48
|
"module": "./esm/index.mjs",
|
|
49
49
|
"types": "./esm/index.d.mts",
|
package/skills/index.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description:
|
|
2
|
+
description: 'Ready-made AI tools and MCP client/server support: `mcp`, `serve`, `webSearchTool`, `fetchUrlTool`, `httpRequestTool`, `calculatorTool` and `dateTimeTool`; also mounts `ai.mcp` and `ai.tools`. Use for "connect an MCP server", "serve tools over MCP", "search the web" or "fetch a URL". Not this package → @warlock.js/ai for custom tools and agents; @warlock.js/ai-workspace for filesystem and shell tools.'
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# @warlock.js/ai-tools
|
|
@@ -18,4 +18,4 @@ A belt of prebuilt tools for `@warlock.js/ai` agents plus the Model Context Prot
|
|
|
18
18
|
- `fetchUrlTool` and `httpRequestTool` are policy-gated: set host allowlists and byte caps rather than opening them fully.
|
|
19
19
|
- `webSearchTool` needs a search provider choice and its API key (tavily, brave, or serpapi).
|
|
20
20
|
- Every error class extends the `AIError` of `@warlock.js/ai`; catch by subclass.
|
|
21
|
-
- Writing a custom tool with `ai.tool()`
|
|
21
|
+
- Writing a custom tool with `ai.tool()` is covered by the `define-ai-tool` topic of the `@warlock.js/ai` package.
|
package/skills/README.md
DELETED
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
# `@warlock.js/ai-tools` — skills index
|
|
2
|
-
|
|
3
|
-
Per-task skills. Cross-references name the topic ("the `<topic>` topic"), and for another package add its skill ("the `<topic>` topic of the `warlock-js-<pkg>` skill").
|
|
4
|
-
|
|
5
|
-
## Skills
|
|
6
|
-
|
|
7
|
-
### `use-web-and-http-tools`
|
|
8
|
-
|
|
9
|
-
Wire the five ready-made tools — `ai.tools.webSearch` (`web_search`), `ai.tools.fetchUrl` (`fetch_url`), `ai.tools.http` (`http_request`), `ai.tools.calculator` (`calculator`), and `ai.tools.dateTime` (`date_time`) — into an agent under their construction-time rails: a search provider + API-key fallback, readability extract modes, the host/method allowlists and byte/timeout caps (the SSRF guardrails), the safe shunting-yard calculator, and the millisecond-unit date-time ops. Covers the option vs per-call-input split, the typed `WebToolError` / `HttpPolicyError` / `CalculatorError` / `DateTimeError`, and the errors-as-data contract. Load when giving an agent web search, fetch/scrape, REST, calculator, or date tools.
|
|
10
|
-
|
|
11
|
-
### `connect-mcp-server`
|
|
12
|
-
|
|
13
|
-
Connect an agent to an external Model Context Protocol server with `ai.mcp(server, options?)` and adapt each of its tools into a native `ToolContract` (Direction A). Covers the stdio (`node:child_process`, no dep) vs Streamable HTTP transport, `namePrefix` / `filter` / `timeoutMs`, the lazy-and-cached `client.tools()` handshake + `tools/list`, the JSON-Schema→Standard-Schema adaptation (Ajv optional peer), the `kind`→`type` translation, and the `McpTransportError` surface. Load when consuming an MCP server's tools inside a warlock agent.
|
|
14
|
-
|
|
15
|
-
### `expose-as-mcp-server`
|
|
16
|
-
|
|
17
|
-
Expose a warlock agent / supervisor / orchestrator (or a raw `ToolContract[]`) AS an MCP server with `ai.mcp.serve(source, options)` (Direction B). Covers the `source` shapes (array or `tools()`), the `name` / `version` / `transport` / `schemaTarget` options, how `initialize` / `tools/list` / `tools/call` map (via `extractJsonSchema` and the never-throwing `invoke()`), the auto-pumped stdio transport vs host-owned HTTP, and the `createServeHandler` pure-protocol seam for HTTP wiring and tests. Load when publishing local tools to Cursor / Claude Desktop / any MCP client.
|