@graphorin/mcp 0.5.0

package/dist/client/defer-loading.js

@@ -0,0 +1,81 @@
+import { incrementCounter } from "@graphorin/tools/audit";
+
+//#region src/client/defer-loading.ts
+/**
+* Deferred-loading resolution for the `toTools()` adapter (extracted
+* from `to-tools.ts` per F-MCP-001).
+*
+* Computes the per-server effective `defer_loading` flag: when the
+* operator does not pass an explicit `defer_loading`, the auto-default
+* fires once when `listTools().length > deferLoadingThreshold` (default
+* `10`) and flips deferral on for every tool from the server. Emits the
+* retrieval counters and the once-per-server INFO log.
+*
+* @packageDocumentation
+*/
+/** Default auto-deferral threshold per the operator-facing convention. */
+const DEFAULT_DEFER_LOADING_THRESHOLD = 10;
+/**
+* Process-scoped dedup keys for the auto-default INFO-log. Each
+* `(serverIdentity, threshold)` pair triggers the log once across all
+* `MCPClient.toTools(...)` invocations in the process so re-running
+* `toTools()` on the same client does not double-log.
+*/
+const autoDeferralInfoSeen = /* @__PURE__ */ new Set();
+/**
+* Process-scoped dedup keys for the explicit `defer_loading: true`
+* INFO-log. Mirrors the auto-default discipline.
+*/
+const explicitDeferralInfoSeen = /* @__PURE__ */ new Set();
+/**
+* Reset the deferral dedup sets. Used by
+* {@link import('./to-tools.js')._resetMcpAdapterDedupForTesting}.
+*
+* @experimental
+*/
+function _resetDeferLoadingDedupForTesting() {
+	autoDeferralInfoSeen.clear();
+	explicitDeferralInfoSeen.clear();
+}
+/**
+* Resolve the effective `defer_loading` flag for a server's tool
+* catalogue and emit the retrieval counters + once-per-server INFO log.
+*/
+function resolveDeferLoading(args) {
+	const total = args.toolNames.length;
+	const autoDeferralFired = args.explicitDefer === void 0 && total > args.threshold;
+	const resolvedDeferLoading = args.explicitDefer ?? autoDeferralFired;
+	if (autoDeferralFired) {
+		for (let i = 0; i < total; i++) incrementCounter("tool.retrieval.deferred.total", { source: "mcp-server-default" });
+		const dedupKey = `${args.serverIdentity.id}:${args.threshold}`;
+		if (!autoDeferralInfoSeen.has(dedupKey) && args.logger !== void 0) {
+			autoDeferralInfoSeen.add(dedupKey);
+			args.logger("info", "mcp.tools.defer_loading.auto-default fired", {
+				server: args.serverIdentity.id,
+				thresholdValue: args.threshold,
+				toolCount: total,
+				toolNames: [...args.toolNames],
+				source: "mcp-server-default"
+			});
+		}
+	} else if (args.explicitDefer === true) {
+		for (let i = 0; i < total; i++) incrementCounter("tool.retrieval.deferred.total", { source: "explicit" });
+		const dedupKey = `${args.serverIdentity.id}:explicit`;
+		if (!explicitDeferralInfoSeen.has(dedupKey) && args.logger !== void 0) {
+			explicitDeferralInfoSeen.add(dedupKey);
+			args.logger("info", "mcp.tools.defer_loading.explicit fired", {
+				server: args.serverIdentity.id,
+				toolCount: total,
+				source: "explicit"
+			});
+		}
+	} else if (args.explicitDefer === false) for (let i = 0; i < total; i++) incrementCounter("tool.retrieval.eager.total", { source: "mcp-explicit-eager" });
+	return {
+		autoDeferralFired,
+		resolvedDeferLoading
+	};
+}
+
+//#endregion
+export { DEFAULT_DEFER_LOADING_THRESHOLD, _resetDeferLoadingDedupForTesting, resolveDeferLoading };
+//# sourceMappingURL=defer-loading.js.map

package/dist/client/defer-loading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defer-loading.js","names":[],"sources":["../../src/client/defer-loading.ts"],"sourcesContent":["/**\n * Deferred-loading resolution for the `toTools()` adapter (extracted\n * from `to-tools.ts` per F-MCP-001).\n *\n * Computes the per-server effective `defer_loading` flag: when the\n * operator does not pass an explicit `defer_loading`, the auto-default\n * fires once when `listTools().length > deferLoadingThreshold` (default\n * `10`) and flips deferral on for every tool from the server. Emits the\n * retrieval counters and the once-per-server INFO log.\n *\n * @packageDocumentation\n */\n\nimport { incrementCounter } from '@graphorin/tools/audit';\nimport type { ServerIdentity } from '../transport/types.js';\n\n/** Default auto-deferral threshold per the operator-facing convention. */\nexport const DEFAULT_DEFER_LOADING_THRESHOLD = 10;\n\n/** Operator-supplied structured logger (mirrors the client logger shape). */\ntype AdapterLogger = (\n  level: 'debug' | 'info' | 'warn' | 'error',\n  message: string,\n  fields?: Record<string, unknown>,\n) => void;\n\n/**\n * Process-scoped dedup keys for the auto-default INFO-log. Each\n * `(serverIdentity, threshold)` pair triggers the log once across all\n * `MCPClient.toTools(...)` invocations in the process so re-running\n * `toTools()` on the same client does not double-log.\n */\nconst autoDeferralInfoSeen = new Set<string>();\n\n/**\n * Process-scoped dedup keys for the explicit `defer_loading: true`\n * INFO-log. Mirrors the auto-default discipline.\n */\nconst explicitDeferralInfoSeen = new Set<string>();\n\n/**\n * Reset the deferral dedup sets. Used by\n * {@link import('./to-tools.js')._resetMcpAdapterDedupForTesting}.\n *\n * @experimental\n */\nexport function _resetDeferLoadingDedupForTesting(): void {\n  autoDeferralInfoSeen.clear();\n  explicitDeferralInfoSeen.clear();\n}\n\n/** Outcome of {@link resolveDeferLoading}. */\nexport interface DeferralResolution {\n  readonly autoDeferralFired: boolean;\n  readonly resolvedDeferLoading: boolean;\n}\n\n/**\n * Resolve the effective `defer_loading` flag for a server's tool\n * catalogue and emit the retrieval counters + once-per-server INFO log.\n */\nexport function resolveDeferLoading(args: {\n  readonly serverIdentity: ServerIdentity;\n  readonly toolNames: ReadonlyArray<string>;\n  readonly explicitDefer: boolean | undefined;\n  readonly threshold: number;\n  readonly logger?: AdapterLogger;\n}): DeferralResolution {\n  const total = args.toolNames.length;\n  const autoDeferralFired = args.explicitDefer === undefined && total > args.threshold;\n  const resolvedDeferLoading = args.explicitDefer ?? autoDeferralFired;\n\n  if (autoDeferralFired) {\n    for (let i = 0; i < total; i++) {\n      incrementCounter('tool.retrieval.deferred.total', { source: 'mcp-server-default' });\n    }\n    const dedupKey = `${args.serverIdentity.id}:${args.threshold}`;\n    if (!autoDeferralInfoSeen.has(dedupKey) && args.logger !== undefined) {\n      autoDeferralInfoSeen.add(dedupKey);\n      args.logger('info', 'mcp.tools.defer_loading.auto-default fired', {\n        server: args.serverIdentity.id,\n        thresholdValue: args.threshold,\n        toolCount: total,\n        toolNames: [...args.toolNames],\n        source: 'mcp-server-default',\n      });\n    }\n  } else if (args.explicitDefer === true) {\n    for (let i = 0; i < total; i++) {\n      incrementCounter('tool.retrieval.deferred.total', { source: 'explicit' });\n    }\n    const dedupKey = `${args.serverIdentity.id}:explicit`;\n    if (!explicitDeferralInfoSeen.has(dedupKey) && args.logger !== undefined) {\n      explicitDeferralInfoSeen.add(dedupKey);\n      args.logger('info', 'mcp.tools.defer_loading.explicit fired', {\n        server: args.serverIdentity.id,\n        toolCount: total,\n        source: 'explicit',\n      });\n    }\n  } else if (args.explicitDefer === false) {\n    for (let i = 0; i < total; i++) {\n      incrementCounter('tool.retrieval.eager.total', { source: 'mcp-explicit-eager' });\n    }\n  }\n\n  return { autoDeferralFired, resolvedDeferLoading };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAa,kCAAkC;;;;;;;AAe/C,MAAM,uCAAuB,IAAI,KAAa;;;;;AAM9C,MAAM,2CAA2B,IAAI,KAAa;;;;;;;AAQlD,SAAgB,oCAA0C;AACxD,sBAAqB,OAAO;AAC5B,0BAAyB,OAAO;;;;;;AAalC,SAAgB,oBAAoB,MAMb;CACrB,MAAM,QAAQ,KAAK,UAAU;CAC7B,MAAM,oBAAoB,KAAK,kBAAkB,UAAa,QAAQ,KAAK;CAC3E,MAAM,uBAAuB,KAAK,iBAAiB;AAEnD,KAAI,mBAAmB;AACrB,OAAK,IAAI,IAAI,GAAG,IAAI,OAAO,IACzB,kBAAiB,iCAAiC,EAAE,QAAQ,sBAAsB,CAAC;EAErF,MAAM,WAAW,GAAG,KAAK,eAAe,GAAG,GAAG,KAAK;AACnD,MAAI,CAAC,qBAAqB,IAAI,SAAS,IAAI,KAAK,WAAW,QAAW;AACpE,wBAAqB,IAAI,SAAS;AAClC,QAAK,OAAO,QAAQ,8CAA8C;IAChE,QAAQ,KAAK,eAAe;IAC5B,gBAAgB,KAAK;IACrB,WAAW;IACX,WAAW,CAAC,GAAG,KAAK,UAAU;IAC9B,QAAQ;IACT,CAAC;;YAEK,KAAK,kBAAkB,MAAM;AACtC,OAAK,IAAI,IAAI,GAAG,IAAI,OAAO,IACzB,kBAAiB,iCAAiC,EAAE,QAAQ,YAAY,CAAC;EAE3E,MAAM,WAAW,GAAG,KAAK,eAAe,GAAG;AAC3C,MAAI,CAAC,yBAAyB,IAAI,SAAS,IAAI,KAAK,WAAW,QAAW;AACxE,4BAAyB,IAAI,SAAS;AACtC,QAAK,OAAO,QAAQ,0CAA0C;IAC5D,QAAQ,KAAK,eAAe;IAC5B,WAAW;IACX,QAAQ;IACT,CAAC;;YAEK,KAAK,kBAAkB,MAChC,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,IACzB,kBAAiB,8BAA8B,EAAE,QAAQ,sBAAsB,CAAC;AAIpF,QAAO;EAAE;EAAmB;EAAsB"}

package/dist/client/inbound-filters.js

@@ -0,0 +1,65 @@
+import { incrementCounter } from "@graphorin/tools/audit";
+import { applyInboundSanitization } from "@graphorin/tools/inbound";
+
+//#region src/client/inbound-filters.ts
+/**
+* Process-scoped dedup keys for the `pass-through` override WARN. The
+* spec mandates exactly-one WARN per server identity per process — the
+* Set retains the keys for the lifetime of the process. Tests reset via
+* {@link import('./to-tools.js')._resetMcpAdapterDedupForTesting}.
+*/
+const passthroughWarnSeen = /* @__PURE__ */ new Set();
+/**
+* Reset the inbound-filter dedup set. Used by
+* {@link import('./to-tools.js')._resetMcpAdapterDedupForTesting}.
+*
+* @experimental
+*/
+function _resetInboundFiltersDedupForTesting() {
+	passthroughWarnSeen.clear();
+}
+/**
+* Resolve the effective per-server inbound-sanitization policy. MCP
+* tools default to the strictest body-level policy.
+*/
+function resolveInboundPolicy(override) {
+	return override ?? "detect-and-strip-and-wrap";
+}
+/**
+* WARN-once per server when the operator opts out of body-level
+* sanitization. The trust class stays `'mcp-derived'` regardless so the
+* per-step preamble in the agent runtime still fires; the WARN exists so
+* the audit log records the operator's deliberate choice.
+*/
+function warnOnPassthroughOverride(args) {
+	if (args.resolvedInbound !== "pass-through") return;
+	if (passthroughWarnSeen.has(args.serverIdentity.id)) return;
+	passthroughWarnSeen.add(args.serverIdentity.id);
+	incrementCounter("mcp.inbound.sanitization.passthrough-override.warn.total", { server: args.serverIdentity.id });
+	if (args.logger !== void 0) args.logger("warn", "mcp.inbound.sanitization.passthrough-override", {
+		server: args.serverIdentity.id,
+		policy: "pass-through",
+		note: "Body-level prompt-injection sanitization is disabled for this MCP server; the trust class remains 'mcp-derived' so the per-step preamble still fires. The WARN cannot be silenced (deliberate operator-friction)."
+	});
+}
+/**
+* Strip imperative payloads from a tool description before it enters the
+* per-step tool catalogue. The description is never wrapped in the
+* `<<<untrusted_content>>>` envelope (the wrap is reserved for tool
+* result bodies emitted into the conversation history).
+*/
+function sanitizeDescription(args) {
+	const stripPolicy = args.inboundSanitization === "pass-through" ? "pass-through" : "detect-and-strip";
+	return applyInboundSanitization({
+		body: args.description,
+		policy: stripPolicy,
+		trustClass: "mcp-derived",
+		toolName: args.toolName,
+		contentOrigin: `mcp:tool-description:${args.serverIdentity.id}`,
+		failClosed: false
+	}).body;
+}
+
+//#endregion
+export { _resetInboundFiltersDedupForTesting, resolveInboundPolicy, sanitizeDescription, warnOnPassthroughOverride };
+//# sourceMappingURL=inbound-filters.js.map

package/dist/client/inbound-filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-filters.js","names":["stripPolicy: InboundSanitizationPolicy"],"sources":["../../src/client/inbound-filters.ts"],"sourcesContent":["/**\n * Inbound prompt-injection filtering for the `toTools()` adapter\n * (extracted from `to-tools.ts` per F-MCP-001).\n *\n * Owns: the per-server inbound-sanitization default, the once-per-server\n * `pass-through` override WARN, and the tool-description strip applied at\n * registration time. The trust class is pinned to `'mcp-derived'` for\n * every produced tool so the agent runtime's per-step preamble fires\n * regardless of the body-level policy chosen here.\n *\n * @packageDocumentation\n */\n\nimport type { InboundSanitizationPolicy } from '@graphorin/core';\nimport { incrementCounter } from '@graphorin/tools/audit';\nimport { applyInboundSanitization } from '@graphorin/tools/inbound';\nimport type { ServerIdentity } from '../transport/types.js';\n\n/** Operator-supplied structured logger (mirrors the client logger shape). */\ntype AdapterLogger = (\n  level: 'debug' | 'info' | 'warn' | 'error',\n  message: string,\n  fields?: Record<string, unknown>,\n) => void;\n\n/**\n * Process-scoped dedup keys for the `pass-through` override WARN. The\n * spec mandates exactly-one WARN per server identity per process — the\n * Set retains the keys for the lifetime of the process. Tests reset via\n * {@link import('./to-tools.js')._resetMcpAdapterDedupForTesting}.\n */\nconst passthroughWarnSeen = new Set<string>();\n\n/**\n * Reset the inbound-filter dedup set. Used by\n * {@link import('./to-tools.js')._resetMcpAdapterDedupForTesting}.\n *\n * @experimental\n */\nexport function _resetInboundFiltersDedupForTesting(): void {\n  passthroughWarnSeen.clear();\n}\n\n/**\n * Resolve the effective per-server inbound-sanitization policy. MCP\n * tools default to the strictest body-level policy.\n */\nexport function resolveInboundPolicy(\n  override: InboundSanitizationPolicy | undefined,\n): InboundSanitizationPolicy {\n  return override ?? 'detect-and-strip-and-wrap';\n}\n\n/**\n * WARN-once per server when the operator opts out of body-level\n * sanitization. The trust class stays `'mcp-derived'` regardless so the\n * per-step preamble in the agent runtime still fires; the WARN exists so\n * the audit log records the operator's deliberate choice.\n */\nexport function warnOnPassthroughOverride(args: {\n  readonly resolvedInbound: InboundSanitizationPolicy;\n  readonly serverIdentity: ServerIdentity;\n  readonly logger?: AdapterLogger;\n}): void {\n  if (args.resolvedInbound !== 'pass-through') return;\n  if (passthroughWarnSeen.has(args.serverIdentity.id)) return;\n  passthroughWarnSeen.add(args.serverIdentity.id);\n  incrementCounter('mcp.inbound.sanitization.passthrough-override.warn.total', {\n    server: args.serverIdentity.id,\n  });\n  if (args.logger !== undefined) {\n    args.logger('warn', 'mcp.inbound.sanitization.passthrough-override', {\n      server: args.serverIdentity.id,\n      policy: 'pass-through',\n      note: \"Body-level prompt-injection sanitization is disabled for this MCP server; the trust class remains 'mcp-derived' so the per-step preamble still fires. The WARN cannot be silenced (deliberate operator-friction).\",\n    });\n  }\n}\n\n/**\n * Strip imperative payloads from a tool description before it enters the\n * per-step tool catalogue. The description is never wrapped in the\n * `<<<untrusted_content>>>` envelope (the wrap is reserved for tool\n * result bodies emitted into the conversation history).\n */\nexport function sanitizeDescription(args: {\n  readonly description: string;\n  readonly inboundSanitization: InboundSanitizationPolicy;\n  readonly toolName: string;\n  readonly serverIdentity: ServerIdentity;\n}): string {\n  const stripPolicy: InboundSanitizationPolicy =\n    args.inboundSanitization === 'pass-through' ? 'pass-through' : 'detect-and-strip';\n  const outcome = applyInboundSanitization({\n    body: args.description,\n    policy: stripPolicy,\n    trustClass: 'mcp-derived',\n    toolName: args.toolName,\n    contentOrigin: `mcp:tool-description:${args.serverIdentity.id}`,\n    failClosed: false,\n  });\n  return outcome.body;\n}\n"],"mappings":";;;;;;;;;;AA+BA,MAAM,sCAAsB,IAAI,KAAa;;;;;;;AAQ7C,SAAgB,sCAA4C;AAC1D,qBAAoB,OAAO;;;;;;AAO7B,SAAgB,qBACd,UAC2B;AAC3B,QAAO,YAAY;;;;;;;;AASrB,SAAgB,0BAA0B,MAIjC;AACP,KAAI,KAAK,oBAAoB,eAAgB;AAC7C,KAAI,oBAAoB,IAAI,KAAK,eAAe,GAAG,CAAE;AACrD,qBAAoB,IAAI,KAAK,eAAe,GAAG;AAC/C,kBAAiB,4DAA4D,EAC3E,QAAQ,KAAK,eAAe,IAC7B,CAAC;AACF,KAAI,KAAK,WAAW,OAClB,MAAK,OAAO,QAAQ,iDAAiD;EACnE,QAAQ,KAAK,eAAe;EAC5B,QAAQ;EACR,MAAM;EACP,CAAC;;;;;;;;AAUN,SAAgB,oBAAoB,MAKzB;CACT,MAAMA,cACJ,KAAK,wBAAwB,iBAAiB,iBAAiB;AASjE,QARgB,yBAAyB;EACvC,MAAM,KAAK;EACX,QAAQ;EACR,YAAY;EACZ,UAAU,KAAK;EACf,eAAe,wBAAwB,KAAK,eAAe;EAC3D,YAAY;EACb,CAAC,CACa"}

package/dist/client/index.d.ts

@@ -0,0 +1,7 @@
+import { CreateMCPClientOptions, MCPCallToolResult, MCPClient, MCPContentPart, MCPElicitationHandler, MCPElicitationRequest, MCPElicitationResult, MCPPromptDefinition, MCPPromptMessage, MCPResourceContent, MCPResourceDefinition, MCPSamplingContent, MCPSamplingHandler, MCPSamplingMessage, MCPSamplingRequest, MCPSamplingResult, MCPToToolsOptions, MCPToolDefinition } from "./types.js";
+import { _resetSseWarnDedupForTesting, createMCPClient } from "./client.js";
+import { McpResourceReaderOptions, createMcpResourceReader } from "./mcp-resource-reader.js";
+import { adaptCallResult } from "./adapt-result.js";
+import { DEFAULT_DEFER_LOADING_THRESHOLD } from "./defer-loading.js";
+import { _resetMcpAdapterDedupForTesting, adaptMCPTools } from "./to-tools.js";
+export { type CreateMCPClientOptions, DEFAULT_DEFER_LOADING_THRESHOLD, type MCPCallToolResult, type MCPClient, type MCPContentPart, type MCPElicitationHandler, type MCPElicitationRequest, type MCPElicitationResult, type MCPPromptDefinition, type MCPPromptMessage, type MCPResourceContent, type MCPResourceDefinition, type MCPSamplingContent, type MCPSamplingHandler, type MCPSamplingMessage, type MCPSamplingRequest, type MCPSamplingResult, type MCPToToolsOptions, type MCPToolDefinition, type McpResourceReaderOptions, _resetMcpAdapterDedupForTesting, _resetSseWarnDedupForTesting, adaptCallResult, adaptMCPTools, createMCPClient, createMcpResourceReader };

package/dist/client/index.js

@@ -0,0 +1,7 @@
+import { adaptCallResult } from "./adapt-result.js";
+import { DEFAULT_DEFER_LOADING_THRESHOLD } from "./defer-loading.js";
+import { _resetMcpAdapterDedupForTesting, adaptMCPTools } from "./to-tools.js";
+import { _resetSseWarnDedupForTesting, createMCPClient } from "./client.js";
+import { createMcpResourceReader } from "./mcp-resource-reader.js";
+
+export { DEFAULT_DEFER_LOADING_THRESHOLD, _resetMcpAdapterDedupForTesting, _resetSseWarnDedupForTesting, adaptCallResult, adaptMCPTools, createMCPClient, createMcpResourceReader };

package/dist/client/mcp-resource-reader.d.ts

@@ -0,0 +1,22 @@
+import { MCPClient } from "./types.js";
+import { ResultReader } from "@graphorin/tools/result";
+
+//#region src/client/mcp-resource-reader.d.ts
+
+/** Configuration for {@link createMcpResourceReader}. */
+interface McpResourceReaderOptions {
+  /** Clients consulted (in order) to resolve a resource URI. */
+  readonly clients: ReadonlyArray<MCPClient>;
+  /** Default `maxBytes` when `read(...)` is called without one. Default `65536`. */
+  readonly defaultMaxBytes?: number;
+}
+/**
+ * Build a {@link ResultReader} that resolves MCP resource URIs through
+ * one or more connected {@link MCPClient}s.
+ *
+ * @stable
+ */
+declare function createMcpResourceReader(opts: McpResourceReaderOptions): ResultReader;
+//#endregion
+export { McpResourceReaderOptions, createMcpResourceReader };
+//# sourceMappingURL=mcp-resource-reader.d.ts.map

package/dist/client/mcp-resource-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-resource-reader.d.ts","names":[],"sources":["../../src/client/mcp-resource-reader.ts"],"sourcesContent":[],"mappings":";;;;;;UA4BiB,wBAAA;;oBAEG,cAAc;;;;;;;;;;iBAWlB,uBAAA,OAA8B,2BAA2B"}

package/dist/client/mcp-resource-reader.js

@@ -0,0 +1,113 @@
+import { incrementCounter } from "@graphorin/tools/audit";
+
+//#region src/client/mcp-resource-reader.ts
+/**
+* {@link createMcpResourceReader} — resolve MCP `resource_link` handles
+* on demand (WI-13 / P2-2, ties to WI-10 result handles).
+*
+* The `toTools()` adapter surfaces an MCP `resource_link` as a preview +
+* the resource `uri` (the {@link import('@graphorin/tools/result').ResultReader}
+* handle) instead of inlining the body. This reader resolves that handle
+* via {@link MCPClient.readResource} when the model later calls the
+* built-in `read_result` tool — so a large MCP resource never inflates
+* context until the model actually asks for it.
+*
+* Compose it with the agent's spill-file reader (the agent tries each
+* configured reader in order): the spill reader claims
+* `graphorin-spill:` handles, this reader resolves the rest. With more
+* than one MCP client, the reader tries each until one server resolves
+* the URI.
+*
+* Network note (R4): this reader performs no I/O until `read(...)` is
+* called, and then only over a connection the operator already opened.
+*
+* @packageDocumentation
+*/
+/**
+* Build a {@link ResultReader} that resolves MCP resource URIs through
+* one or more connected {@link MCPClient}s.
+*
+* @stable
+*/
+function createMcpResourceReader(opts) {
+	const clients = [...opts.clients];
+	const defaultMaxBytes = opts.defaultMaxBytes ?? 65536;
+	return { async read(uri, range) {
+		if (clients.length === 0) throw new Error("createMcpResourceReader: no MCP clients configured to resolve resource handles.");
+		let lastError;
+		for (const client of clients) {
+			let content;
+			try {
+				content = await client.readResource(uri);
+			} catch (err) {
+				lastError = err;
+				continue;
+			}
+			incrementCounter("mcp.resource-link.resolved.total", { server: client.serverIdentity.id });
+			return sliceResource(content, range, defaultMaxBytes);
+		}
+		const suffix = lastError instanceof Error ? ` Last error: ${lastError.message}` : "";
+		throw new Error(`createMcpResourceReader: no configured MCP server resolved resource ${JSON.stringify(uri)}.${suffix}`);
+	} };
+}
+/**
+* Raw resource bytes (MC-10): text resources as UTF-8, blob resources
+* DECODED from base64 — slicing/totalBytes operate on real payload
+* bytes, never on the ~33%-inflated base64 string (whose arbitrary
+* cuts also break base64 quads).
+*/
+function resourceBytes(content) {
+	if (content.text !== void 0) return Buffer.from(content.text, "utf8");
+	if (content.blob !== void 0) return Buffer.from(content.blob, "base64");
+	return Buffer.alloc(0);
+}
+/**
+* Apply a {@link ResultReadRange} to the fully-fetched resource body,
+* mirroring the spill-file reader's slicing semantics (line mode wins;
+* `maxBytes` caps the returned slice) so `read_result` pages uniformly.
+*/
+function sliceResource(content, range, defaultMaxBytes) {
+	const buf = resourceBytes(content);
+	const full = buf.toString("utf8");
+	const totalBytes = buf.byteLength;
+	const cap = Math.max(0, range?.maxBytes ?? defaultMaxBytes);
+	if (range?.startLine !== void 0 || range?.endLine !== void 0) {
+		const lines = full.split("\n");
+		const start = Math.max(1, range.startLine ?? 1);
+		const end$1 = Math.min(lines.length, range.endLine ?? lines.length);
+		const selected = start <= end$1 ? lines.slice(start - 1, end$1).join("\n") : "";
+		const capped = Buffer.byteLength(selected, "utf8") > cap;
+		const out = capBytes(selected, cap);
+		return Object.freeze({
+			producerTrustClass: "mcp-derived",
+			content: out,
+			bytes: Buffer.byteLength(out, "utf8"),
+			totalBytes,
+			eof: end$1 >= lines.length && !capped
+		});
+	}
+	const offset = clamp(range?.offset ?? 0, 0, totalBytes);
+	const requested = range?.length ?? totalBytes - offset;
+	const rawEnd = clamp(offset + Math.max(0, requested), offset, totalBytes);
+	const end = Math.min(rawEnd, offset + cap);
+	const slice = buf.subarray(offset, end);
+	return Object.freeze({
+		producerTrustClass: "mcp-derived",
+		content: slice.toString("utf8"),
+		bytes: slice.byteLength,
+		totalBytes,
+		eof: end >= totalBytes
+	});
+}
+function clamp(value, lo, hi) {
+	return Math.min(hi, Math.max(lo, value));
+}
+/** Truncate `s` to at most `maxBytes` UTF-8 bytes (tolerating a split trailing char). */
+function capBytes(s, maxBytes) {
+	if (Buffer.byteLength(s, "utf8") <= maxBytes) return s;
+	return Buffer.from(s, "utf8").subarray(0, maxBytes).toString("utf8");
+}
+
+//#endregion
+export { createMcpResourceReader };
+//# sourceMappingURL=mcp-resource-reader.js.map

package/dist/client/mcp-resource-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-resource-reader.js","names":["lastError: unknown","content: MCPResourceContent","end"],"sources":["../../src/client/mcp-resource-reader.ts"],"sourcesContent":["/**\n * {@link createMcpResourceReader} — resolve MCP `resource_link` handles\n * on demand (WI-13 / P2-2, ties to WI-10 result handles).\n *\n * The `toTools()` adapter surfaces an MCP `resource_link` as a preview +\n * the resource `uri` (the {@link import('@graphorin/tools/result').ResultReader}\n * handle) instead of inlining the body. This reader resolves that handle\n * via {@link MCPClient.readResource} when the model later calls the\n * built-in `read_result` tool — so a large MCP resource never inflates\n * context until the model actually asks for it.\n *\n * Compose it with the agent's spill-file reader (the agent tries each\n * configured reader in order): the spill reader claims\n * `graphorin-spill:` handles, this reader resolves the rest. With more\n * than one MCP client, the reader tries each until one server resolves\n * the URI.\n *\n * Network note (R4): this reader performs no I/O until `read(...)` is\n * called, and then only over a connection the operator already opened.\n *\n * @packageDocumentation\n */\n\nimport { incrementCounter } from '@graphorin/tools/audit';\nimport type { ResultReader, ResultReadOutcome, ResultReadRange } from '@graphorin/tools/result';\nimport type { MCPClient, MCPResourceContent } from './types.js';\n\n/** Configuration for {@link createMcpResourceReader}. */\nexport interface McpResourceReaderOptions {\n  /** Clients consulted (in order) to resolve a resource URI. */\n  readonly clients: ReadonlyArray<MCPClient>;\n  /** Default `maxBytes` when `read(...)` is called without one. Default `65536`. */\n  readonly defaultMaxBytes?: number;\n}\n\n/**\n * Build a {@link ResultReader} that resolves MCP resource URIs through\n * one or more connected {@link MCPClient}s.\n *\n * @stable\n */\nexport function createMcpResourceReader(opts: McpResourceReaderOptions): ResultReader {\n  const clients = [...opts.clients];\n  const defaultMaxBytes = opts.defaultMaxBytes ?? 65_536;\n  return {\n    async read(uri, range): Promise<ResultReadOutcome> {\n      if (clients.length === 0) {\n        throw new Error(\n          'createMcpResourceReader: no MCP clients configured to resolve resource handles.',\n        );\n      }\n      let lastError: unknown;\n      for (const client of clients) {\n        let content: MCPResourceContent;\n        try {\n          content = await client.readResource(uri);\n        } catch (err) {\n          lastError = err;\n          continue;\n        }\n        incrementCounter('mcp.resource-link.resolved.total', {\n          server: client.serverIdentity.id,\n        });\n        return sliceResource(content, range, defaultMaxBytes);\n      }\n      const suffix = lastError instanceof Error ? ` Last error: ${lastError.message}` : '';\n      throw new Error(\n        `createMcpResourceReader: no configured MCP server resolved resource ${JSON.stringify(uri)}.${suffix}`,\n      );\n    },\n  };\n}\n\n/**\n * Raw resource bytes (MC-10): text resources as UTF-8, blob resources\n * DECODED from base64 — slicing/totalBytes operate on real payload\n * bytes, never on the ~33%-inflated base64 string (whose arbitrary\n * cuts also break base64 quads).\n */\nfunction resourceBytes(content: MCPResourceContent): Buffer {\n  if (content.text !== undefined) return Buffer.from(content.text, 'utf8');\n  if (content.blob !== undefined) return Buffer.from(content.blob, 'base64');\n  return Buffer.alloc(0);\n}\n\n/**\n * Apply a {@link ResultReadRange} to the fully-fetched resource body,\n * mirroring the spill-file reader's slicing semantics (line mode wins;\n * `maxBytes` caps the returned slice) so `read_result` pages uniformly.\n */\nfunction sliceResource(\n  content: MCPResourceContent,\n  range: ResultReadRange | undefined,\n  defaultMaxBytes: number,\n): ResultReadOutcome {\n  const buf = resourceBytes(content);\n  const full = buf.toString('utf8');\n  const totalBytes = buf.byteLength;\n  const cap = Math.max(0, range?.maxBytes ?? defaultMaxBytes);\n\n  if (range?.startLine !== undefined || range?.endLine !== undefined) {\n    const lines = full.split('\\n');\n    const start = Math.max(1, range.startLine ?? 1);\n    const end = Math.min(lines.length, range.endLine ?? lines.length);\n    const selected = start <= end ? lines.slice(start - 1, end).join('\\n') : '';\n    const capped = Buffer.byteLength(selected, 'utf8') > cap;\n    const out = capBytes(selected, cap);\n    return Object.freeze({\n      // TL-6: MCP resource content is mcp-derived by definition — the\n      // executor re-applies inbound sanitization + dataflow provenance\n      // by this class when read_result relays it.\n      producerTrustClass: 'mcp-derived' as const,\n      content: out,\n      bytes: Buffer.byteLength(out, 'utf8'),\n      totalBytes,\n      eof: end >= lines.length && !capped,\n    });\n  }\n\n  const offset = clamp(range?.offset ?? 0, 0, totalBytes);\n  const requested = range?.length ?? totalBytes - offset;\n  const rawEnd = clamp(offset + Math.max(0, requested), offset, totalBytes);\n  const end = Math.min(rawEnd, offset + cap);\n  const slice = buf.subarray(offset, end);\n  return Object.freeze({\n    // TL-6: MCP resource content is mcp-derived by definition.\n    producerTrustClass: 'mcp-derived' as const,\n    content: slice.toString('utf8'),\n    bytes: slice.byteLength,\n    totalBytes,\n    eof: end >= totalBytes,\n  });\n}\n\nfunction clamp(value: number, lo: number, hi: number): number {\n  return Math.min(hi, Math.max(lo, value));\n}\n\n/** Truncate `s` to at most `maxBytes` UTF-8 bytes (tolerating a split trailing char). */\nfunction capBytes(s: string, maxBytes: number): string {\n  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;\n  return Buffer.from(s, 'utf8').subarray(0, maxBytes).toString('utf8');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,wBAAwB,MAA8C;CACpF,MAAM,UAAU,CAAC,GAAG,KAAK,QAAQ;CACjC,MAAM,kBAAkB,KAAK,mBAAmB;AAChD,QAAO,EACL,MAAM,KAAK,KAAK,OAAmC;AACjD,MAAI,QAAQ,WAAW,EACrB,OAAM,IAAI,MACR,kFACD;EAEH,IAAIA;AACJ,OAAK,MAAM,UAAU,SAAS;GAC5B,IAAIC;AACJ,OAAI;AACF,cAAU,MAAM,OAAO,aAAa,IAAI;YACjC,KAAK;AACZ,gBAAY;AACZ;;AAEF,oBAAiB,oCAAoC,EACnD,QAAQ,OAAO,eAAe,IAC/B,CAAC;AACF,UAAO,cAAc,SAAS,OAAO,gBAAgB;;EAEvD,MAAM,SAAS,qBAAqB,QAAQ,gBAAgB,UAAU,YAAY;AAClF,QAAM,IAAI,MACR,uEAAuE,KAAK,UAAU,IAAI,CAAC,GAAG,SAC/F;IAEJ;;;;;;;;AASH,SAAS,cAAc,SAAqC;AAC1D,KAAI,QAAQ,SAAS,OAAW,QAAO,OAAO,KAAK,QAAQ,MAAM,OAAO;AACxE,KAAI,QAAQ,SAAS,OAAW,QAAO,OAAO,KAAK,QAAQ,MAAM,SAAS;AAC1E,QAAO,OAAO,MAAM,EAAE;;;;;;;AAQxB,SAAS,cACP,SACA,OACA,iBACmB;CACnB,MAAM,MAAM,cAAc,QAAQ;CAClC,MAAM,OAAO,IAAI,SAAS,OAAO;CACjC,MAAM,aAAa,IAAI;CACvB,MAAM,MAAM,KAAK,IAAI,GAAG,OAAO,YAAY,gBAAgB;AAE3D,KAAI,OAAO,cAAc,UAAa,OAAO,YAAY,QAAW;EAClE,MAAM,QAAQ,KAAK,MAAM,KAAK;EAC9B,MAAM,QAAQ,KAAK,IAAI,GAAG,MAAM,aAAa,EAAE;EAC/C,MAAMC,QAAM,KAAK,IAAI,MAAM,QAAQ,MAAM,WAAW,MAAM,OAAO;EACjE,MAAM,WAAW,SAASA,QAAM,MAAM,MAAM,QAAQ,GAAGA,MAAI,CAAC,KAAK,KAAK,GAAG;EACzE,MAAM,SAAS,OAAO,WAAW,UAAU,OAAO,GAAG;EACrD,MAAM,MAAM,SAAS,UAAU,IAAI;AACnC,SAAO,OAAO,OAAO;GAInB,oBAAoB;GACpB,SAAS;GACT,OAAO,OAAO,WAAW,KAAK,OAAO;GACrC;GACA,KAAKA,SAAO,MAAM,UAAU,CAAC;GAC9B,CAAC;;CAGJ,MAAM,SAAS,MAAM,OAAO,UAAU,GAAG,GAAG,WAAW;CACvD,MAAM,YAAY,OAAO,UAAU,aAAa;CAChD,MAAM,SAAS,MAAM,SAAS,KAAK,IAAI,GAAG,UAAU,EAAE,QAAQ,WAAW;CACzE,MAAM,MAAM,KAAK,IAAI,QAAQ,SAAS,IAAI;CAC1C,MAAM,QAAQ,IAAI,SAAS,QAAQ,IAAI;AACvC,QAAO,OAAO,OAAO;EAEnB,oBAAoB;EACpB,SAAS,MAAM,SAAS,OAAO;EAC/B,OAAO,MAAM;EACb;EACA,KAAK,OAAO;EACb,CAAC;;AAGJ,SAAS,MAAM,OAAe,IAAY,IAAoB;AAC5D,QAAO,KAAK,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC;;;AAI1C,SAAS,SAAS,GAAW,UAA0B;AACrD,KAAI,OAAO,WAAW,GAAG,OAAO,IAAI,SAAU,QAAO;AACrD,QAAO,OAAO,KAAK,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,SAAS,OAAO"}

package/dist/client/pinning.js

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+
+//#region src/client/pinning.ts
+/**
+* Tool-definition pinning (MC-6): stable fingerprints over MCP tool
+* definitions so approve-then-swap rug-pulls — a server changing a
+* tool's description/schema behind an already-approved name — are
+* detectable across snapshots and process restarts.
+*
+* The fingerprint is a sha256 over a key-sorted canonical render of
+* `{ name, description, inputSchema, outputSchema, title }`. Operators
+* persist the stamped `__definitionHash` (or read it from the audit
+* trail) and pass it back via `toTools({ pinnedFingerprints })`.
+*
+* @packageDocumentation
+*/
+/** Deterministic JSON render: object keys sorted recursively. */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map((v) => stableStringify(v)).join(",")}]`;
+	if (typeof value === "object" && value !== null) return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+}
+/**
+* Stable sha256 fingerprint of one MCP tool definition (MC-6).
+*
+* @stable
+*/
+function computeToolDefinitionHash(def) {
+	const canonical = stableStringify({
+		name: def.name,
+		description: def.description,
+		inputSchema: def.inputSchema,
+		...def.outputSchema !== void 0 ? { outputSchema: def.outputSchema } : {},
+		...def.title !== void 0 ? { title: def.title } : {}
+	});
+	return createHash("sha256").update(canonical).digest("hex");
+}
+
+//#endregion
+export { computeToolDefinitionHash };
+//# sourceMappingURL=pinning.js.map

package/dist/client/pinning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinning.js","names":[],"sources":["../../src/client/pinning.ts"],"sourcesContent":["/**\n * Tool-definition pinning (MC-6): stable fingerprints over MCP tool\n * definitions so approve-then-swap rug-pulls — a server changing a\n * tool's description/schema behind an already-approved name — are\n * detectable across snapshots and process restarts.\n *\n * The fingerprint is a sha256 over a key-sorted canonical render of\n * `{ name, description, inputSchema, outputSchema, title }`. Operators\n * persist the stamped `__definitionHash` (or read it from the audit\n * trail) and pass it back via `toTools({ pinnedFingerprints })`.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'node:crypto';\n\nimport type { MCPToolDefinition } from './types.js';\n\n/** Deterministic JSON render: object keys sorted recursively. */\nfunction stableStringify(value: unknown): string {\n  if (Array.isArray(value)) {\n    return `[${value.map((v) => stableStringify(v)).join(',')}]`;\n  }\n  if (typeof value === 'object' && value !== null) {\n    const entries = Object.entries(value as Record<string, unknown>)\n      .filter(([, v]) => v !== undefined)\n      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);\n    return `{${entries.join(',')}}`;\n  }\n  return JSON.stringify(value) ?? 'null';\n}\n\n/**\n * Stable sha256 fingerprint of one MCP tool definition (MC-6).\n *\n * @stable\n */\nexport function computeToolDefinitionHash(def: MCPToolDefinition): string {\n  const canonical = stableStringify({\n    name: def.name,\n    description: def.description,\n    inputSchema: def.inputSchema,\n    ...(def.outputSchema !== undefined ? { outputSchema: def.outputSchema } : {}),\n    ...(def.title !== undefined ? { title: def.title } : {}),\n  });\n  return createHash('sha256').update(canonical).digest('hex');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAmBA,SAAS,gBAAgB,OAAwB;AAC/C,KAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,IAAI,MAAM,KAAK,MAAM,gBAAgB,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;AAE5D,KAAI,OAAO,UAAU,YAAY,UAAU,KAKzC,QAAO,IAJS,OAAO,QAAQ,MAAiC,CAC7D,QAAQ,GAAG,OAAO,MAAM,OAAU,CAClC,MAAM,CAAC,IAAI,CAAC,OAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,EAAG,CAChD,KAAK,CAAC,GAAG,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC,GAAG,gBAAgB,EAAE,GAAG,CAC7C,KAAK,IAAI,CAAC;AAE/B,QAAO,KAAK,UAAU,MAAM,IAAI;;;;;;;AAQlC,SAAgB,0BAA0B,KAAgC;CACxE,MAAM,YAAY,gBAAgB;EAChC,MAAM,IAAI;EACV,aAAa,IAAI;EACjB,aAAa,IAAI;EACjB,GAAI,IAAI,iBAAiB,SAAY,EAAE,cAAc,IAAI,cAAc,GAAG,EAAE;EAC5E,GAAI,IAAI,UAAU,SAAY,EAAE,OAAO,IAAI,OAAO,GAAG,EAAE;EACxD,CAAC;AACF,QAAO,WAAW,SAAS,CAAC,OAAO,UAAU,CAAC,OAAO,MAAM"}

package/dist/client/to-tools.d.ts

@@ -0,0 +1,41 @@
+import { ServerIdentity } from "../transport/types.js";
+import { MCPClient, MCPToToolsOptions, MCPToolDefinition } from "./types.js";
+import { adaptCallResult } from "./adapt-result.js";
+import { DEFAULT_DEFER_LOADING_THRESHOLD } from "./defer-loading.js";
+import { InboundSanitizationPolicy, Tool } from "@graphorin/core";
+
+//#region src/client/to-tools.d.ts
+
+/**
+ * Reset every process-scoped dedup set owned by the adapter modules.
+ * Used by tests.
+ *
+ * @experimental
+ */
+declare function _resetMcpAdapterDedupForTesting(): void;
+/** Result returned by {@link adaptMCPTools}. */
+interface AdaptedToolsResult {
+  readonly tools: ReadonlyArray<Tool>;
+  /** MC-6: sha256 definition fingerprint per MCP tool name. */
+  readonly fingerprints: ReadonlyMap<string, string>;
+  readonly autoDeferralFired: boolean;
+  readonly resolvedDeferLoading: boolean;
+  readonly resolvedInboundSanitization: InboundSanitizationPolicy;
+  readonly toolCount: number;
+  readonly deferralThreshold: number;
+}
+/**
+ * Build the {@link Tool} array for the supplied MCP tool catalogue.
+ *
+ * @stable
+ */
+declare function adaptMCPTools(args: {
+  readonly client: MCPClient;
+  readonly serverIdentity: ServerIdentity;
+  readonly catalogue: ReadonlyArray<MCPToolDefinition>;
+  readonly options?: MCPToToolsOptions;
+  readonly logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>) => void;
+}): AdaptedToolsResult;
+//#endregion
+export { _resetMcpAdapterDedupForTesting, adaptMCPTools };
+//# sourceMappingURL=to-tools.d.ts.map

package/dist/client/to-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-tools.d.ts","names":[],"sources":["../../src/client/to-tools.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;iBAmDgB,+BAAA,CAAA;;UAMC,kBAAA;kBACC,cAAc;;yBAEP;;;wCAGe;;;;;;;;;iBAUxB,aAAA;mBACG;2BACQ;sBACL,cAAc;qBACf;2FAIR;IAET"}

package/dist/client/to-tools.js

@@ -0,0 +1,125 @@
+import { buildJsonSchemaValidator } from "../registry/json-schema.js";
+import { adaptCallResult } from "./adapt-result.js";
+import { DEFAULT_DEFER_LOADING_THRESHOLD, _resetDeferLoadingDedupForTesting, resolveDeferLoading } from "./defer-loading.js";
+import { _resetInboundFiltersDedupForTesting, resolveInboundPolicy, sanitizeDescription, warnOnPassthroughOverride } from "./inbound-filters.js";
+import { computeToolDefinitionHash } from "./pinning.js";
+
+//#region src/client/to-tools.ts
+/**
+* Reset every process-scoped dedup set owned by the adapter modules.
+* Used by tests.
+*
+* @experimental
+*/
+function _resetMcpAdapterDedupForTesting() {
+	_resetDeferLoadingDedupForTesting();
+	_resetInboundFiltersDedupForTesting();
+}
+/**
+* Build the {@link Tool} array for the supplied MCP tool catalogue.
+*
+* @stable
+*/
+function adaptMCPTools(args) {
+	const opts = args.options ?? {};
+	const fingerprints = /* @__PURE__ */ new Map();
+	const filter = opts.filter;
+	const namespace = (opts.namespace ?? "").trim();
+	const filtered = filter === void 0 ? args.catalogue : args.catalogue.filter((t) => filter(t));
+	const total = filtered.length;
+	const threshold = opts.deferLoadingThreshold ?? DEFAULT_DEFER_LOADING_THRESHOLD;
+	const { autoDeferralFired, resolvedDeferLoading } = resolveDeferLoading({
+		serverIdentity: args.serverIdentity,
+		toolNames: filtered.map((t) => t.name),
+		explicitDefer: opts.defer_loading,
+		threshold,
+		...args.logger === void 0 ? {} : { logger: args.logger }
+	});
+	const resolvedInbound = resolveInboundPolicy(opts.inboundSanitization);
+	warnOnPassthroughOverride({
+		resolvedInbound,
+		serverIdentity: args.serverIdentity,
+		...args.logger === void 0 ? {} : { logger: args.logger }
+	});
+	const tools = [];
+	for (const definition of filtered) {
+		const namespacedName = namespace.length === 0 ? definition.name : `${namespace}.${definition.name}`;
+		const sideEffectClass = opts.sideEffectClassByTool?.[namespacedName] ?? "external-stateful";
+		const preferredModel = opts.preferredModelByTool?.[namespacedName];
+		const inputValidator = buildJsonSchemaValidator(definition.inputSchema);
+		const outputValidator = definition.outputSchema === void 0 ? void 0 : buildJsonSchemaValidator(definition.outputSchema);
+		const definitionHash = computeToolDefinitionHash(definition);
+		fingerprints.set(definition.name, definitionHash);
+		tools.push(buildAdaptedTool({
+			client: args.client,
+			serverIdentity: args.serverIdentity,
+			definitionHash,
+			...args.logger !== void 0 ? { logger: args.logger } : {},
+			mcpToolName: definition.name,
+			graphorinToolName: namespacedName,
+			description: definition.description.length === 0 ? `${definition.name} (MCP)` : definition.description,
+			inputSchema: inputValidator,
+			outputSchema: outputValidator,
+			defer_loading: resolvedDeferLoading,
+			inboundSanitization: resolvedInbound,
+			sideEffectClass,
+			...opts.maxResultTokens === void 0 ? {} : { maxResultTokens: opts.maxResultTokens },
+			...opts.truncationStrategy === void 0 ? {} : { truncationStrategy: opts.truncationStrategy },
+			...opts.callTimeoutMs === void 0 ? {} : { callTimeoutMs: opts.callTimeoutMs },
+			...preferredModel === void 0 ? {} : { preferredModel }
+		}));
+	}
+	return Object.freeze({
+		tools: Object.freeze(tools),
+		fingerprints,
+		autoDeferralFired,
+		resolvedDeferLoading,
+		resolvedInboundSanitization: resolvedInbound,
+		toolCount: total,
+		deferralThreshold: threshold
+	});
+}
+function buildAdaptedTool(args) {
+	const sanitizedDescription = sanitizeDescription({
+		description: args.description,
+		inboundSanitization: args.inboundSanitization,
+		toolName: args.graphorinToolName,
+		serverIdentity: args.serverIdentity
+	});
+	const tool = {
+		name: args.graphorinToolName,
+		description: sanitizedDescription,
+		inputSchema: args.inputSchema,
+		...args.outputSchema === void 0 ? {} : { outputSchema: args.outputSchema },
+		defer_loading: args.defer_loading,
+		inboundSanitization: args.inboundSanitization,
+		sideEffectClass: args.sideEffectClass,
+		sandboxPolicy: "sandboxed",
+		...args.maxResultTokens === void 0 ? {} : { maxResultTokens: args.maxResultTokens },
+		...args.truncationStrategy === void 0 ? {} : { truncationStrategy: args.truncationStrategy },
+		...args.preferredModel === void 0 ? {} : { preferredModel: args.preferredModel },
+		async execute(input, ctx) {
+			return adaptCallResult({
+				result: await args.client.callTool(args.mcpToolName, input, {
+					...ctx?.signal !== void 0 ? { signal: ctx.signal } : {},
+					...args.callTimeoutMs !== void 0 ? { timeoutMs: args.callTimeoutMs } : {}
+				}),
+				outputSchema: args.outputSchema,
+				serverIdentity: args.serverIdentity,
+				toolName: args.graphorinToolName,
+				...args.logger !== void 0 ? { logger: args.logger } : {}
+			});
+		}
+	};
+	return Object.assign(tool, {
+		__source: {
+			kind: "mcp",
+			serverIdentity: args.serverIdentity.id
+		},
+		__definitionHash: args.definitionHash
+	});
+}
+
+//#endregion
+export { _resetMcpAdapterDedupForTesting, adaptMCPTools };
+//# sourceMappingURL=to-tools.js.map

package/dist/client/to-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-tools.js","names":["tools: Tool[]"],"sources":["../../src/client/to-tools.ts"],"sourcesContent":["/**\n * `toTools()` adapter — bridges MCP tool descriptors into the\n * Graphorin tool registry.\n *\n * The adapter orchestrates three extracted concerns (F-MCP-001):\n *\n * 1. Filters / namespaces the `listTools()` output, then resolves the\n *    per-server effective `defer_loading` flag — see\n *    {@link import('./defer-loading.js').resolveDeferLoading}.\n * 2. Resolves the per-server inbound prompt-injection policy and strips\n *    imperative payloads from each description — see\n *    {@link import('./inbound-filters.js')}.\n * 3. Converts each MCP tool into a strongly-typed Graphorin `Tool` whose\n *    `execute(...)` calls back into {@link MCPClient.callTool} and adapts\n *    the result — see {@link import('./adapt-result.js').adaptCallResult}.\n *\n * The trust class is pinned to `'mcp-derived'` so the agent runtime's\n * per-step preamble fires regardless of the body-level policy.\n *\n * @packageDocumentation\n */\n\nimport type { ContentChunk, InboundSanitizationPolicy, Tool, ToolReturn } from '@graphorin/core';\nimport { buildJsonSchemaValidator, type JsonSchemaLike } from '../registry/json-schema.js';\nimport type { ServerIdentity } from '../transport/types.js';\nimport { adaptCallResult } from './adapt-result.js';\nimport {\n  _resetDeferLoadingDedupForTesting,\n  DEFAULT_DEFER_LOADING_THRESHOLD,\n  resolveDeferLoading,\n} from './defer-loading.js';\nimport {\n  _resetInboundFiltersDedupForTesting,\n  resolveInboundPolicy,\n  sanitizeDescription,\n  warnOnPassthroughOverride,\n} from './inbound-filters.js';\nimport { computeToolDefinitionHash } from './pinning.js';\nimport type { MCPClient, MCPToolDefinition, MCPToToolsOptions } from './types.js';\n\n// Re-exported for backward compatibility: callers (and tests) import\n// these symbols directly from `./to-tools.js` and via the client barrel.\nexport { adaptCallResult } from './adapt-result.js';\nexport { DEFAULT_DEFER_LOADING_THRESHOLD } from './defer-loading.js';\n\n/**\n * Reset every process-scoped dedup set owned by the adapter modules.\n * Used by tests.\n *\n * @experimental\n */\nexport function _resetMcpAdapterDedupForTesting(): void {\n  _resetDeferLoadingDedupForTesting();\n  _resetInboundFiltersDedupForTesting();\n}\n\n/** Result returned by {@link adaptMCPTools}. */\nexport interface AdaptedToolsResult {\n  readonly tools: ReadonlyArray<Tool>;\n  /** MC-6: sha256 definition fingerprint per MCP tool name. */\n  readonly fingerprints: ReadonlyMap<string, string>;\n  readonly autoDeferralFired: boolean;\n  readonly resolvedDeferLoading: boolean;\n  readonly resolvedInboundSanitization: InboundSanitizationPolicy;\n  readonly toolCount: number;\n  readonly deferralThreshold: number;\n}\n\n/**\n * Build the {@link Tool} array for the supplied MCP tool catalogue.\n *\n * @stable\n */\nexport function adaptMCPTools(args: {\n  readonly client: MCPClient;\n  readonly serverIdentity: ServerIdentity;\n  readonly catalogue: ReadonlyArray<MCPToolDefinition>;\n  readonly options?: MCPToToolsOptions;\n  readonly logger?: (\n    level: 'debug' | 'info' | 'warn' | 'error',\n    message: string,\n    fields?: Record<string, unknown>,\n  ) => void;\n}): AdaptedToolsResult {\n  const opts = args.options ?? {};\n  const fingerprints = new Map<string, string>();\n  const filter = opts.filter;\n  const namespace = (opts.namespace ?? '').trim();\n  const filtered = filter === undefined ? args.catalogue : args.catalogue.filter((t) => filter(t));\n  const total = filtered.length;\n  const threshold = opts.deferLoadingThreshold ?? DEFAULT_DEFER_LOADING_THRESHOLD;\n\n  const { autoDeferralFired, resolvedDeferLoading } = resolveDeferLoading({\n    serverIdentity: args.serverIdentity,\n    toolNames: filtered.map((t) => t.name),\n    explicitDefer: opts.defer_loading,\n    threshold,\n    ...(args.logger === undefined ? {} : { logger: args.logger }),\n  });\n\n  const resolvedInbound = resolveInboundPolicy(opts.inboundSanitization);\n  warnOnPassthroughOverride({\n    resolvedInbound,\n    serverIdentity: args.serverIdentity,\n    ...(args.logger === undefined ? {} : { logger: args.logger }),\n  });\n\n  const tools: Tool[] = [];\n  for (const definition of filtered) {\n    const namespacedName =\n      namespace.length === 0 ? definition.name : `${namespace}.${definition.name}`;\n    const sideEffectClass = opts.sideEffectClassByTool?.[namespacedName] ?? 'external-stateful';\n    const preferredModel = opts.preferredModelByTool?.[namespacedName];\n    const inputValidator = buildJsonSchemaValidator(definition.inputSchema as JsonSchemaLike);\n    const outputValidator =\n      definition.outputSchema === undefined\n        ? undefined\n        : buildJsonSchemaValidator(definition.outputSchema as JsonSchemaLike);\n    const definitionHash = computeToolDefinitionHash(definition);\n    fingerprints.set(definition.name, definitionHash);\n    tools.push(\n      buildAdaptedTool({\n        client: args.client,\n        serverIdentity: args.serverIdentity,\n        definitionHash,\n        ...(args.logger !== undefined ? { logger: args.logger } : {}),\n        mcpToolName: definition.name,\n        graphorinToolName: namespacedName,\n        description:\n          definition.description.length === 0 ? `${definition.name} (MCP)` : definition.description,\n        inputSchema: inputValidator,\n        outputSchema: outputValidator,\n        defer_loading: resolvedDeferLoading,\n        inboundSanitization: resolvedInbound,\n        sideEffectClass,\n        ...(opts.maxResultTokens === undefined ? {} : { maxResultTokens: opts.maxResultTokens }),\n        ...(opts.truncationStrategy === undefined\n          ? {}\n          : { truncationStrategy: opts.truncationStrategy }),\n        ...(opts.callTimeoutMs === undefined ? {} : { callTimeoutMs: opts.callTimeoutMs }),\n        ...(preferredModel === undefined ? {} : { preferredModel }),\n      }),\n    );\n  }\n\n  return Object.freeze({\n    tools: Object.freeze(tools),\n    fingerprints,\n    autoDeferralFired,\n    resolvedDeferLoading,\n    resolvedInboundSanitization: resolvedInbound,\n    toolCount: total,\n    deferralThreshold: threshold,\n  });\n}\n\ninterface BuildAdaptedToolArgs {\n  readonly client: MCPClient;\n  readonly serverIdentity: ServerIdentity;\n  readonly mcpToolName: string;\n  readonly graphorinToolName: string;\n  readonly description: string;\n  readonly inputSchema: import('@graphorin/core').ZodLikeSchema<unknown>;\n  readonly outputSchema?: import('@graphorin/core').ZodLikeSchema<unknown> | undefined;\n  readonly defer_loading: boolean;\n  readonly inboundSanitization: InboundSanitizationPolicy;\n  readonly sideEffectClass: import('@graphorin/core').SideEffectClass;\n  readonly maxResultTokens?: number;\n  readonly truncationStrategy?: import('@graphorin/core').TruncationStrategy;\n  /** Per-call timeout forwarded to `client.callTool` (MC-3/MC-5). */\n  readonly callTimeoutMs?: number;\n  /** MC-6: sha256 fingerprint of the producing MCP definition. */\n  readonly definitionHash: string;\n  readonly logger?: (\n    level: 'debug' | 'info' | 'warn' | 'error',\n    message: string,\n    fields?: Record<string, unknown>,\n  ) => void;\n  readonly preferredModel?:\n    | import('@graphorin/core').ModelHint\n    | import('@graphorin/core').ModelSpec;\n}\n\nfunction buildAdaptedTool(args: BuildAdaptedToolArgs): Tool<unknown, unknown, unknown> {\n  const sanitizedDescription = sanitizeDescription({\n    description: args.description,\n    inboundSanitization: args.inboundSanitization,\n    toolName: args.graphorinToolName,\n    serverIdentity: args.serverIdentity,\n  });\n\n  const tool = {\n    name: args.graphorinToolName,\n    description: sanitizedDescription,\n    inputSchema: args.inputSchema,\n    ...(args.outputSchema === undefined ? {} : { outputSchema: args.outputSchema }),\n    defer_loading: args.defer_loading,\n    inboundSanitization: args.inboundSanitization,\n    sideEffectClass: args.sideEffectClass,\n    sandboxPolicy: 'sandboxed' as const,\n    ...(args.maxResultTokens === undefined ? {} : { maxResultTokens: args.maxResultTokens }),\n    ...(args.truncationStrategy === undefined\n      ? {}\n      : { truncationStrategy: args.truncationStrategy }),\n    ...(args.preferredModel === undefined ? {} : { preferredModel: args.preferredModel }),\n    async execute(\n      input: unknown,\n      ctx?: import('@graphorin/core').ToolExecutionContext<unknown>,\n    ): Promise<ToolReturn<unknown>> {\n      // MC-5: the agent's per-call AbortSignal reaches the wire — an\n      // aborted run sends `notifications/cancelled` instead of orphaning\n      // the JSON-RPC request on the server. MC-3: the per-server call\n      // timeout rides along.\n      const result = await args.client.callTool(args.mcpToolName, input, {\n        ...(ctx?.signal !== undefined ? { signal: ctx.signal } : {}),\n        ...(args.callTimeoutMs !== undefined ? { timeoutMs: args.callTimeoutMs } : {}),\n      });\n      return adaptCallResult({\n        result,\n        outputSchema: args.outputSchema,\n        serverIdentity: args.serverIdentity,\n        toolName: args.graphorinToolName,\n        ...(args.logger !== undefined ? { logger: args.logger } : {}),\n      });\n    },\n  } satisfies Tool<unknown, unknown, unknown>;\n  // MC-7: pre-stamp the provenance so the agent's inferToolSource —\n  // which honours an existing stamp — classifies tools passed via\n  // `config.tools` as 'mcp-derived' (untrusted for the WI-12 dataflow\n  // policy) instead of first-party. Zero operator boilerplate.\n  return Object.assign(tool, {\n    __source: { kind: 'mcp', serverIdentity: args.serverIdentity.id } as const,\n    // MC-6: operators persist this fingerprint to pin the approved\n    // definition (`toTools({ pinnedFingerprints })`).\n    __definitionHash: args.definitionHash,\n  });\n}\n\n/** Unused export kept for ergonomic test access. */\nexport type AdaptedToolChunkBuffer = ReadonlyArray<ContentChunk>;\n"],"mappings":"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"}