agentfootprint 10.2.0 → 10.3.1

package/dist/esm/mcp/mcpClient.js

@@ -0,0 +1,299 @@
+/**
+ * mcpClient — connect to an MCP server, expose its tools to your Agent.
+ *
+ *   const slack = await mcpClient({
+ *     name: 'slack',
+ *     transport: { transport: 'stdio', command: 'npx', args: ['@example/slack-mcp'] },
+ *   });
+ *
+ *   const tools = await slack.tools();   // → readonly Tool[]
+ *   const agent = Agent.create({ ... }).tools(tools).build();
+ *
+ *   // ...
+ *
+ *   await slack.close();
+ *
+ * Pattern: Adapter (GoF) — translates MCP `listTools()` / `callTool()`
+ *          into agentfootprint's `Tool` interface (schema + execute).
+ *          Each MCP tool becomes ONE agentfootprint Tool. The agent's
+ *          existing tool-call handler invokes `client.callTool()`
+ *          inside the wrapped `execute`.
+ *
+ * Role:    Layer-3 integration. Sits next to `defineTool` — same
+ *          shape, different source. Once tools land on the agent,
+ *          the rest of the library doesn't know they came from MCP.
+ *          Since 9.71.0 that is true of DECLARATIONS too: a server's
+ *          `_meta` bag becomes `argumentsFrom` / `resultKind` / `owner`
+ *          / `resultClass` / `resultCeiling` on the registered `Tool`,
+ *          so the integrity checks, the placement mint and the identity
+ *          joins arm for a remote tool exactly as for a local one. The
+ *          reading NEVER throws — see `toolExtras.ts`.
+ *
+ * Emits:   N/A — wrapped tools emit the standard
+ *          `agentfootprint.stream.tool_start` / `tool_end` events
+ *          when the agent calls them. Add `name: '<mcp-server>'` to
+ *          `McpClientOptions` so observability surfaces can group
+ *          tool calls by server.
+ *
+ * Lazy-require pattern: the `@modelcontextprotocol/sdk` peer-dep
+ * loads only when a consumer actually constructs a client. Tests
+ * inject `_client` and skip the import path entirely.
+ */
+import { callMetaOf, readToolExtras } from './toolExtras.js';
+import { readToolResult, resultModeOf } from './toolResult.js';
+import { createVendingFetch } from './gatewayTransport.js';
+import { retryingFetch } from './throttleRetry.js';
+import { refuseConflictingOptions } from './connectionRefusals.js';
+import { sdkLoadFailure } from './sdkLoadFailure.js';
+import { transportUrl } from './transportUrl.js';
+import { lazyRequire } from '../lib/lazyRequire.js';
+// Version-less identity. The MCP `clientInfo` field is informational
+// (server logs it); a hardcoded number drifts every release. Consumers
+// who care about wire-level identity pass `clientInfo` explicitly.
+const DEFAULT_CLIENT_INFO = {
+    name: 'agentfootprint',
+    version: '0.0.0',
+};
+/**
+ * Connect to an MCP server. Returns an `McpClient` that exposes the
+ * server's tools as agentfootprint `Tool[]` and a `close()` to tear
+ * down the transport.
+ *
+ * Three ways to get a connection, and they are three because a browser can
+ * only take the last two:
+ *
+ *   - `{ transport }` — the library loads the SDK through its Node loader and
+ *     builds everything. The default, and what every Node consumer already
+ *     does.
+ *   - `{ transport, sdk }` — you supply the two SDK modules with static
+ *     imports; the library still builds the transport, so gateway vending,
+ *     `retryOnThrottle`, `headers` and your own `fetch` all keep working.
+ *   - `{ connection }` — you built and connected the client yourself; the
+ *     library only adapts its tools.
+ *
+ * @throws when the two arms are mixed, when a `connection` is not one, or when
+ *   `@modelcontextprotocol/sdk` cannot be loaded (the message says which of
+ *   "not installed" and "no Node loader here" actually happened), or when the
+ *   transport fails to connect.
+ */
+export async function mcpClient(opts) {
+    const name = opts.name ?? 'mcp';
+    const resultMode = resultModeOf(opts.resultMode, name);
+    // Before anything connects: an option that names a behaviour which cannot
+    // happen on the chosen arm is a defect, not a preference.
+    refuseConflictingOptions(opts, name);
+    const connection = await openConnection(opts);
+    // Tool cache so consumers calling `.tools()` more than once don't
+    // hammer the server. `.refresh()` invalidates it.
+    let cache = null;
+    let closed = false;
+    const ensureOpen = (op) => {
+        if (closed) {
+            throw new Error(`mcpClient[${name}].${op}() called after close(). Construct a new client to reconnect.`);
+        }
+    };
+    const buildTools = async () => {
+        // `signal` rides in the SDK's THIRD argument (RequestOptions), not in
+        // the request params — see `wrapMcpTool`.
+        const listed = opts.signal
+            ? await connection.listTools(undefined, { signal: opts.signal })
+            : await connection.listTools();
+        return listed.tools.map((t) => wrapMcpTool(name, connection, t, opts.signal, resultMode));
+    };
+    return {
+        name,
+        async tools() {
+            ensureOpen('tools');
+            if (!cache)
+                cache = await buildTools();
+            return cache;
+        },
+        async refresh() {
+            ensureOpen('refresh');
+            cache = await buildTools();
+            return cache;
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            cache = null;
+            await connection.close();
+        },
+    };
+}
+// ─── Getting a connection ──────────────────────────────────────────
+/**
+ * The one funnel every arm passes through, in precedence order: a connection
+ * you handed over, the internal test seam, then the library building one.
+ *
+ * A call with neither `connection` nor `sdk` reaches `resolveClient` with two
+ * `undefined` arguments and takes the identical path it always took.
+ */
+async function openConnection(opts) {
+    if (opts.connection !== undefined)
+        return opts.connection;
+    if (opts._client !== undefined)
+        return opts._client;
+    // `refuseConflictingOptions` has already refused the case where this is
+    // absent, so the assertion documents that guarantee rather than assuming it.
+    const transport = opts.transport;
+    return resolveClient(transport, opts.clientInfo, opts.signal, opts.retryOnThrottle, opts.sdk);
+}
+// ─── SDK construction (lazy require, unless the caller supplied it) ─
+async function resolveClient(transport, clientInfo, signal, retryOnThrottle, sdk) {
+    const mod = sdk ?? loadClientModule();
+    const client = new mod.Client(clientInfo ?? DEFAULT_CLIENT_INFO, {
+        capabilities: {},
+    });
+    const transportImpl = await buildTransport(transport, retryOnThrottle, sdk);
+    // Same rule as callTool: options ride beside the transport, never inside it.
+    if (signal)
+        await client.connect(transportImpl, { signal });
+    else
+        await client.connect(transportImpl);
+    return client;
+}
+/** The Node loader path, unchanged — reached only when no `sdk` was supplied. */
+function loadClientModule() {
+    try {
+        return lazyRequire('@modelcontextprotocol/sdk/client/index.js');
+    }
+    catch (err) {
+        throw new Error(sdkLoadFailure(err, {
+            notInstalled: 'mcpClient requires @modelcontextprotocol/sdk.\n' +
+                '  Install:  npm install @modelcontextprotocol/sdk\n' +
+                '  Or pass `_client` for test injection.',
+            caller: 'mcpClient',
+            specifier: '@modelcontextprotocol/sdk/client/index.js',
+            instead: 'Pass `sdk` (the two SDK modules, imported statically) or `connection` ' +
+                '(a client you connected yourself).',
+        }));
+    }
+}
+async function buildTransport(t, retryOnThrottle, sdk) {
+    if (t.transport === 'stdio') {
+        // Deliberately NOT served by `sdk`: stdio spawns a subprocess, so it can
+        // never run in a browser, and `client/stdio.js` is the SDK's one client
+        // module that imports `node:process`/`node:stream`. Keeping it behind the
+        // loader is what keeps it off every browser module graph.
+        let stdioMod;
+        try {
+            stdioMod = lazyRequire('@modelcontextprotocol/sdk/client/stdio.js');
+        }
+        catch (err) {
+            throw new Error(sdkLoadFailure(err, {
+                notInstalled: 'mcpClient(stdio) requires @modelcontextprotocol/sdk/client/stdio.js — ' +
+                    'check that @modelcontextprotocol/sdk is installed at the latest version.',
+                caller: 'mcpClient(stdio)',
+                specifier: '@modelcontextprotocol/sdk/client/stdio.js',
+                instead: 'stdio spawns a subprocess, so it cannot run in a browser at all — ' +
+                    "reach the server over `transport: { transport: 'http', url }` instead.",
+            }));
+        }
+        return new stdioMod.StdioClientTransport({
+            command: t.command,
+            args: t.args ? [...t.args] : [],
+            ...(t.env && { env: { ...t.env } }),
+            ...(t.cwd !== undefined && { cwd: t.cwd }),
+        });
+    }
+    // http + gateway transports both ride Streamable HTTP. They differ only in
+    // WHEN the auth headers are decided: `http` fixes them at construction,
+    // `gateway` vends them inside every request (see gatewayTransport.ts).
+    const httpMod = sdk ?? loadHttpModule(t.transport);
+    // Throttle retry wraps the OUTERMOST fetch, so every attempt is re-signed
+    // and re-vended: signatures expire, and a token that would have died during
+    // the wait is simply never the one reused. `retryingFetch` returns its input
+    // untouched when retry is off — including `undefined`, so a plain `http`
+    // transport with no custom fetch still passes none and behaves exactly as it
+    // did before 8.11.0.
+    if (t.transport === 'gateway') {
+        // The consumer's own `fetch` (9.32.0) goes UNDERNEATH the vending, not
+        // beside it: `createVendingFetch` resolves the credential, applies it to
+        // this one request, and then calls the base fetch — so an mTLS agent or a
+        // DPoP signer sees the final headers and has the last word, while the
+        // credential is still vended per request. Passing `undefined` is the
+        // default global `fetch`, which is byte-identical to every release before
+        // the seam existed.
+        return new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
+            fetch: retryingFetch(createVendingFetch(t, t.fetch), retryOnThrottle),
+        });
+    }
+    // Both options ride the SAME SDK transport, and both are forwarded when both
+    // are given. The SDK folds `requestInit.headers` into the `init.headers` it
+    // hands the custom fetch, so a signer sees the static headers and has the
+    // final word over the bytes — see `McpHttpTransport.fetch`.
+    const httpFetch = retryingFetch(t.fetch, retryOnThrottle);
+    return new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
+        ...(t.headers && { requestInit: { headers: { ...t.headers } } }),
+        ...(httpFetch && { fetch: httpFetch }),
+    });
+}
+/** The Node loader path for Streamable HTTP — reached only with no `sdk`. */
+function loadHttpModule(transport) {
+    try {
+        return lazyRequire('@modelcontextprotocol/sdk/client/streamableHttp.js');
+    }
+    catch (err) {
+        throw new Error(sdkLoadFailure(err, {
+            notInstalled: `mcpClient(${transport}) requires @modelcontextprotocol/sdk/client/streamableHttp.js — ` +
+                'check that @modelcontextprotocol/sdk is installed at the latest version.',
+            caller: `mcpClient(${transport})`,
+            specifier: '@modelcontextprotocol/sdk/client/streamableHttp.js',
+            instead: 'Pass `sdk` (the two SDK modules, imported statically) or `connection` ' +
+                '(a client you connected yourself).',
+        }));
+    }
+}
+// ─── Tool wrapping ─────────────────────────────────────────────────
+function wrapMcpTool(serverName, connection, mcp, signal, resultMode) {
+    const tool = {
+        schema: {
+            name: mcp.name,
+            description: mcp.description ?? `MCP tool: ${mcp.name}`,
+            inputSchema: mcp.inputSchema,
+        },
+        // Provenance, carried to the decision point. Governance that matches on a
+        // bare tool name cannot tell two servers' identically-named tools apart;
+        // this is the fact that lets it. See `Tool.source`.
+        source: serverName,
+        // The DECLARATIONS the server sent in MCP's `_meta` bag (9.71.0) — read
+        // defensively, per field, by the same rules `defineTool` enforces, and
+        // NEVER throwing: a malformed field is warned about once and dropped, and
+        // this tool still registers. That is what keeps one bad tool from killing
+        // a forty-tool bulk register. A server that sent no bag adds no keys here,
+        // so the Tool is byte-identical to one built before this existed.
+        ...readToolExtras(mcp._meta, {
+            server: serverName,
+            tool: mcp.name,
+            inputSchema: mcp.inputSchema,
+        }),
+        execute: async (args, ctx) => {
+            // The agent passes args as `unknown` per Tool contract. MCP
+            // expects a JSON object — non-object inputs become `{}` rather
+            // than failing the SDK call.
+            const argsObj = args !== null && typeof args === 'object' && !Array.isArray(args)
+                ? args
+                : {};
+            // The abort signal is NOT a request param — it belongs to the SDK's
+            // third argument (`RequestOptions`). Put it in the params object and
+            // it gets serialized onto the wire as an empty `{}` and the call is
+            // uncancellable: a silent no-op that only a real transport reveals.
+            // `resultSchema` (2nd arg) is left to the SDK's own default.
+            // The call's time (`ctx.time`, the time layer) crosses in the request's own
+            // `_meta` bag, under the one namespaced key; a call without it sends no `_meta`.
+            const params = {
+                name: mcp.name,
+                arguments: argsObj,
+                ...(ctx?.time !== undefined && { _meta: callMetaOf(ctx.time) }),
+            };
+            const result = signal
+                ? await connection.callTool(params, undefined, { signal })
+                : await connection.callTool(params);
+            return readToolResult(result, mcp.name, serverName, resultMode);
+        },
+    };
+    return tool;
+}
+//# sourceMappingURL=mcpClient.js.map

package/dist/esm/mcp/mcpClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpClient.js","sourceRoot":"","sources":["../../../src/mcp/mcpClient.ts"],"names":[],"mappings":"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"}

package/dist/esm/mcp/mcpServe.d.ts

@@ -0,0 +1,86 @@
+/**
+ * mcpServe — expose your agentfootprint tools AS an MCP server.
+ *
+ *   const handle = await mcpServe([lookupTool, refundTool], {
+ *     name: 'support-desk',
+ *     version: '1.0.0',
+ *   });
+ *
+ *   // …later
+ *   await handle.close();
+ *
+ * Over HTTP the handle also reports the socket it bound, so `port: 0`
+ * ("any free port") is usable from the outside:
+ *
+ *   const handle = await mcpServe(tools, {
+ *     transport: { transport: 'http', port: 0, host: '127.0.0.1' },
+ *   });
+ *   connect(`http://127.0.0.1:${handle.port}/mcp`);
+ *
+ * `mcpClient` pulls someone else's tools in. This pushes yours out, so
+ * the tool you already wrote, tested and governed can be called by any
+ * MCP client — a desktop host, another team's agent, an IDE — without
+ * being rewritten against a second tool interface.
+ *
+ * Pattern: Adapter (GoF), pointed the other way. `mcpClient` translates
+ *          MCP → `Tool`; this translates `Tool` → MCP. Same SDK, same
+ *          lazy-require discipline, mirrored lifecycle (`close()`).
+ *
+ * ── The one promise worth stating plainly ────────────────────────────
+ * A served tool is THE SAME OBJECT you passed in. `mcpServe` holds your
+ * `Tool` by reference and calls `tool.execute(args, ctx)` — it never
+ * copies the schema and re-implements the body, never unwraps a
+ * decorator, never reaches past a wrapper to an inner tool. So whatever
+ * governance you composed around that tool — a permission check inside
+ * `execute`, a redaction step, an audit hook — is still the thing that
+ * runs when a remote client calls it. Serving is not a second door into
+ * your tool; it is the same door with a longer corridor.
+ *
+ * Two demands the library CANNOT keep over MCP are refused at
+ * construction rather than silently dropped:
+ *   - `checkIn` (human consent before the tool runs) needs a pause
+ *     channel that a request/response protocol does not have.
+ *   - `needs` (declare-and-push credentials) needs a provider; without
+ *     one the tool would run with `ctx.credential` undefined.
+ *
+ * ── Declarations travel; execution does not (9.71.0) ─────────────────
+ * A served tool's DECLARATIONS — `argumentsFrom`, `resultKind`, `owner`,
+ * `resultClass`, `resultCeiling` — are written into MCP's own `_meta` bag
+ * under one namespaced key, so an agentfootprint client arms the checks and
+ * rails that read them exactly as it would for a local `defineTool`. The
+ * execution-side fields never go: see `toolExtras.ts` for the bar and the
+ * reasoning. A tool declaring none of the five lists exactly as before.
+ *
+ * ── Schemas ──────────────────────────────────────────────────────────
+ * Tools already carry JSON Schema in `schema.inputSchema`, and MCP's
+ * `tools/list` wants JSON Schema, so the mapping is the identity
+ * function. That is also why this builds on the SDK's low-level
+ * `Server` rather than its `McpServer` convenience wrapper — the latter
+ * takes zod schemas, which would mean converting a JSON Schema you
+ * already have into zod (a new dependency) to convert it straight back.
+ */
+import type { Tool } from '../tools/tools.js';
+import type { McpServeHandle, McpServeOptions } from './types.js';
+/**
+ * Serve `tools` over MCP. Resolves once the transport is connected (for
+ * `http`, once the socket is listening), so holding the handle means the
+ * server is live.
+ *
+ * @throws at construction when `tools` is empty, when two tools share a
+ *   name, when a tool declares `checkIn`, or when a tool declares `needs`
+ *   without `opts.credentials` — see the module header. Also throws when
+ *   `@modelcontextprotocol/sdk` is not installed.
+ */
+export declare function mcpServe(tools: readonly Tool[], opts?: McpServeOptions): Promise<McpServeHandle>;
+/**
+ * Sentinels handed to an injected `_server` in place of the SDK's zod
+ * schemas. Exported so a test can tell the two handlers apart.
+ * @internal
+ */
+export declare const LIST_TOOLS_SENTINEL: Readonly<{
+    method: "tools/list";
+}>;
+/** @internal @see LIST_TOOLS_SENTINEL */
+export declare const CALL_TOOL_SENTINEL: Readonly<{
+    method: "tools/call";
+}>;