@warlock.js/ai-tools 5.29.0 → 5.31.0

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to `@warlock.js/ai-tools` are documented in this file.
 
 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.
 
+## 5.31.0 - 2026-10-18
+
+### Added
+
+- `ai.mcp(server, { signal })` binds the client to a run: when the signal aborts the client closes its transport, and later handshakes and tool calls fail with an `McpTransportError` of type `"closed"`. Every `tools/call` honors both the client signal and the per-call `ctx.signal`.
+- `ai.tools.measure(tools, { model, mode })` — the `measureTools` helper from `@warlock.js/ai` — measures the input tokens a tool list costs per call.
+- `ai.mcp.serve(source, { transport: { type: "http" } })` serves the MCP Streamable HTTP transport on `node:http` (no extra dependency). It binds `127.0.0.1` on a free port at `/mcp` by default (`host`, `port`, `path` override them), and `start()` resolves `{ url, close }`. `close()` stops accepting connections, waits up to `drainTimeoutMs` (default 5 s) for in-flight calls, then aborts their `ctx.signal` and frees the port. The endpoint is stateless: JSON responses, `202` for notifications, `405` for `GET` / `DELETE`, `400` for batches or an unsupported `MCP-Protocol-Version`.
+- HTTP auth: `auth: { bearer }` accepts one token or a rotation list; `auth: { authorize(request) }` runs a custom check; with both set, a request must pass both. Failures get `401` before the body is read.
+- Tools served over HTTP receive the inbound request on `ctx.request` (`headers`, `remoteAddress`), for per-user tokens, tenant headers or trace ids.
+- Grouped sources: `serve({ groups: { name: tools } }, { prefixToolNames: true })` exposes `<group>_<tool>`; a function builds custom names.
+- Optional MCP resources (`resources: [{ uri, name, read }]`) and prompts (`prompts: [{ name, arguments, get }]`), with their capabilities advertised only when configured. The server also answers `ping`.
+- `McpServeError` (`type`: `"collision"`, `"config"`, `"listen"`), `SUPPORTED_PROTOCOL_VERSIONS`, and the `McpHttpServeTransport`, `McpHttpAuth`, `McpHttpRequestInfo`, `McpServeHandle`, `McpHttpServeHandle`, `McpServeResource`, `McpServePrompt`, `McpServeCallContext`, `McpToolSource`, `McpGroupedToolSource` types. `createServeHandler(...).handle(request, context?)` takes an optional call context.
+
+### Changed
+
+- `initialize` negotiates the protocol version: a client's requested version is echoed when supported (`2025-11-25`, `2025-06-18`, `2025-03-26`), otherwise the newest is offered. It previously always answered `2025-06-18`.
+- `McpServer.start()` resolves a handle (`{ url?, close }`) instead of `void`. The http transport's `port` is optional.
+- `@modelcontextprotocol/sdk` is no longer listed as an optional peer dependency. The MCP client never imported it: it speaks MCP's JSON-RPC itself over a child process (stdio) and `fetch` (http). The SDK is now a development dependency, used only by the interoperability test against the official client. The MCP docs, README and `connect-mcp-server` skill now say so, and name `ajv` as the client's only optional peer.
+
+### Fixed
+
+- The stdio transport of `ai.mcp.serve()` no longer crashes the process when a line is JSON but not a request object (`null`, a number, an array): it answers a JSON-RPC "Invalid Request" error (`-32600`, `id: null`). A failure while answering a line is answered as an internal error and can no longer become an unhandled rejection.
+
+### Security
+
+- The HTTP transport binds loopback by default and refuses to start on any non-loopback host without `auth` (`McpServeError`, `type: "config"`).
+- Bearer tokens are compared with `crypto.timingSafeEqual` over SHA-256 digests, so neither content nor length leaks through timing; every configured token is checked. Empty tokens are refused, and an `authorize` hook that throws denies the request.
+- `Origin` is validated on every request, per the MCP transport's DNS-rebinding guidance: loopback origins and `allowedOrigins` pass, others (including `null`) get `403`. While bound to loopback, a `Host` header other than `localhost`, `127.0.0.1`, `[::1]` or `allowedHosts` also gets `403`.
+- Request bodies over `maxBodyBytes` (default 1 MiB) get `413` and the connection is closed.
+
+### Upgrading
+
+- **BREAKING:** `ai.mcp.serve()` throws `McpServeError` (`type: "collision"`) when two exposed tools share a name, and for duplicate resource URIs or prompt names. Previously both tools were listed and every call reached the last one. Rename one tool, or serve a grouped source with `prefixToolNames: true`.
+- `serve(..., { transport: { type: "http" } }).start()` no longer rejects: it binds a real endpoint. Code that implemented `McpServer` itself must return a handle from `start()`.
+
+## 5.30.0 - 2026-10-16
+
+### Changed
+
+- Lockstep release; package APIs are unchanged.
+
 ## 5.29.0 - 2026-10-01
 
 ### Changed
@@ -75,6 +116,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Changed
@@ -138,7 +180,7 @@ changelogs.
 
 ### Security
 
-- **`fetch_url` and `http_request` now deny private-network targets by default and route through `@warlock.js/ai`'s hardened `guardedFetch` instead of a local host check.** Previously `allowHosts` was the *only* SSRF guardrail and it was opt-in — a bare `ai.tools.fetchUrl()` / `ai.tools.http()` would fetch any `http(s)` URL the model supplied, including `http://169.254.169.254/latest/meta-data/...`, `localhost`, and RFC1918 addresses, and neither tool re-validated redirect targets, so even a configured allowlist could be 302'd into an internal endpoint. Both tools now issue every request through the core outbound policy, which by default refuses private / loopback / link-local / CGNAT / cloud-metadata addresses — resolving hostnames through DNS and checking every returned address, failing closed on resolution failure — and re-validates every redirect `Location` (scheme, allowlist, private-IP deny) before following it, with a hop cap and cross-origin credential-header stripping. Blocks surface as the existing typed errors (`WebToolError` `type: "denied-host"`, `HttpPolicyError` `type: "host-not-allowed"`), so agents still read them as `{ error }` data
+- **`fetch_url` and `http_request` now deny private-network targets by default and route through `@warlock.js/ai`'s hardened `guardedFetch` instead of a local host check.** Previously `allowHosts` was the _only_ SSRF guardrail and it was opt-in — a bare `ai.tools.fetchUrl()` / `ai.tools.http()` would fetch any `http(s)` URL the model supplied, including `http://169.254.169.254/latest/meta-data/...`, `localhost`, and RFC1918 addresses, and neither tool re-validated redirect targets, so even a configured allowlist could be 302'd into an internal endpoint. Both tools now issue every request through the core outbound policy, which by default refuses private / loopback / link-local / CGNAT / cloud-metadata addresses — resolving hostnames through DNS and checking every returned address, failing closed on resolution failure — and re-validates every redirect `Location` (scheme, allowlist, private-IP deny) before following it, with a hop cap and cross-origin credential-header stripping. Blocks surface as the existing typed errors (`WebToolError` `type: "denied-host"`, `HttpPolicyError` `type: "host-not-allowed"`), so agents still read them as `{ error }` data
 - **New `allowPrivateNetwork` option (default `false`) on both tools** for the deliberate case of a tool that must call an internal service (e.g. a local dev server); `allowHosts` still works and now also constrains redirect targets
 
 ## 4.12.0

package/README.md

@@ -14,13 +14,13 @@ All five tools attach onto the shared `ai` object at import time under the `ai.t
 (via a `declare module "@warlock.js/ai"` augmentation), so a bare `import "@warlock.js/ai-tools"`
 makes them available and statically typed.
 
-| Tool | LLM-visible name | What it does |
-|---|---|---|
-| `ai.tools.webSearch(options)` | `web_search` | Web search via a chosen provider (`tavily` / `brave` / `serpapi`) — ranked title/URL/snippet hits. |
-| `ai.tools.fetchUrl(options?)` | `fetch_url` | Fetch a URL → readability `text` (default), raw `html`, or `markdown`; host allowlist + byte cap. |
-| `ai.tools.http(options?)` | `http_request` | A guarded HTTP/REST client — method + host allowlists, `baseUrl` join, byte/timeout caps. |
-| `ai.tools.calculator(options?)` | `calculator` | A SAFE arithmetic evaluator (shunting-yard; never `eval`/`Function`). |
-| `ai.tools.dateTime(options?)` | `date_time` | `now` / `add` / `diff` / `format` over ISO-8601 instants, IANA time zones. |
+| Tool                            | LLM-visible name | What it does                                                                                       |
+| ------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
+| `ai.tools.webSearch(options)`   | `web_search`     | Web search via a chosen provider (`tavily` / `brave` / `serpapi`) — ranked title/URL/snippet hits. |
+| `ai.tools.fetchUrl(options?)`   | `fetch_url`      | Fetch a URL → readability `text` (default), raw `html`, or `markdown`; host allowlist + byte cap.  |
+| `ai.tools.http(options?)`       | `http_request`   | A guarded HTTP/REST client — method + host allowlists, `baseUrl` join, byte/timeout caps.          |
+| `ai.tools.calculator(options?)` | `calculator`     | A SAFE arithmetic evaluator (shunting-yard; never `eval`/`Function`).                              |
+| `ai.tools.dateTime(options?)`   | `date_time`      | `now` / `add` / `diff` / `format` over ISO-8601 instants, IANA time zones.                         |
 
 ## MCP — both directions
 
@@ -39,7 +39,7 @@ npm install @warlock.js/ai-tools
 ```
 
 `@warlock.js/ai` is the only required runtime peer. Everything heavy — a search provider, the
-readability scraper, the MCP SDK, and a JSON-Schema validator — is an **optional peer**, lazily
+readability scraper, and a JSON-Schema validator — is an **optional peer**, lazily
 `import()`ed only when the relevant path runs; a missing one surfaces a curated `npm install` string
 rather than crashing at import time. Beyond `@warlock.js/ai` the package uses only Node built-ins and
 the global `fetch` (Node 18+). Import the package once for its side effect so the surface is
@@ -54,7 +54,7 @@ import "@warlock.js/ai-tools";
 ### 1. An agent with web search + HTTP
 
 Hand an agent the web tools and let it research, then hit an API — both bounded by a host allowlist.
-A failing tool call comes back as `{ error }` *data*, so the agent self-corrects instead of crashing.
+A failing tool call comes back as `{ error }` _data_, so the agent self-corrects instead of crashing.
 
 ```ts
 import "@warlock.js/ai-tools"; // registers ai.tools.* + ai.mcp on import
@@ -114,16 +114,28 @@ so Cursor / Claude Desktop / any MCP client can call these tools.
 ```ts
 import "@warlock.js/ai-tools";
 
-const server = ai.mcp.serve(
-  [ai.tools.calculator(), ai.tools.dateTime()],
-  { name: "warlock-utils", transport: { type: "stdio" } },
-);
+const server = ai.mcp.serve([ai.tools.calculator(), ai.tools.dateTime()], {
+  name: "warlock-utils",
+  transport: { type: "stdio" },
+});
 
 await server.start();
 // ...later:
 await server.stop();
 ```
 
+Over Streamable HTTP, `start()` binds a loopback endpoint and resolves `{ url, close }`. A
+non-loopback `host` requires `auth`; `Origin` is validated and bodies are size-capped:
+
+```ts
+const { url, close } = await ai.mcp
+  .serve([ai.tools.calculator()], {
+    name: "session-tools",
+    transport: { type: "http", auth: { bearer: sessionToken } }, // 127.0.0.1, free port, /mcp
+  })
+  .start();
+```
+
 ## Errors flow as data, not throws
 
 Every tool follows the framework's errors-as-data contract: a guardrail rejection or a failed call is