@graphorin/mcp 0.6.1 → 0.7.0

package/src/client/to-tools.ts

@@ -0,0 +1,294 @@
+/**
+ * `toTools()` adapter - bridges MCP tool descriptors into the
+ * Graphorin tool registry.
+ *
+ * The adapter orchestrates three extracted concerns (F-MCP-001):
+ *
+ * 1. Filters / namespaces the `listTools()` output, then resolves the
+ *    per-server effective `defer_loading` flag - see
+ *    {@link import('./defer-loading.js').resolveDeferLoading}.
+ * 2. Resolves the per-server inbound prompt-injection policy and strips
+ *    imperative payloads from each description - see
+ *    {@link import('./inbound-filters.js')}.
+ * 3. Converts each MCP tool into a strongly-typed Graphorin `Tool` whose
+ *    `execute(...)` calls back into {@link MCPClient.callTool} and adapts
+ *    the result - see {@link import('./adapt-result.js').adaptCallResult}.
+ *
+ * The trust class is pinned to `'mcp-derived'` so the agent runtime's
+ * per-step preamble fires regardless of the body-level policy.
+ *
+ * @packageDocumentation
+ */
+
+import type { ContentChunk, InboundSanitizationPolicy, Tool, ToolReturn } from '@graphorin/core';
+import { buildJsonSchemaValidator, type JsonSchemaLike } from '../registry/json-schema.js';
+import type { ServerIdentity } from '../transport/types.js';
+import { adaptCallResult } from './adapt-result.js';
+import {
+  _resetDeferLoadingDedupForTesting,
+  DEFAULT_DEFER_LOADING_THRESHOLD,
+  resolveDeferLoading,
+} from './defer-loading.js';
+import {
+  _resetInboundFiltersDedupForTesting,
+  resolveInboundPolicy,
+  sanitizeDescription,
+  sanitizeSchemaAnnotations,
+  warnOnPassthroughOverride,
+} from './inbound-filters.js';
+import { computeToolDefinitionHash } from './pinning.js';
+import type { MCPClient, MCPToolDefinition, MCPToToolsOptions } from './types.js';
+
+// Re-exported for backward compatibility: callers (and tests) import
+// these symbols directly from `./to-tools.js` and via the client barrel.
+export { adaptCallResult } from './adapt-result.js';
+export { DEFAULT_DEFER_LOADING_THRESHOLD } from './defer-loading.js';
+
+/**
+ * Reset every process-scoped dedup set owned by the adapter modules.
+ * Used by tests.
+ *
+ * @experimental
+ */
+export function _resetMcpAdapterDedupForTesting(): void {
+  _resetDeferLoadingDedupForTesting();
+  _resetInboundFiltersDedupForTesting();
+}
+
+/** Result returned by {@link adaptMCPTools}. */
+export 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;
+  /**
+   * W-105: tool names the operator downgraded below the sink classes
+   * via `sideEffectClassByTool` (`'read-only'` / `'pure'`). Each such
+   * tool leaves EVERY sink check - the dataflow gate, the Rule-of-Two
+   * writer forbid, the read-only capability gate - so operator audits
+   * should review this list. Empty when no override downgrades.
+   */
+  readonly downgradedTools: ReadonlyArray<string>;
+}
+
+/**
+ * Build the {@link Tool} array for the supplied MCP tool catalogue.
+ *
+ * @stable
+ */
+export 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 {
+  const opts = args.options ?? {};
+  const fingerprints = new Map<string, string>();
+  const filter = opts.filter;
+  const namespace = (opts.namespace ?? '').trim();
+  const filtered = filter === undefined ? 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 === undefined ? {} : { logger: args.logger }),
+  });
+
+  const resolvedInbound = resolveInboundPolicy(opts.inboundSanitization);
+  warnOnPassthroughOverride({
+    resolvedInbound,
+    serverIdentity: args.serverIdentity,
+    ...(args.logger === undefined ? {} : { logger: args.logger }),
+  });
+
+  const tools: Tool[] = [];
+  const downgradedTools: string[] = [];
+  for (const definition of filtered) {
+    const namespacedName =
+      namespace.length === 0 ? definition.name : `${namespace}.${definition.name}`;
+    const sideEffectClass = opts.sideEffectClassByTool?.[namespacedName] ?? 'external-stateful';
+    // W-105: a downgrade below the sink classes is an explicit operator
+    // trust decision with wide consequences - the tool leaves every sink
+    // check (dataflow gate, Rule-of-Two writer forbid, read-only
+    // capability gate). One WARN per tool at adaptation time + a result
+    // field so audits can pick it up; the server's own readOnlyHint is
+    // deliberately never trusted for this.
+    if (sideEffectClass === 'read-only' || sideEffectClass === 'pure') {
+      downgradedTools.push(namespacedName);
+      args.logger?.(
+        'warn',
+        `mcp.tools.side-effect-downgraded: operator override classifies '${namespacedName}' as '${sideEffectClass}' - the tool leaves every sink check (dataflow gate, Rule-of-Two writer forbid, read-only capability gate)`,
+        {
+          server: args.serverIdentity.id,
+          tool: namespacedName,
+          sideEffectClass,
+        },
+      );
+    }
+    const preferredModel = opts.preferredModelByTool?.[namespacedName];
+    // W-018: strip imperative payloads from schema ANNOTATIONS
+    // (description / title / $comment / string examples at any depth -
+    // the Invariant Labs tool-poisoning hiding place) before the
+    // schema reaches the validator, whose `toJSON()` is what the
+    // provider wire and `tool_search` re-expose.
+    const sanitizedInput = sanitizeSchemaAnnotations({
+      schema: definition.inputSchema as JsonSchemaLike,
+      inboundSanitization: resolvedInbound,
+      toolName: namespacedName,
+      serverIdentity: args.serverIdentity,
+    });
+    const sanitizedOutput =
+      definition.outputSchema === undefined
+        ? undefined
+        : sanitizeSchemaAnnotations({
+            schema: definition.outputSchema as JsonSchemaLike,
+            inboundSanitization: resolvedInbound,
+            toolName: namespacedName,
+            serverIdentity: args.serverIdentity,
+          });
+    const inputValidator = buildJsonSchemaValidator(sanitizedInput.schema);
+    const outputValidator =
+      sanitizedOutput === undefined ? undefined : buildJsonSchemaValidator(sanitizedOutput.schema);
+    // TOFU invariant (MC-6): the fingerprint hashes the RAW definition,
+    // never the sanitized copy. Hashing redacted bytes would invalidate
+    // the pins of existing deployments AND collapse two
+    // differently-poisoned schemas into one redacted hash, hiding drift.
+    // `sanitizeSchemaAnnotations` returns a clone and never mutates
+    // `definition`, so the order here is belt-and-braces.
+    const definitionHash = computeToolDefinitionHash(definition);
+    fingerprints.set(definition.name, definitionHash);
+    tools.push(
+      buildAdaptedTool({
+        client: args.client,
+        serverIdentity: args.serverIdentity,
+        definitionHash,
+        ...(args.logger !== undefined ? { 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 === undefined ? {} : { maxResultTokens: opts.maxResultTokens }),
+        ...(opts.truncationStrategy === undefined
+          ? {}
+          : { truncationStrategy: opts.truncationStrategy }),
+        ...(opts.callTimeoutMs === undefined ? {} : { callTimeoutMs: opts.callTimeoutMs }),
+        ...(preferredModel === undefined ? {} : { preferredModel }),
+      }),
+    );
+  }
+
+  return Object.freeze({
+    tools: Object.freeze(tools),
+    fingerprints,
+    autoDeferralFired,
+    resolvedDeferLoading,
+    resolvedInboundSanitization: resolvedInbound,
+    toolCount: total,
+    deferralThreshold: threshold,
+    downgradedTools: Object.freeze(downgradedTools),
+  });
+}
+
+interface BuildAdaptedToolArgs {
+  readonly client: MCPClient;
+  readonly serverIdentity: ServerIdentity;
+  readonly mcpToolName: string;
+  readonly graphorinToolName: string;
+  readonly description: string;
+  readonly inputSchema: import('@graphorin/core').ZodLikeSchema<unknown>;
+  readonly outputSchema?: import('@graphorin/core').ZodLikeSchema<unknown> | undefined;
+  readonly defer_loading: boolean;
+  readonly inboundSanitization: InboundSanitizationPolicy;
+  readonly sideEffectClass: import('@graphorin/core').SideEffectClass;
+  readonly maxResultTokens?: number;
+  readonly truncationStrategy?: import('@graphorin/core').TruncationStrategy;
+  /** Per-call timeout forwarded to `client.callTool` (MC-3/MC-5). */
+  readonly callTimeoutMs?: number;
+  /** MC-6: sha256 fingerprint of the producing MCP definition. */
+  readonly definitionHash: string;
+  readonly logger?: (
+    level: 'debug' | 'info' | 'warn' | 'error',
+    message: string,
+    fields?: Record<string, unknown>,
+  ) => void;
+  readonly preferredModel?:
+    | import('@graphorin/core').ModelHint
+    | import('@graphorin/core').ModelSpec;
+}
+
+function buildAdaptedTool(args: BuildAdaptedToolArgs): Tool<unknown, unknown, unknown> {
+  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 === undefined ? {} : { outputSchema: args.outputSchema }),
+    defer_loading: args.defer_loading,
+    inboundSanitization: args.inboundSanitization,
+    sideEffectClass: args.sideEffectClass,
+    sandboxPolicy: 'sandboxed' as const,
+    ...(args.maxResultTokens === undefined ? {} : { maxResultTokens: args.maxResultTokens }),
+    ...(args.truncationStrategy === undefined
+      ? {}
+      : { truncationStrategy: args.truncationStrategy }),
+    ...(args.preferredModel === undefined ? {} : { preferredModel: args.preferredModel }),
+    async execute(
+      input: unknown,
+      ctx?: import('@graphorin/core').ToolExecutionContext<unknown>,
+    ): Promise<ToolReturn<unknown>> {
+      // MC-5: the agent's per-call AbortSignal reaches the wire - an
+      // aborted run sends `notifications/cancelled` instead of orphaning
+      // the JSON-RPC request on the server. MC-3: the per-server call
+      // timeout rides along.
+      const result = await args.client.callTool(args.mcpToolName, input, {
+        ...(ctx?.signal !== undefined ? { signal: ctx.signal } : {}),
+        ...(args.callTimeoutMs !== undefined ? { timeoutMs: args.callTimeoutMs } : {}),
+      });
+      return adaptCallResult({
+        result,
+        outputSchema: args.outputSchema,
+        serverIdentity: args.serverIdentity,
+        toolName: args.graphorinToolName,
+        inboundSanitization: args.inboundSanitization,
+        ...(args.logger !== undefined ? { logger: args.logger } : {}),
+      });
+    },
+  } satisfies Tool<unknown, unknown, unknown>;
+  // MC-7: pre-stamp the provenance so the agent's inferToolSource -
+  // which honours an existing stamp - classifies tools passed via
+  // `config.tools` as 'mcp-derived' (untrusted for the WI-12 dataflow
+  // policy) instead of first-party. Zero operator boilerplate.
+  return Object.assign(tool, {
+    __source: { kind: 'mcp', serverIdentity: args.serverIdentity.id } as const,
+    // MC-6: operators persist this fingerprint to pin the approved
+    // definition (`toTools({ pinnedFingerprints })`).
+    __definitionHash: args.definitionHash,
+  });
+}
+
+/** Unused export kept for ergonomic test access. */
+export type AdaptedToolChunkBuffer = ReadonlyArray<ContentChunk>;

package/src/client/transport-factory.ts

@@ -0,0 +1,117 @@
+/**
+ * Factory that materialises a `@modelcontextprotocol/sdk` `Transport`
+ * instance from a {@link MCPTransportConfig}.
+ *
+ * The factory is small on purpose: every MCP-spec evolution (new
+ * transport, transport-specific option, transport-level header
+ * convention) lands here so the higher-level {@link createMCPClient}
+ * stays untouched.
+ *
+ * @packageDocumentation
+ */
+
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+import type { MCPTransportConfig } from '../transport/types.js';
+
+/**
+ * Outcome of the transport build, including the SDK transport
+ * instance and the helper hooks the client needs to forward to the
+ * SDK.
+ */
+export interface BuiltTransport {
+  readonly transport: Transport;
+  readonly disposeBeforeStart?: () => Promise<void>;
+}
+
+/**
+ * Live source of the outbound `Authorization` header for the HTTP
+ * transports. The bridge's `OAuthAuthorizationProvider` satisfies this
+ * structurally (its `resolveHeader()` already returns the full
+ * `Bearer <token>` value); a static `bearerToken` is wrapped into a
+ * constant resolver by {@link createMCPClient}.
+ *
+ * @internal
+ */
+export interface TransportAuthSource {
+  /** Resolve the full `Authorization` header value (e.g. `Bearer abc`). */
+  resolveHeader(): Promise<string> | string;
+}
+
+/**
+ * Wrap a `fetch` implementation so the live `Authorization` header is
+ * re-resolved and injected on **every** outgoing request. The wrapper
+ * always overwrites a caller-supplied `Authorization` header so the
+ * provider stays the single source of truth (refresh-ahead from
+ * {@link createOAuthAuthorizationProvider} fires per request).
+ */
+function authWrappedFetch(baseFetch: typeof fetch, auth: TransportAuthSource): typeof fetch {
+  return (async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const header = await auth.resolveHeader();
+    const headers = new Headers(init?.headers);
+    headers.set('Authorization', header);
+    return baseFetch(input, { ...init, headers });
+  }) as typeof fetch;
+}
+
+/**
+ * Build a SDK `Transport` from a {@link MCPTransportConfig}.
+ *
+ * When an `auth` source is supplied (HTTP transports only) the factory
+ * installs a per-request fetch-wrapper that re-resolves the
+ * `Authorization` header on every outgoing call - this is the seam that
+ * makes a long-lived agent session survive OAuth token expiry without
+ * re-creating the client.
+ *
+ * @stable
+ */
+export function buildTransport(
+  config: MCPTransportConfig,
+  options?: { readonly auth?: TransportAuthSource },
+): BuiltTransport {
+  switch (config.kind) {
+    case 'stdio': {
+      const stdio: Transport = new StdioClientTransport({
+        command: config.command,
+        ...(config.args === undefined ? {} : { args: [...config.args] }),
+        ...(config.env === undefined ? {} : { env: { ...config.env } }),
+        ...(config.cwd === undefined ? {} : { cwd: config.cwd }),
+        ...(config.stderr === undefined ? {} : { stderr: config.stderr }),
+      });
+      return Object.freeze({ transport: stdio });
+    }
+    case 'streamable-http': {
+      const url = typeof config.url === 'string' ? new URL(config.url) : config.url;
+      const headers = { ...(config.headers ?? {}) };
+      const baseFetch = config.fetch ?? fetch;
+      const fetchImpl =
+        options?.auth === undefined ? config.fetch : authWrappedFetch(baseFetch, options.auth);
+      // The SDK class's `sessionId: string | undefined` getter is
+      // structurally narrower than `Transport.sessionId?: string` in
+      // strict mode; route through `unknown` to keep the public
+      // surface clean.
+      const sdkTransport = new StreamableHTTPClientTransport(url, {
+        ...(fetchImpl === undefined ? {} : { fetch: fetchImpl }),
+        requestInit: { headers },
+        ...(config.sessionId === undefined ? {} : { sessionId: config.sessionId }),
+      });
+      const transport = sdkTransport as unknown as Transport;
+      return Object.freeze({ transport });
+    }
+    case 'sse': {
+      const url = typeof config.url === 'string' ? new URL(config.url) : config.url;
+      const headers = { ...(config.headers ?? {}) };
+      const baseFetch = config.fetch ?? fetch;
+      const fetchImpl =
+        options?.auth === undefined ? config.fetch : authWrappedFetch(baseFetch, options.auth);
+      const transport: Transport = new SSEClientTransport(url, {
+        ...(fetchImpl === undefined ? {} : { fetch: fetchImpl }),
+        requestInit: { headers },
+      });
+      return Object.freeze({ transport });
+    }
+  }
+}