@graphorin/mcp 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @graphorin/mcp
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release. The `@graphorin/mcp` package ships the typed
+  Model Context Protocol client used by Graphorin agents, the
+  standalone server, and the CLI. The release surface includes the
+  three transports (`stdio`, `streamable-http`, `sse`), the typed
+  `MCPClient` (`listTools` / `listResources` / `listPrompts` /
+  `callTool` / `readResource` / `getPrompt` / `close`), the
+  strategy-aware `toTools()` adapter (per-server inbound
+  prompt-injection sanitization, deferred-loading auto-default at
+  the 10-tool threshold, structured-content + outputSchema
+  round-trip with backward-compatible `TextContent` mirror,
+  per-server result envelope overrides, collision-strategy +
+  per-server priority, per-server preferredModel + side-effect
+  class overrides), the pluggable `EventStore` contract for
+  resumable Streamable HTTP sessions (`Mcp-Session-Id` +
+  `Last-Event-ID` handshake), the OAuth bridge backed by
+  `@graphorin/security/oauth`, the typed error hierarchy, and the
+  helper functions consumed by `graphorin auth` (CLI). See the
+  package `README.md` for the full surface inventory and the
+  workspace `CHANGELOG.md` for the rollup release notes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,296 @@
+# @graphorin/mcp
+
+> Model Context Protocol client for the Graphorin framework.
+
+`@graphorin/mcp` ships the typed MCP client used by Graphorin
+agents, the standalone server, and the CLI. The package wraps the
+official `@modelcontextprotocol/sdk@^1.29.0` client primitives and
+adds the Graphorin-specific glue: the `toTools()` adapter that
+bridges MCP tool descriptors into the typed Graphorin tool
+registry, the inbound prompt-injection sanitization defaults for
+MCP-derived tools, the structured-content + outputSchema
+round-trip with backward-compatible TextContent mirror, the
+deferred-loading auto-default at the 10-tool threshold, the
+collision-strategy + per-server priority handoff to the tool
+registry, honest Streamable HTTP session semantics, and the OAuth
+bridge that resolves bearer headers from
+the existing outbound OAuth subsystem in `@graphorin/security`.
+
+## Highlights
+
+- **Three transports out of the box.** `'stdio'` is the primary
+  transport for local MCP servers started as a child process;
+  `'streamable-http'` is the current default for remote servers
+  with optional Streamable HTTP session support; `'sse'` is the
+  deprecated legacy transport, kept for back-compat with servers
+  that have not migrated yet (the runtime emits one WARN per
+  process on selection).
+- **Typed `MCPClient` surface.** `listTools` / `listResources` /
+  `listPrompts` / `callTool` / `readResource` / `getPrompt` /
+  `close` plus the strategy-aware `toTools(...)` adapter.
+- **Strict default for MCP-derived tools.** Every `Tool` produced
+  by `MCPClient.toTools()` defaults to the
+  `'detect-and-strip-and-wrap'` inbound prompt-injection
+  sanitization policy (mirrored on tool-result bodies at execution
+  time) and the `'sandboxed'` sandbox policy. The trust class is
+  pinned to `'mcp-derived'` so the agent runtime's per-step
+  preamble fires regardless of body-level overrides.
+- **Auto-deferral at the 10-tool threshold.** When the MCP
+  server's `listTools()` returns more than `deferLoadingThreshold`
+  entries (default `10`), the per-server default flips
+  `defer_loading: true` for every produced tool; an INFO-log
+  records the threshold and the tool names; the
+  `tool.retrieval.deferred.total` counter is incremented per
+  affected tool.
+- **Structured-content round-trip.** When the MCP server
+  advertises an `outputSchema` on a tool definition (per the
+  current MCP spec) and returns `structuredContent` on `callTool`,
+  the adapter validates the structured form against the converted
+  Zod-compatible schema and surfaces it as the typed `Tool.execute`
+  output. The unstructured `content[]` is preserved in
+  `ToolReturn.contentParts` (including the backward-compatible
+  `TextContent` mirror); pre-spec servers that emit only `content[]`
+  fall through to the legacy concatenated-text behaviour.
+- **Collision resolution at the registry boundary.** The client
+  exposes `serverIdentity`, `collisionStrategy` (default
+  `'auto-prefix'`), and the optional per-client `priority` field;
+  the registry consumes the trio when its strategy-aware
+  `assertNoDuplicates(strategy, ctx)` overload runs.
+- **OAuth integration.** `createOAuthAuthorizationProvider({...})`
+  wraps the existing `refreshOAuthSession(...)` helper from
+  `@graphorin/security/oauth`, resolves the bearer header on every
+  request, debounces concurrent refreshes via the OAuth
+  subsystem's in-flight de-duplication, and emits the
+  `mcp.auth.expired` lifecycle event when a refresh fails.
+- **Streamable HTTP sessions.** The client persists the assigned
+  `Mcp-Session-Id` and the SDK transport auto-reconnects with
+  `Last-Event-ID` after a transient disconnect. Event replay is the
+  SERVER's responsibility per the Streamable HTTP spec — the client
+  surfaces `sessionIdPresent` (stateful routing detected; not a
+  replay guarantee).
+
+## Stable sub-paths
+
+```ts
+import { createMCPClient } from '@graphorin/mcp/client';
+import { createOAuthAuthorizationProvider } from '@graphorin/mcp/oauth';
+import {
+  formatMCPServerName,
+  validateMCPServerConfig,
+} from '@graphorin/mcp/helpers';
+import { MCPConnectionError, MCPProtocolError } from '@graphorin/mcp/errors';
+import type {
+  MCPTransportConfig,
+  ServerIdentity,
+} from '@graphorin/mcp/transport';
+```
+
+## Quick start
+
+```ts
+import { createMCPClient } from '@graphorin/mcp';
+
+// Local MCP server over stdio.
+const fileSystem = await createMCPClient({
+  transport: {
+    kind: 'stdio',
+    command: 'pnpm',
+    args: ['dlx', '@modelcontextprotocol/server-filesystem', '/Users/me/Documents'],
+  },
+});
+
+// Remote MCP server over Streamable HTTP.
+const issues = await createMCPClient({
+  transport: {
+    kind: 'streamable-http',
+    url: 'https://issues.example.com/mcp',
+    headers: { Authorization: 'Bearer ${TOKEN}' },
+  },
+});
+
+const tools = [
+  ...(await fileSystem.toTools({ namespace: 'fs' })),
+  ...(await issues.toTools({ namespace: 'issues' })),
+];
+
+// `tools` is ready to register with `@graphorin/tools`'s
+// `createToolRegistry({...})`; the agent runtime consumes the
+// resulting registry as part of its per-step planner.
+
+await fileSystem.close();
+await issues.close();
+```
+
+## Inbound sanitization policy reference
+
+The per-server `inboundSanitization` field controls how
+imperative-pattern matches in tool result bodies (and tool
+descriptions, at registration time) are handled:
+
+| Policy                          | Description                                                                 |
+|---------------------------------|-----------------------------------------------------------------------------|
+| `'pass-through'`                | No scan; bytes-equal forwarding (use only for trusted in-house servers).    |
+| `'detect-and-flag'`             | Scan; emit a flag span attribute + audit row but do not modify the body.    |
+| `'detect-and-strip'`            | Replace each match with the `[REDACTED:imperative-pattern]` literal token.  |
+| `'detect-and-wrap'`             | Wrap the body in `<<<untrusted_content>>>` without stripping matches.       |
+| `'detect-and-strip-and-wrap'`   | **Default for MCP-derived tools.** Both strip matches and wrap the body.    |
+
+Tool descriptions are always sanitized at registration time using
+the `'detect-and-strip'` variant of the configured policy (the
+wrap envelope is reserved for tool-result bodies inside the
+conversation history; the description goes into the per-step tool
+catalogue verbatim aside from the strip pass).
+
+## OAuth integration
+
+The package re-exports the OAuth library functions as the
+operator-facing CLI helpers `mcpAuthLogin`, `mcpAuthListSessions`,
+`mcpAuthRefresh`, `mcpAuthRevoke`, and `mcpAuthStatus`. They wrap
+the lower-level `loginInteractive`, `listOAuthSessions`,
+`refreshOAuthSession`, `revokeOAuthSession`, and `getOAuthStatus`
+helpers in `@graphorin/security/oauth`. The corresponding CLI
+binaries land in Phase 15.
+
+```ts
+import {
+  createInMemoryOAuthServerStore,
+  loginInteractive,
+} from '@graphorin/security/oauth';
+import {
+  createOAuthAuthorizationProvider,
+  createMCPClient,
+} from '@graphorin/mcp';
+
+const storage = createInMemoryOAuthServerStore();
+await loginInteractive({
+  serverId: 'issues-mcp',
+  serverUrl: 'https://issues.example.com/mcp',
+  storage,
+});
+
+const authProvider = createOAuthAuthorizationProvider({
+  serverId: 'issues-mcp',
+  storage,
+});
+
+const issues = await createMCPClient({
+  transport: {
+    kind: 'streamable-http',
+    url: 'https://issues.example.com/mcp',
+  },
+  // The client installs a per-request fetch-wrapper that calls
+  // `authProvider.resolveHeader()` on every outgoing request, so the
+  // refresh-ahead window fires automatically and a long-lived session
+  // survives token expiry without re-creating the client. Do **not**
+  // resolve the token once into static `headers` — that pins a single
+  // token and defeats the refresh.
+  authProvider,
+});
+```
+
+For a rare pre-shared token, pass `bearerToken` instead (mutually
+exclusive with `authProvider`; supplying both throws
+`MCPInvalidConfigError`):
+
+```ts
+const issues = await createMCPClient({
+  transport: { kind: 'streamable-http', url: 'https://issues.example.com/mcp' },
+  bearerToken: process.env.ISSUES_MCP_TOKEN!,
+});
+```
+
+## Streamable HTTP sessions
+
+When the MCP server assigns an `Mcp-Session-Id` on `initialize`, the
+client persists it for stateful routing and exposes
+`client.sessionIdPresent` (`client.resumable` is its deprecated
+alias). A session id is **not** a replay guarantee: per the
+Streamable HTTP spec, event replay is the **server's**
+responsibility, and the SDK transport already auto-reconnects with
+the `Last-Event-ID` header after a transient disconnect — no client
+configuration needed. (The former client-side `eventStore` option
+was removed: a client-held store cannot drive replay; passing the
+legacy option logs a warning.)
+
+### Reverse-proxy operational note
+
+When a Graphorin client connects to a Streamable HTTP MCP server
+through a reverse proxy (nginx, HAProxy, AWS ALB, Cloudflare, GCP
+Load Balancer), the proxy MUST be configured to disable response
+buffering on the SSE-style streaming response. Without the
+directive the symptoms are:
+
+- The client never receives `tool.execute.progress` /
+  `tool.execute.partial` events until the tool completes (defeats
+  the streaming purpose).
+- The connection appears to hang from the client side until the
+  proxy buffer is full.
+- Intermediate keep-alive timeouts fire because the proxy thinks
+  the connection is idle.
+
+#### Canonical nginx snippet
+
+```nginx
+location /mcp {
+  proxy_buffering off;
+  proxy_cache off;
+  chunked_transfer_encoding on;
+  proxy_read_timeout 600s;
+}
+```
+
+#### Analogous notes for other reverse proxies
+
+- **AWS ALB.** Enable stickiness, raise the idle-timeout to at
+  least 600 s, and confirm WebSocket-style upgrade compatibility
+  is enabled.
+- **Cloudflare.** Disable "Always Online" caching for the MCP
+  route and raise the proxy timeout via Cloudflare Tunnel.
+- **GCP Load Balancer.** Configure the backend service with
+  `connectionDraining.drainingTimeoutSec >= 600` and
+  `timeoutSec >= 600`.
+
+## Errors
+
+Every error class extends `GraphorinMCPError` and carries a
+stable lowercase `kind` discriminator and an actionable `hint`
+field where applicable:
+
+- `MCPConnectionError`               — transport could not be established or was dropped.
+- `MCPProtocolError`                 — JSON-RPC / MCP protocol-level error.
+- `MCPAuthError`                     — authentication / authorization failure.
+- `MCPToolNotFoundError`             — the requested tool is not registered with the server.
+- `MCPCallTimeoutError`              — tool call exceeded the configured timeout (variant `'session-lost'` for the resume-handshake-lost path).
+- `MCPCancelledError`                — call was cancelled by an `AbortSignal`.
+- `MCPInvalidConfigError`            — the supplied `MCPTransportConfig` is invalid.
+- `MCPTransportNotSupportedError`    — the supplied configuration requested an unsupported transport / capability combination (variant `'transport-resumable-not-supported'` for resumable sessions on `'stdio'` / `'sse'`).
+
+## Acceptance & testing
+
+- 109 unit + integration + property tests run under Vitest with
+  no network calls (verified by the workspace
+  `pnpm run check-no-network` script).
+- Integration tests use the SDK's `InMemoryTransport` linked-pair
+  + a configurable in-process `Server` fixture; no child
+  processes are spawned and no network round-trips happen during
+  the test run.
+- Coverage thresholds: 80 % statements, 80 % lines, 80 %
+  functions, 70 % branches.
+
+## Dependencies
+
+| Dependency                       | Pin              | Purpose                                       |
+|----------------------------------|------------------|-----------------------------------------------|
+| `@modelcontextprotocol/sdk`      | `^1.29.0`        | Underlying MCP client + transport primitives. |
+| `@graphorin/core`                | workspace        | `Tool` / `MessageContent` / `ZodLikeSchema`.  |
+| `@graphorin/security`            | workspace        | OAuth client + lifecycle event surface.       |
+| `@graphorin/observability`       | workspace        | Imperative-pattern catalogue.                 |
+| `@graphorin/tools`               | workspace        | Inbound sanitization helper + counter registry. |
+
+## License
+
+MIT — © 2026 Oleksiy Stepurenko.
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/client/adapt-result.d.ts

@@ -0,0 +1,25 @@
+import { ServerIdentity } from "../transport/types.js";
+import { MCPCallToolResult } from "./types.js";
+import { ToolReturn, ZodLikeSchema } from "@graphorin/core";
+
+//#region src/client/adapt-result.d.ts
+
+/** Arguments for {@link adaptCallResult}. */
+interface AdaptCallResultArgs {
+  readonly result: MCPCallToolResult;
+  readonly outputSchema?: ZodLikeSchema<unknown> | undefined;
+  readonly serverIdentity: ServerIdentity;
+  readonly toolName: string;
+  readonly logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>) => void;
+}
+/**
+ * Convert an MCP `CallToolResult` into a typed Graphorin `ToolReturn`,
+ * handling the structured-content + outputSchema round-trip and the
+ * backward-compatible TextContent mirror.
+ *
+ * @internal
+ */
+declare function adaptCallResult(args: AdaptCallResultArgs): ToolReturn<unknown>;
+//#endregion
+export { adaptCallResult };
+//# sourceMappingURL=adapt-result.d.ts.map

package/dist/client/adapt-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapt-result.d.ts","names":[],"sources":["../../src/client/adapt-result.ts"],"sourcesContent":[],"mappings":";;;;;;;UAmBiB,mBAAA;mBACE;0BACO;2BACC;;2FAKd;;;;;;;;;iBAWG,eAAA,OAAsB,sBAAsB"}

package/dist/client/adapt-result.js

@@ -0,0 +1,174 @@
+import { MCPToolExecutionError } from "../errors/index.js";
+import { incrementCounter } from "@graphorin/tools/audit";
+
+//#region src/client/adapt-result.ts
+/**
+* Convert an MCP `CallToolResult` into a typed Graphorin `ToolReturn`,
+* handling the structured-content + outputSchema round-trip and the
+* backward-compatible TextContent mirror.
+*
+* @internal
+*/
+function adaptCallResult(args) {
+	const { result, outputSchema, serverIdentity, toolName } = args;
+	if (result.isError === true) {
+		const errorText = (result.content ?? []).filter((p) => p.type === "text").map((p) => p.text).join("\n");
+		incrementCounter("mcp.call.tool-error.total", {
+			server: serverIdentity.id,
+			tool: toolName
+		});
+		throw new MCPToolExecutionError(errorText.length > 0 ? errorText : `MCP tool '${toolName}' reported an error result.`, { metadata: { tool: toolName } });
+	}
+	const contentParts = [];
+	const resourceLinkPreviews = [];
+	for (const part of result.content) {
+		if (part.type === "resource_link") {
+			incrementCounter("mcp.resource-link.emitted.total", {
+				server: serverIdentity.id,
+				tool: toolName
+			});
+			resourceLinkPreviews.push(formatResourceLinkPreview(part));
+		}
+		const messagePart = mcpContentToMessageContent(part);
+		if (messagePart !== void 0) contentParts.push(messagePart);
+	}
+	const textParts = (result.content ?? []).filter((p) => p.type === "text");
+	const outputSegments = [];
+	for (const part of result.content ?? []) switch (part.type) {
+		case "text":
+			outputSegments.push(part.text);
+			break;
+		case "image":
+		case "audio":
+			outputSegments.push(describeBinaryPart(part.type, part.mimeType, part.data));
+			break;
+		case "resource":
+			if (part.resource.text !== void 0) outputSegments.push(part.resource.text);
+			else if (part.resource.blob !== void 0) outputSegments.push(`[resource ${part.resource.uri} ${part.resource.mimeType ?? "application/octet-stream"}, ~${approxDecodedSize(part.resource.blob)} — full payload in contentParts]`);
+			else outputSegments.push(`Resource ${part.resource.uri}`);
+			break;
+		case "resource_link": break;
+	}
+	const concatenatedText = [...outputSegments, ...resourceLinkPreviews].join("\n");
+	if (result.structuredContent !== void 0) if (outputSchema !== void 0) {
+		const validation = outputSchema.safeParse(result.structuredContent);
+		if (validation.success) {
+			incrementCounter("mcp.structured-content.emitted.total", {
+				server: serverIdentity.id,
+				tool: toolName
+			});
+			const finalParts = [...contentParts];
+			if (textParts.length === 0) finalParts.push({
+				type: "text",
+				text: JSON.stringify(result.structuredContent)
+			});
+			return Object.freeze({
+				output: validation.data,
+				contentParts: Object.freeze(finalParts)
+			});
+		}
+		incrementCounter("mcp.structured-content.validation.failure.total", {
+			server: serverIdentity.id,
+			tool: toolName
+		});
+		args.logger?.("warn", "mcp.structured-content.validation.failed: payload mirrored as JSON text", {
+			server: serverIdentity.id,
+			tool: toolName
+		});
+		const fallbackParts = [...contentParts];
+		if (textParts.length === 0) fallbackParts.push({
+			type: "text",
+			text: JSON.stringify(result.structuredContent)
+		});
+		return Object.freeze({
+			output: concatenatedText.length > 0 ? concatenatedText : JSON.stringify(result.structuredContent),
+			contentParts: Object.freeze(fallbackParts)
+		});
+	} else {
+		incrementCounter("mcp.structured-content.emitted.total", {
+			server: serverIdentity.id,
+			tool: toolName
+		});
+		const finalParts = [...contentParts];
+		if (textParts.length === 0) finalParts.push({
+			type: "text",
+			text: JSON.stringify(result.structuredContent)
+		});
+		return Object.freeze({
+			output: result.structuredContent,
+			contentParts: Object.freeze(finalParts)
+		});
+	}
+	return Object.freeze({
+		output: concatenatedText,
+		contentParts: Object.freeze(contentParts)
+	});
+}
+function mcpContentToMessageContent(part) {
+	switch (part.type) {
+		case "text": return {
+			type: "text",
+			text: part.text
+		};
+		case "image": return {
+			type: "image",
+			image: decodeBase64(part.data),
+			mimeType: part.mimeType
+		};
+		case "audio": return {
+			type: "audio",
+			audio: decodeBase64(part.data),
+			mimeType: part.mimeType
+		};
+		case "resource": {
+			const text = part.resource.text;
+			if (text !== void 0) return {
+				type: "text",
+				text
+			};
+			const blob = part.resource.blob;
+			if (blob !== void 0) return {
+				type: "file",
+				file: decodeBase64(blob),
+				mimeType: part.resource.mimeType ?? "application/octet-stream"
+			};
+			return {
+				type: "text",
+				text: `Resource ${part.resource.uri}`
+			};
+		}
+		case "resource_link": return {
+			type: "text",
+			text: formatResourceLinkPreview(part)
+		};
+	}
+}
+/**
+* Render the compact, model-facing preview for a `resource_link`. The
+* `uri` doubles as the `read_result` handle — an
+* {@link import('./mcp-resource-reader.js').createMcpResourceReader}
+* resolves it on demand via {@link MCPClient.readResource}.
+*/
+function formatResourceLinkPreview(part) {
+	const label = part.title === void 0 || part.title.length === 0 ? part.name : part.title;
+	const meta = [];
+	if (part.mimeType !== void 0) meta.push(part.mimeType);
+	if (part.size !== void 0) meta.push(`${part.size} bytes`);
+	return `[resource_link] ${label}${meta.length === 0 ? "" : ` (${meta.join(", ")})`}${part.description === void 0 || part.description.length === 0 ? "" : ` — ${part.description}`}\nFetch the full contents on demand with read_result, handle: ${part.uri}`;
+}
+/** Human-readable size of a base64 payload's decoded bytes (MC-8). */
+function approxDecodedSize(base64) {
+	const bytes = Math.floor(base64.length * 3 / 4);
+	return bytes >= 1024 ? `${Math.round(bytes / 1024)}kB` : `${bytes}B`;
+}
+/** Text descriptor for a non-text content part (MC-8). */
+function describeBinaryPart(kind, mimeType, data) {
+	return `[${kind} ${mimeType}, ~${approxDecodedSize(data)} — full payload in contentParts]`;
+}
+function decodeBase64(value) {
+	return Uint8Array.from(Buffer.from(value, "base64"));
+}
+
+//#endregion
+export { adaptCallResult };
+//# sourceMappingURL=adapt-result.js.map

package/dist/client/adapt-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapt-result.js","names":["contentParts: MessageContent[]","resourceLinkPreviews: string[]","outputSegments: string[]","meta: string[]"],"sources":["../../src/client/adapt-result.ts"],"sourcesContent":["/**\n * Result adaptation for the `toTools()` adapter (extracted from\n * `to-tools.ts` per F-MCP-001).\n *\n * Converts an MCP `CallToolResult` into a typed Graphorin `ToolReturn`,\n * handling the structured-content + outputSchema round-trip and the\n * backward-compatible TextContent mirror, and mapping each MCP content\n * part onto a Graphorin {@link MessageContent}.\n *\n * @packageDocumentation\n */\n\nimport type { MessageContent, ToolReturn, ZodLikeSchema } from '@graphorin/core';\nimport { incrementCounter } from '@graphorin/tools/audit';\nimport { MCPToolExecutionError } from '../errors/index.js';\nimport type { ServerIdentity } from '../transport/types.js';\nimport type { MCPCallToolResult, MCPContentPart } from './types.js';\n\n/** Arguments for {@link adaptCallResult}. */\nexport interface AdaptCallResultArgs {\n  readonly result: MCPCallToolResult;\n  readonly outputSchema?: ZodLikeSchema<unknown> | undefined;\n  readonly serverIdentity: ServerIdentity;\n  readonly toolName: string;\n  readonly logger?: (\n    level: 'debug' | 'info' | 'warn' | 'error',\n    message: string,\n    fields?: Record<string, unknown>,\n  ) => void;\n}\n\n/**\n * Convert an MCP `CallToolResult` into a typed Graphorin `ToolReturn`,\n * handling the structured-content + outputSchema round-trip and the\n * backward-compatible TextContent mirror.\n *\n * @internal\n */\nexport function adaptCallResult(args: AdaptCallResultArgs): ToolReturn<unknown> {\n  const { result, outputSchema, serverIdentity, toolName } = args;\n  // MC-4: the SDK deliberately does NOT throw on isError results — the\n  // failure marker must not launder into a successful ToolReturn. Throw\n  // the typed error so the executor records a real failure; the server's\n  // text rides in the message for model self-correction.\n  if (result.isError === true) {\n    const errorText = (result.content ?? [])\n      .filter((p): p is { type: 'text'; text: string } => p.type === 'text')\n      .map((p) => p.text)\n      .join('\\n');\n    incrementCounter('mcp.call.tool-error.total', {\n      server: serverIdentity.id,\n      tool: toolName,\n    });\n    throw new MCPToolExecutionError(\n      errorText.length > 0 ? errorText : `MCP tool '${toolName}' reported an error result.`,\n      { metadata: { tool: toolName } },\n    );\n  }\n  const contentParts: MessageContent[] = [];\n  // `resource_link` parts are NOT inlined: each contributes a compact\n  // preview (carrying the `uri` as a result handle) so the model fetches\n  // the body on demand via `read_result` instead of inflating context.\n  const resourceLinkPreviews: string[] = [];\n  for (const part of result.content) {\n    if (part.type === 'resource_link') {\n      incrementCounter('mcp.resource-link.emitted.total', {\n        server: serverIdentity.id,\n        tool: toolName,\n      });\n      resourceLinkPreviews.push(formatResourceLinkPreview(part));\n    }\n    const messagePart = mcpContentToMessageContent(part);\n    if (messagePart !== undefined) contentParts.push(messagePart);\n  }\n  const textParts = (result.content ?? []).filter(\n    (p): p is { type: 'text'; text: string } => p.type === 'text',\n  );\n  // MC-8: the typed `output` is the ONLY channel the agent loop\n  // serialises into the tool message — non-text parts must leave a\n  // text trace there (the full payloads stay in `contentParts`), and\n  // embedded resource TEXT joins the concatenation outright.\n  const outputSegments: string[] = [];\n  for (const part of result.content ?? []) {\n    switch (part.type) {\n      case 'text':\n        outputSegments.push(part.text);\n        break;\n      case 'image':\n      case 'audio':\n        outputSegments.push(describeBinaryPart(part.type, part.mimeType, part.data));\n        break;\n      case 'resource': {\n        if (part.resource.text !== undefined) {\n          outputSegments.push(part.resource.text);\n        } else if (part.resource.blob !== undefined) {\n          outputSegments.push(\n            `[resource ${part.resource.uri} ${part.resource.mimeType ?? 'application/octet-stream'}, ~${approxDecodedSize(part.resource.blob)} — full payload in contentParts]`,\n          );\n        } else {\n          outputSegments.push(`Resource ${part.resource.uri}`);\n        }\n        break;\n      }\n      case 'resource_link':\n        // Joined below via the read_result preview.\n        break;\n    }\n  }\n  const concatenatedText = [...outputSegments, ...resourceLinkPreviews].join('\\n');\n\n  if (result.structuredContent !== undefined) {\n    if (outputSchema !== undefined) {\n      const validation = outputSchema.safeParse(result.structuredContent);\n      if (validation.success) {\n        incrementCounter('mcp.structured-content.emitted.total', {\n          server: serverIdentity.id,\n          tool: toolName,\n        });\n        const finalParts = [...contentParts];\n        if (textParts.length === 0) {\n          finalParts.push({ type: 'text', text: JSON.stringify(result.structuredContent) });\n        }\n        return Object.freeze({\n          output: validation.data,\n          contentParts: Object.freeze(finalParts),\n        });\n      }\n      incrementCounter('mcp.structured-content.validation.failure.total', {\n        server: serverIdentity.id,\n        tool: toolName,\n      });\n      // MC-11: a schema mismatch must not silently drop the payload —\n      // log and mirror the structured content as JSON text, exactly\n      // like the no-schema branch does.\n      args.logger?.(\n        'warn',\n        'mcp.structured-content.validation.failed: payload mirrored as JSON text',\n        { server: serverIdentity.id, tool: toolName },\n      );\n      const fallbackParts = [...contentParts];\n      if (textParts.length === 0) {\n        fallbackParts.push({ type: 'text', text: JSON.stringify(result.structuredContent) });\n      }\n      return Object.freeze({\n        output:\n          concatenatedText.length > 0 ? concatenatedText : JSON.stringify(result.structuredContent),\n        contentParts: Object.freeze(fallbackParts),\n      });\n    } else {\n      incrementCounter('mcp.structured-content.emitted.total', {\n        server: serverIdentity.id,\n        tool: toolName,\n      });\n      const finalParts = [...contentParts];\n      if (textParts.length === 0) {\n        finalParts.push({ type: 'text', text: JSON.stringify(result.structuredContent) });\n      }\n      return Object.freeze({\n        output: result.structuredContent,\n        contentParts: Object.freeze(finalParts),\n      });\n    }\n  }\n\n  return Object.freeze({\n    output: concatenatedText,\n    contentParts: Object.freeze(contentParts),\n  });\n}\n\nfunction mcpContentToMessageContent(part: MCPContentPart): MessageContent | undefined {\n  switch (part.type) {\n    case 'text':\n      return { type: 'text', text: part.text };\n    case 'image':\n      return {\n        type: 'image',\n        image: decodeBase64(part.data),\n        mimeType: part.mimeType,\n      };\n    case 'audio':\n      return {\n        type: 'audio',\n        audio: decodeBase64(part.data),\n        mimeType: part.mimeType,\n      };\n    case 'resource': {\n      const text = part.resource.text;\n      if (text !== undefined) {\n        return { type: 'text', text };\n      }\n      const blob = part.resource.blob;\n      if (blob !== undefined) {\n        return {\n          type: 'file',\n          file: decodeBase64(blob),\n          mimeType: part.resource.mimeType ?? 'application/octet-stream',\n        };\n      }\n      return { type: 'text', text: `Resource ${part.resource.uri}` };\n    }\n    case 'resource_link':\n      return { type: 'text', text: formatResourceLinkPreview(part) };\n  }\n}\n\n/**\n * Render the compact, model-facing preview for a `resource_link`. The\n * `uri` doubles as the `read_result` handle — an\n * {@link import('./mcp-resource-reader.js').createMcpResourceReader}\n * resolves it on demand via {@link MCPClient.readResource}.\n */\nfunction formatResourceLinkPreview(\n  part: Extract<MCPContentPart, { type: 'resource_link' }>,\n): string {\n  const label = part.title === undefined || part.title.length === 0 ? part.name : part.title;\n  const meta: string[] = [];\n  if (part.mimeType !== undefined) meta.push(part.mimeType);\n  if (part.size !== undefined) meta.push(`${part.size} bytes`);\n  const metaStr = meta.length === 0 ? '' : ` (${meta.join(', ')})`;\n  const desc =\n    part.description === undefined || part.description.length === 0 ? '' : ` — ${part.description}`;\n  return `[resource_link] ${label}${metaStr}${desc}\\nFetch the full contents on demand with read_result, handle: ${part.uri}`;\n}\n\n/** Human-readable size of a base64 payload's decoded bytes (MC-8). */\nfunction approxDecodedSize(base64: string): string {\n  const bytes = Math.floor((base64.length * 3) / 4);\n  return bytes >= 1024 ? `${Math.round(bytes / 1024)}kB` : `${bytes}B`;\n}\n\n/** Text descriptor for a non-text content part (MC-8). */\nfunction describeBinaryPart(kind: 'image' | 'audio', mimeType: string, data: string): string {\n  return `[${kind} ${mimeType}, ~${approxDecodedSize(data)} — full payload in contentParts]`;\n}\n\nfunction decodeBase64(value: string): Uint8Array {\n  return Uint8Array.from(Buffer.from(value, 'base64'));\n}\n"],"mappings":"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"}