@graphorin/mcp 0.6.1 → 0.7.0

package/src/client/mcp-resource-reader.ts

@@ -0,0 +1,183 @@
+/**
+ * {@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
+ */
+
+import { incrementCounter } from '@graphorin/tools/audit';
+import type { ResultReader, ResultReadOutcome, ResultReadRange } from '@graphorin/tools/result';
+import type { MCPClient, MCPResourceContent } from './types.js';
+
+/** Configuration for {@link createMcpResourceReader}. */
+export 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;
+  /**
+   * mcp-skills-06: allow a BARE (unscoped) resource URI to be tried
+   * against every configured client. Default `false` - handles minted
+   * by the adapter are scoped (`mcp:<serverId>:<uri>`) and resolve
+   * ONLY against their originating server, so a malicious server's
+   * link (or a prompt-injected model) cannot fetch a resource from a
+   * different, more-trusted server (the cross-server confused-deputy
+   * hop). Enable only when you accept that risk for legacy handles.
+   */
+  readonly allowCrossServer?: boolean;
+}
+
+/** Scoped-handle grammar minted by the tool adapter: `mcp:<serverId>:<uri>`. */
+const SCOPED_HANDLE = /^mcp:([^:]+):(.+)$/;
+
+/**
+ * Build a {@link ResultReader} that resolves MCP resource URIs through
+ * one or more connected {@link MCPClient}s.
+ *
+ * @stable
+ */
+export function createMcpResourceReader(opts: McpResourceReaderOptions): ResultReader {
+  const clients = [...opts.clients];
+  const defaultMaxBytes = opts.defaultMaxBytes ?? 65_536;
+  return {
+    async read(handle, range): Promise<ResultReadOutcome> {
+      if (clients.length === 0) {
+        throw new Error(
+          'createMcpResourceReader: no MCP clients configured to resolve resource handles.',
+        );
+      }
+      // mcp-skills-06: a scoped handle (`mcp:<serverId>:<uri>`) resolves
+      // ONLY against its originating server. The try-every-client loop
+      // survives solely for bare URIs behind the explicit
+      // `allowCrossServer` opt-in.
+      const scoped = SCOPED_HANDLE.exec(handle);
+      let uri = handle;
+      let candidates = clients;
+      if (scoped !== null) {
+        // W-140: the id segment is percent-encoded at mint time (ids
+        // carry ':' since W-016 made ports part of the identity).
+        const serverId = decodeURIComponent(scoped[1] ?? '');
+        uri = scoped[2] ?? '';
+        candidates = clients.filter((c) => c.serverIdentity.id === serverId);
+        if (candidates.length === 0) {
+          throw new Error(
+            `createMcpResourceReader: no configured client matches the handle's server ` +
+              `'${serverId}' - a handle only resolves against its originating server.`,
+          );
+        }
+      } else if (opts.allowCrossServer !== true) {
+        throw new Error(
+          `createMcpResourceReader: refusing to resolve the unscoped resource URI ` +
+            `${JSON.stringify(handle)} against every configured server (cross-server ` +
+            `confused-deputy risk). Use the scoped handle from the tool result ` +
+            `('mcp:<serverId>:<uri>'), or opt in with allowCrossServer: true.`,
+        );
+      }
+      let lastError: unknown;
+      for (const client of candidates) {
+        let content: MCPResourceContent;
+        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: MCPResourceContent): Buffer {
+  if (content.text !== undefined) return Buffer.from(content.text, 'utf8');
+  if (content.blob !== undefined) 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: MCPResourceContent,
+  range: ResultReadRange | undefined,
+  defaultMaxBytes: number,
+): ResultReadOutcome {
+  const buf = resourceBytes(content);
+  const full = buf.toString('utf8');
+  const totalBytes = buf.byteLength;
+  const cap = Math.max(0, range?.maxBytes ?? defaultMaxBytes);
+
+  if (range?.startLine !== undefined || range?.endLine !== undefined) {
+    const lines = full.split('\n');
+    const start = Math.max(1, range.startLine ?? 1);
+    const end = Math.min(lines.length, range.endLine ?? lines.length);
+    const selected = start <= end ? lines.slice(start - 1, end).join('\n') : '';
+    const capped = Buffer.byteLength(selected, 'utf8') > cap;
+    const out = capBytes(selected, cap);
+    return Object.freeze({
+      // TL-6: MCP resource content is mcp-derived by definition - the
+      // executor re-applies inbound sanitization + dataflow provenance
+      // by this class when read_result relays it.
+      producerTrustClass: 'mcp-derived' as const,
+      content: out,
+      bytes: Buffer.byteLength(out, 'utf8'),
+      totalBytes,
+      eof: end >= 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({
+    // TL-6: MCP resource content is mcp-derived by definition.
+    producerTrustClass: 'mcp-derived' as const,
+    content: slice.toString('utf8'),
+    bytes: slice.byteLength,
+    totalBytes,
+    eof: end >= totalBytes,
+  });
+}
+
+function clamp(value: number, lo: number, hi: number): number {
+  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: string, maxBytes: number): string {
+  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;
+  return Buffer.from(s, 'utf8').subarray(0, maxBytes).toString('utf8');
+}

package/src/client/pinning.ts

@@ -0,0 +1,48 @@
+/**
+ * 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
+ */
+
+import { createHash } from 'node:crypto';
+
+import type { MCPToolDefinition } from './types.js';
+
+/** Deterministic JSON render: object keys sorted recursively. */
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+/**
+ * Stable sha256 fingerprint of one MCP tool definition (MC-6).
+ *
+ * @stable
+ */
+export function computeToolDefinitionHash(def: MCPToolDefinition): string {
+  const canonical = stableStringify({
+    name: def.name,
+    description: def.description,
+    inputSchema: def.inputSchema,
+    ...(def.outputSchema !== undefined ? { outputSchema: def.outputSchema } : {}),
+    ...(def.title !== undefined ? { title: def.title } : {}),
+  });
+  return createHash('sha256').update(canonical).digest('hex');
+}

package/src/client/to-tools-run.ts

@@ -0,0 +1,178 @@
+/**
+ * W-080: the full `toTools()` pipeline (list -> adapt -> drift diff ->
+ * pin comparison / TOFU store legs) extracted from `client.ts` and
+ * parameterized by an {@link MCPClient}. Two callers:
+ *
+ * - the plain client's own `toTools()` (client = itself, the pre-W-080
+ *   behaviour byte-for-byte), and
+ * - the managed wrapper's `toTools()` (client = THE WRAPPER), so every
+ *   adapted `Tool.execute` closes over the wrapper and keeps working
+ *   after the wrapper swaps its inner client on reconnect - no
+ *   re-registration required.
+ *
+ * @packageDocumentation
+ */
+
+import type { Tool } from '@graphorin/core';
+import { incrementCounter } from '@graphorin/tools/audit';
+import { MCPToolPinningError } from '../errors/index.js';
+import { adaptMCPTools } from './to-tools.js';
+import type { CreateMCPClientOptions, MCPClient, MCPToToolsOptions } from './types.js';
+
+/** Mutable cross-snapshot fingerprint cell (MC-6 drift tracking). */
+export interface ToolFingerprintRef {
+  current: ReadonlyMap<string, string> | undefined;
+}
+
+/** Arguments for {@link runToTools}. @internal */
+export interface RunToToolsArgs {
+  /** The client the adapted tools CLOSE OVER (wrapper for managed). */
+  readonly client: MCPClient;
+  /**
+   * Cross-snapshot fingerprint cell. Owned by the caller so drift
+   * tracking spans the caller's lifetime (for the managed wrapper that
+   * includes reconnects - a rug-pull across a reconnect still diffs).
+   */
+  readonly fingerprintRef: ToolFingerprintRef;
+  readonly logger?: CreateMCPClientOptions['logger'];
+  readonly toolsOpts?: MCPToToolsOptions;
+}
+
+/**
+ * Run the list -> adapt -> drift -> pin pipeline against `args.client`.
+ *
+ * @internal
+ */
+export async function runToTools(args: RunToToolsArgs): Promise<ReadonlyArray<Tool>> {
+  const { client, fingerprintRef, logger, toolsOpts } = args;
+  const serverIdentity = client.serverIdentity;
+  const catalogue = await client.listTools();
+  const adapted = adaptMCPTools({
+    client,
+    serverIdentity,
+    catalogue,
+    ...(toolsOpts === undefined ? {} : { options: toolsOpts }),
+    ...(logger === undefined ? {} : { logger }),
+  });
+  // MC-6: cross-snapshot drift - a definition changing behind an
+  // already-seen name within this client's lifetime is audited.
+  if (fingerprintRef.current !== undefined) {
+    for (const [name, hash] of adapted.fingerprints) {
+      const previous = fingerprintRef.current.get(name);
+      if (previous !== undefined && previous !== hash) {
+        incrementCounter('mcp.tools.changed.total', {
+          server: serverIdentity.id,
+          tool: name,
+        });
+        logger?.('warn', 'mcp.tools.changed: definition drifted between snapshots', {
+          server: serverIdentity.id,
+          tool: name,
+          previous,
+          current: hash,
+        });
+      }
+    }
+  }
+  fingerprintRef.current = adapted.fingerprints;
+  // MC-6: operator pins from a previously approved snapshot - the
+  // rug-pull (approve-then-swap across restarts) posture. C6 extends it
+  // with durable trust-on-first-use via `pinStore`: the first snapshot
+  // is RECORDED, later snapshots are COMPARED, and a store-backed
+  // mismatch defaults to 'reject' (a persisted first approval is an
+  // explicit trust decision).
+  let pins = toolsOpts?.pinnedFingerprints;
+  let mismatchAction = toolsOpts?.onPinMismatch ?? 'warn';
+  // W-079: the added/removed lifecycle legs only apply to STORE pins -
+  // a store snapshot covers the full catalogue by construction, while
+  // explicit pinnedFingerprints may deliberately pin a subset.
+  let pinsFromStore = false;
+  const pinStore = toolsOpts?.pinStore;
+  if (pins === undefined && pinStore !== undefined) {
+    const stored = await pinStore.get(serverIdentity.id);
+    if (stored === undefined) {
+      const recorded: Record<string, string> = {};
+      for (const [name, hash] of adapted.fingerprints) recorded[name] = hash;
+      await pinStore.set(serverIdentity.id, recorded);
+      incrementCounter('mcp.tools.pins-recorded.total', { server: serverIdentity.id });
+      logger?.('info', 'mcp.tools.pins-recorded: first-use fingerprints stored', {
+        server: serverIdentity.id,
+        tools: Object.keys(recorded).length,
+      });
+    } else {
+      pins = stored;
+      pinsFromStore = true;
+      mismatchAction = toolsOpts?.onPinMismatch ?? 'reject';
+    }
+  }
+  if (pins !== undefined) {
+    for (const [name, pinned] of Object.entries(pins)) {
+      const current = adapted.fingerprints.get(name);
+      if (current !== undefined && current !== pinned) {
+        if (mismatchAction === 'reject') {
+          throw new MCPToolPinningError(
+            `MCP tool '${name}' no longer matches its pinned definition fingerprint - the server changed the definition behind an approved name.`,
+            { metadata: { server: serverIdentity.id, tool: name } },
+          );
+        }
+        incrementCounter('mcp.tools.pin-mismatch.total', {
+          server: serverIdentity.id,
+          tool: name,
+        });
+        logger?.('warn', 'mcp.tools.pin-mismatch: pinned fingerprint diverged', {
+          server: serverIdentity.id,
+          tool: name,
+        });
+      }
+    }
+    // W-079: the comparison loop above only sees names that were
+    // pinned. A server that passed its first-use recording can later
+    // ADD a poisoned tool (or rename one) - without this leg it would
+    // enter the catalogue with no counter and no rejection.
+    const pinnedNames = new Set(Object.keys(pins));
+    for (const name of pinsFromStore ? adapted.fingerprints.keys() : []) {
+      if (pinnedNames.has(name)) continue;
+      if (mismatchAction === 'reject') {
+        throw new MCPToolPinningError(
+          `MCP server added tool '${name}' after its catalogue was pinned - a post-approval addition is rejected until the operator re-pins (onPinMismatch: 'accept-and-update').`,
+          { metadata: { server: serverIdentity.id, tool: name } },
+        );
+      }
+      incrementCounter('mcp.tools.pin-added.total', {
+        server: serverIdentity.id,
+        tool: name,
+      });
+      logger?.('warn', 'mcp.tools.pin-added: tool added after the catalogue was pinned', {
+        server: serverIdentity.id,
+        tool: name,
+      });
+    }
+    // W-079: removals are not an injection by themselves, but they can
+    // hide a rename (remove + add) - keep them observable.
+    for (const name of pinsFromStore ? pinnedNames : []) {
+      if (adapted.fingerprints.has(name)) continue;
+      incrementCounter('mcp.tools.pin-removed.total', {
+        server: serverIdentity.id,
+        tool: name,
+      });
+      logger?.('info', 'mcp.tools.pin-removed: pinned tool disappeared from the catalogue', {
+        server: serverIdentity.id,
+        tool: name,
+      });
+    }
+    // W-079: the explicit operator path to accept a changed catalogue -
+    // overwrite the store with the CURRENT snapshot so subsequent
+    // toTools() calls are clean. Explicit pinnedFingerprints stay
+    // read-only (they are config, not a store).
+    if (mismatchAction === 'accept-and-update' && pinsFromStore && pinStore !== undefined) {
+      const refreshed: Record<string, string> = {};
+      for (const [name, hash] of adapted.fingerprints) refreshed[name] = hash;
+      await pinStore.set(serverIdentity.id, refreshed);
+      incrementCounter('mcp.tools.pins-updated.total', { server: serverIdentity.id });
+      logger?.('info', 'mcp.tools.pins-updated: operator accepted the current catalogue', {
+        server: serverIdentity.id,
+        tools: Object.keys(refreshed).length,
+      });
+    }
+  }
+  return adapted.tools;
+}