@mcp-i/core 1.1.0-canary.2 → 1.1.0

package/src/middleware/mcpi-transport.ts

@@ -0,0 +1,162 @@
+/**
+ * MCPITransport — Proof-injecting Transport Wrapper
+ *
+ * Wraps any MCP Transport to intercept `tools/call` responses and attach
+ * MCP-I detached proofs. Uses only the public Transport interface — no
+ * private SDK internals accessed.
+ *
+ * The McpServer never knows this wrapper exists. It sees a normal transport.
+ * The connected client sees normal MCP responses with an added `_meta.proof`.
+ *
+ * How it works:
+ *   1. Incoming `tools/call` requests are captured (by id) to record tool
+ *      name and arguments for proof generation.
+ *   2. Outgoing responses for those ids get a proof injected into `_meta`.
+ *   3. All other message types pass through unmodified.
+ *
+ * @module mcpi-transport
+ */
+
+import type { MCPIMiddleware, MCPIToolHandler } from "./with-mcpi.js";
+import { logger } from "../logging/index.js";
+
+/** Minimal Transport interface — matches @modelcontextprotocol/sdk Transport */
+export interface Transport {
+  start(): Promise<void>;
+  send(message: JSONRPCMessage): Promise<void>;
+  close(): Promise<void>;
+  onmessage?: (message: JSONRPCMessage) => void;
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+}
+
+export type JSONRPCMessage = Record<string, unknown>;
+
+interface PendingCall {
+  toolName: string;
+  args: Record<string, unknown>;
+}
+
+type ToolResult = {
+  content: Array<{ type: string; text: string; [key: string]: unknown }>;
+  isError?: boolean;
+  [key: string]: unknown;
+};
+
+/**
+ * Creates a transport wrapper that injects MCP-I proofs into `tools/call`
+ * responses.
+ *
+ * @param inner   - The real transport (Stdio, HTTP, etc.)
+ * @param mcpi    - Configured MCPIMiddleware instance
+ * @param exclude - Tool names to skip proof generation for
+ */
+export function createMCPITransport(
+  inner: Transport,
+  mcpi: MCPIMiddleware,
+  exclude: string[] = ["_mcpi", "_mcpi_handshake"],
+): Transport {
+  // Request id → { toolName, args } for pending tool calls
+  const pending = new Map<unknown, PendingCall>();
+
+  const wrapper: Transport = {
+    start: () => inner.start(),
+    close: () => inner.close(),
+
+    // McpServer writes into wrapper.onmessage — forward to inner so the
+    // real transport can drive it.
+    set onmessage(handler: ((msg: JSONRPCMessage) => void) | undefined) {
+      inner.onmessage = handler;
+    },
+    get onmessage() {
+      return inner.onmessage;
+    },
+
+    set onclose(handler: (() => void) | undefined) {
+      inner.onclose = handler;
+    },
+    get onclose() {
+      return inner.onclose;
+    },
+
+    set onerror(handler: ((err: Error) => void) | undefined) {
+      inner.onerror = handler;
+    },
+    get onerror() {
+      return inner.onerror;
+    },
+
+    // McpServer calls send() for every outgoing message.
+    // Intercept tools/call responses here to inject proofs.
+    async send(message: JSONRPCMessage): Promise<void> {
+      const id = message.id;
+      const call = id !== undefined ? pending.get(id) : undefined;
+
+      if (call) {
+        pending.delete(id);
+        try {
+          const rawResult = message.result as ToolResult | undefined;
+          if (rawResult && !rawResult.isError) {
+            const handler: MCPIToolHandler = async () => rawResult;
+            const addProof = mcpi.wrapWithProof(call.toolName, handler);
+            const proofed = await addProof(call.args);
+            if (proofed._meta !== undefined) {
+              message = {
+                ...message,
+                result: proofed,
+              };
+            }
+          }
+        } catch (error) {
+          logger.error("[mcpi-transport] Proof injection failed", {
+            tool: call.toolName,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          const rawResult = message.result as ToolResult | undefined;
+          if (rawResult) {
+            rawResult._meta = {
+              proofError: "Proof generation failed — response is unproven",
+            };
+            message = { ...message, result: rawResult };
+          }
+        }
+      }
+
+      return inner.send(message);
+    },
+  };
+
+  // Intercept incoming messages from the real transport to capture
+  // tools/call requests before McpServer processes them.
+  // We defer setting inner.onmessage until McpServer has set wrapper.onmessage
+  // via server.connect() — so we proxy through the getter/setter above and
+  // add our interception in a one-time initializer on start().
+  const originalStart = inner.start.bind(inner);
+  wrapper.start = async () => {
+    await originalStart();
+    // At this point McpServer has called server.connect(wrapper) which set
+    // wrapper.onmessage = <McpServer handler>. That assignment forwarded to
+    // inner.onmessage via the setter above. Now we inject our interceptor.
+    const downstream = inner.onmessage;
+    inner.onmessage = (message: JSONRPCMessage) => {
+      if (
+        message.method === "tools/call" &&
+        message.id !== undefined
+      ) {
+        const params = message.params as
+          | { name?: string; arguments?: Record<string, unknown> }
+          | undefined;
+        const toolName = params?.name;
+        if (toolName && !exclude.includes(toolName)) {
+          pending.set(message.id, {
+            toolName,
+            args: params?.arguments ?? {},
+          });
+        }
+      }
+      downstream?.(message);
+    };
+  };
+
+  return wrapper;
+}

package/src/middleware/with-mcpi-server.ts

@@ -8,16 +8,19 @@
  *   import { withMCPI } from '@mcp-i/core/middleware';
  *   const mcpi = await withMCPI(server, { crypto: new NodeCryptoProvider() });
  *   // All tools registered on `server` now get proofs automatically.
+ *   await server.connect(transport); // transport is transparently wrapped
  */
 
 import type { CryptoProvider } from "../providers/base.js";
-import { generateDidKeyFromBase64 } from "../utils/did-helpers.js";
+import { generateDidKeyFromBase64, didKeyFragment } from "../utils/did-helpers.js";
 import {
+  MCPI_ACTIONS,
   createMCPIMiddleware,
   type MCPIIdentityConfig,
   type MCPIDelegationConfig,
   type MCPIMiddleware,
 } from "./with-mcpi.js";
+import { createMCPITransport, type Transport } from "./mcpi-transport.js";
 import { z } from "zod";
 
 export interface WithMCPIOptions {
@@ -35,6 +38,12 @@ export interface WithMCPIOptions {
   excludeTools?: string[];
   /** Delegation verification config */
   delegation?: MCPIDelegationConfig;
+  /**
+   * How the MCP-I protocol tool is exposed on the server.
+   * - "tool" (default): auto-register `_mcpi`
+   * - "none": do not register MCP-I tool (use middleware APIs for custom runtime hooks)
+   */
+  handshakeExposure?: "tool" | "none";
 }
 
 /**
@@ -50,33 +59,43 @@ export async function generateIdentity(
   const did = generateDidKeyFromBase64(keyPair.publicKey);
   return {
     did,
-    kid: `${did}#keys-1`,
+    kid: `${did}#${didKeyFragment(did)}`,
     privateKey: keyPair.privateKey,
     publicKey: keyPair.publicKey,
   };
 }
 
 /**
- * McpServer type — minimal interface to avoid hard dependency on the SDK.
- * Matches the public API of @modelcontextprotocol/sdk McpServer.
+ * Minimal McpServer interface — avoids hard dependency on @modelcontextprotocol/sdk.
+ * Matches the subset of McpServer's public API that withMCPI() uses.
  */
 interface McpServerLike {
-  server: {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [key: string]: any;
-  };
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  registerTool(...args: any[]): void;
+  connect(transport: Transport): Promise<unknown>;
+  registerTool(
+    name: string,
+    config: Record<string, unknown>,
+    handler: (args: unknown) => Promise<unknown>,
+  ): void;
 }
 
 /**
  * Add MCP-I to a McpServer instance.
  *
  * 1. Auto-generates Ed25519 identity (or uses provided one)
- * 2. Registers `_mcpi_handshake` tool
- * 3. Intercepts the `tools/call` request handler to auto-attach proofs
+ * 2. Registers `_mcpi` tool by default (`handshakeExposure: "tool"`)
+ * 3. Patches `server.connect()` to transparently wrap the transport with
+ *    MCPITransport, which injects detached proofs into all `tools/call`
+ *    responses using only the public Transport interface.
+ *
+ * The user-facing API is unchanged — register tools before or after this
+ * call, then connect as normal:
  *
- * @param server - McpServer instance
+ * ```ts
+ * const mcpi = await withMCPI(server, { crypto: new NodeCryptoProvider() });
+ * await server.connect(transport); // MCPITransport wraps silently
+ * ```
+ *
+ * @param server  - McpServer instance
  * @param options - Configuration
  * @returns The MCPIMiddleware instance for advanced usage (wrapWithDelegation, etc.)
  */
@@ -97,88 +116,60 @@ export async function withMCPI(
     options.crypto,
   );
 
-  // Register _mcpi_handshake tool
-  server.registerTool(
-    "_mcpi_handshake",
-    {
-      description:
-        "MCP-I identity handshake — establishes a cryptographic session",
-      inputSchema: {
-        nonce: z.string().describe("Client-generated unique nonce"),
-        audience: z
-          .string()
-          .describe("Intended audience (server DID or URL)"),
-        timestamp: z.number().describe("Unix epoch seconds"),
+  if ((options.handshakeExposure ?? "tool") === "tool") {
+    // Register the unified _mcpi tool for protocol operations.
+    server.registerTool(
+      "_mcpi",
+      {
+        description:
+          "MCP-I protocol — identity verification, session handshake, and server metadata",
+        annotations: { title: "MCP-I Protocol", readOnlyHint: true },
+        inputSchema: {
+          action: z
+            .enum(MCPI_ACTIONS)
+            .describe("Protocol operation to perform"),
+          nonce: z
+            .string()
+            .optional()
+            .describe("Client-generated unique nonce (handshake)"),
+          audience: z
+            .string()
+            .optional()
+            .describe("Intended audience (handshake)"),
+          timestamp: z
+            .number()
+            .optional()
+            .describe("Unix epoch seconds (handshake)"),
+          agentDid: z
+            .string()
+            .optional()
+            .describe("Client agent DID (handshake, optional)"),
+        },
       },
-    },
-    async (args: unknown) => {
-      const result = await mcpi.handleHandshake(args as Record<string, unknown>);
-      return {
-        ...result,
-        content: result.content.map((c) => ({ ...c, type: "text" as const })),
-      };
-    },
-  );
-
-  // Auto-proof interception: wrap the tools/call handler
-  const proofAllTools = options.proofAllTools ?? true;
-
-  if (proofAllTools) {
-    const lowLevel = server.server;
-    const handlers: Map<string, Function> =
-      lowLevel._requestHandlers;
-    const original = handlers.get("tools/call");
-
-    if (original) {
-      handlers.set(
-        "tools/call",
-        async (request: Record<string, unknown>, extra: unknown) => {
-          const result = (await (
-            original as (
-              req: Record<string, unknown>,
-              ext: unknown,
-            ) => Promise<Record<string, unknown>>
-          )(request, extra)) as {
-            content?: Array<{
-              type: string;
-              text: string;
-              [key: string]: unknown;
-            }>;
-            isError?: boolean;
-            _meta?: Record<string, unknown>;
-            [key: string]: unknown;
-          };
-
-          const params = request.params as
-            | { name?: string; arguments?: Record<string, unknown> }
-            | undefined;
-          const toolName = params?.name;
-
-          if (
-            !toolName ||
-            toolName === "_mcpi_handshake" ||
-            result.isError
-          ) {
-            return result;
-          }
+      async (args: unknown) => {
+        const result = await mcpi.handleMCPI(
+          args as Record<string, unknown>,
+        );
+        return {
+          ...result,
+          content: result.content.map((c) => ({ ...c, type: "text" as const })),
+        };
+      },
+    );
+  }
 
-          if (options.excludeTools?.includes(toolName)) {
-            return result;
-          }
+  // Auto-proof interception via transport wrapper (public API only).
+  //
+  // We patch server.connect() so that whatever transport the caller passes
+  // is silently wrapped with MCPITransport before McpServer sees it.
+  // Tool registration order does not matter — proofs are injected at the
+  // transport boundary, after McpServer has already dispatched the call.
+  if (options.proofAllTools !== false) {
+    const exclude = ["_mcpi", "_mcpi_handshake", ...(options.excludeTools ?? [])];
+    const originalConnect = server.connect.bind(server);
 
-          // Use wrapWithProof to add proof — it handles session management
-          const addProof = mcpi.wrapWithProof(
-            toolName,
-            async () => result as {
-              content: Array<{ type: string; text: string; [key: string]: unknown }>;
-              isError?: boolean;
-              [key: string]: unknown;
-            },
-          );
-          return addProof(params?.arguments ?? {});
-        },
-      );
-    }
+    server.connect = (transport: Transport) =>
+      originalConnect(createMCPITransport(transport, mcpi, exclude));
   }
 
   return mcpi;

package/src/middleware/with-mcpi.ts

@@ -4,8 +4,8 @@
  * Adds identity, session management, and proof generation to MCP servers.
  *
  * For most use cases, prefer the high-level `withMCPI()` adapter from
- * `./with-mcpi-server.ts` which auto-registers the handshake tool and
- * auto-attaches proofs to all tool responses:
+ * `./with-mcpi-server.ts` which (by default) auto-registers the handshake
+ * tool and auto-attaches proofs to all tool responses:
  *
  *   import { withMCPI } from '@mcp-i/core';
  *   await withMCPI(server, { crypto: new NodeCryptoProvider() });
@@ -47,6 +47,7 @@ import {
   type DelegationRecord,
 } from "../types/protocol.js";
 import { logger } from "../logging/index.js";
+import { MCPI_ERROR_CODES } from "../errors.js";
 import { canonicalizeJSON } from "../delegation/utils.js";
 import { base64urlDecodeToBytes, base64urlEncodeFromBytes, bytesToBase64 } from "../utils/base64.js";
 
@@ -55,8 +56,12 @@ export interface MCPIIdentityConfig {
   kid: string;
   privateKey: string;
   publicKey: string;
+  agentName?: string;
 }
 
+export const MCPI_ACTIONS = ["handshake", "identity", "reputation"] as const;
+type MCPIAction = (typeof MCPI_ACTIONS)[number];
+
 export interface MCPIDelegationConfig {
   /**
    * Optional custom DID resolver. If it returns null, middleware falls back to
@@ -103,8 +108,8 @@ export interface MCPIConfig {
   /**
    * When true, automatically creates a session on the first tool call
    * if no session exists. Useful for demos and development where
-   * MCP clients don't support the _mcpi_handshake flow.
-   * In production, MCP-I-aware clients handle handshake automatically.
+   * MCP clients don't support the `_mcpi` handshake flow.
+   * In production, MCP-I-aware runtimes should execute handshake before tool calls.
    */
   autoSession?: boolean;
 }
@@ -155,12 +160,29 @@ export interface MCPIMiddleware {
   proofGenerator: ProofGenerator;
 
   /**
+   * Unified tool definition for `_mcpi`.
+   * Include this in your ListToolsRequest handler's tool list.
+   */
+  mcpiTool: MCPIToolDefinition;
+
+  /**
+   * @deprecated Use `mcpiTool` (`_mcpi` with `action: "handshake"`).
    * Tool definition for `_mcpi_handshake`.
    * Include this in your ListToolsRequest handler's tool list.
    */
   handshakeTool: MCPIToolDefinition;
 
   /**
+   * Handle a unified `_mcpi` action. Use this in your CallToolRequest handler
+   * when `request.params.name === '_mcpi'`.
+   */
+  handleMCPI(args: Record<string, unknown>): Promise<{
+    content: Array<{ type: string; text: string }>;
+    isError?: boolean;
+  }>;
+
+  /**
+   * @deprecated Use `handleMCPI` with `action: "handshake"`.
    * Handle a handshake call. Use this in your CallToolRequest handler
    * when `request.params.name === '_mcpi_handshake'`.
    */
@@ -267,7 +289,8 @@ function validateScopeAttenuation(
  * Create MCP-I middleware for a standard MCP SDK Server.
  *
  * For most use cases, prefer {@link withMCPI} from `./with-mcpi-server.ts`
- * which wraps this function and auto-registers handshake + auto-attaches proofs.
+ * which wraps this function and (by default) auto-registers handshake +
+ * auto-attaches proofs.
  *
  * Use `createMCPIMiddleware` directly when:
  * - You use the low-level `Server` API (not `McpServer`)
@@ -331,6 +354,33 @@ export function createMCPIMiddleware(
     },
   };
 
+  const mcpiTool: MCPIToolDefinition = {
+    name: "_mcpi",
+    description:
+      "MCP-I protocol — identity verification, session handshake, and server metadata",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: [...MCPI_ACTIONS],
+          description: "Protocol operation to perform",
+        },
+        nonce: { type: "string", description: "Client-generated unique nonce" },
+        audience: {
+          type: "string",
+          description: "Intended audience (server DID or URL)",
+        },
+        timestamp: { type: "number", description: "Unix epoch seconds" },
+        agentDid: {
+          type: "string",
+          description: "Client agent DID (optional)",
+        },
+      },
+      required: ["action"],
+    },
+  };
+
   async function handleHandshake(args: Record<string, unknown>): Promise<{
     content: Array<{ type: string; text: string }>;
     isError?: boolean;
@@ -343,7 +393,7 @@ export function createMCPIMiddleware(
             text: JSON.stringify({
               success: false,
               error: {
-                code: "MCPI_INVALID_HANDSHAKE",
+                code: MCPI_ERROR_CODES.handshake_failed,
                 message:
                   "Invalid handshake format: requires nonce (string), audience (string), and timestamp (positive integer)",
               },
@@ -381,9 +431,82 @@ export function createMCPIMiddleware(
     };
   }
 
+  async function handleIdentity(): Promise<{
+    content: Array<{ type: string; text: string }>;
+    isError?: boolean;
+  }> {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            did: identity.did,
+            kid: identity.kid,
+            name: config.identity.agentName ?? identity.did,
+            capabilities: ["handshake", "signing", "verification"],
+            protocolVersion: "1.0.0",
+          }),
+        },
+      ],
+    };
+  }
+
+  async function handleMCPI(args: Record<string, unknown>): Promise<{
+    content: Array<{ type: string; text: string }>;
+    isError?: boolean;
+  }> {
+    const action =
+      typeof args.action === "string"
+        ? (args.action as MCPIAction)
+        : undefined;
+
+    switch (action) {
+      case "handshake":
+        return handleHandshake(args);
+
+      case "identity":
+        return handleIdentity();
+
+      case "reputation":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                success: false,
+                error: {
+                  code: MCPI_ERROR_CODES.runtime_error,
+                  message:
+                    'action: "reputation" is not yet implemented.',
+                },
+              }),
+            },
+          ],
+          isError: true,
+        };
+
+      default:
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                success: false,
+                error: {
+                  code: MCPI_ERROR_CODES.invalid_request,
+                  message: `Unknown _mcpi action: "${action ?? "(missing)"}". Valid actions: ${MCPI_ACTIONS.join(", ")}`,
+                },
+              }),
+            },
+          ],
+          isError: true,
+        };
+    }
+  }
+
   /**
    * Auto-create a session for proof generation when no handshake has occurred.
-   * In production, MCP-I-aware clients handle the handshake automatically.
+   * In production, MCP-I-aware runtimes should execute handshake before tool calls.
    * This convenience mode allows non-MCP-I clients (like MCP Inspector) to
    * still see proofs without manual handshake.
    */
@@ -449,8 +572,14 @@ export function createMCPIMiddleware(
 
         // Attach proof as _meta (rendered by MCP Inspector, invisible to LLMs)
         result._meta = { proof };
-      } catch {
-        // Proof generation failure is non-fatal — the tool result is still valid
+      } catch (error) {
+        logger.error("[mcpi] Proof generation failed", {
+          tool: toolName,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        result._meta = {
+          proofError: "Proof generation failed — response is unproven",
+        };
       }
 
       return result;
@@ -638,8 +767,13 @@ export function createMCPIMiddleware(
           }
         }
 
+        const skipStatusForLegacy =
+          legacyUnsafeDelegationEnabled &&
+          !!credential.credentialStatus &&
+          !delegationConfig?.statusListResolver;
         const credentialVerification = await verifier.verifyDelegationCredential(
           credential,
+          skipStatusForLegacy ? { skipStatus: true } : undefined,
         );
         if (!credentialVerification.valid) {
           return {
@@ -747,7 +881,7 @@ export function createMCPIMiddleware(
           `[mcpi] Delegation verification failed for "${toolName}": ${verificationResult.reason}`,
         );
         return buildDelegationErrorResponse(
-          "delegation_invalid",
+          MCPI_ERROR_CODES.delegation_invalid,
           verificationResult.reason ?? "Unknown delegation validation error",
         );
       }
@@ -758,7 +892,7 @@ export function createMCPIMiddleware(
           `[mcpi] Delegation missing required scope "${config.scopeId}" for "${toolName}"`,
         );
         return buildDelegationErrorResponse(
-          "delegation_scope_missing",
+          MCPI_ERROR_CODES.insufficient_scope,
           `Required scope "${config.scopeId}" not in delegation scopes`,
         );
       }
@@ -780,7 +914,9 @@ export function createMCPIMiddleware(
     identity: config.identity,
     sessionManager,
     proofGenerator,
+    mcpiTool,
     handshakeTool,
+    handleMCPI,
     handleHandshake,
     wrapWithProof,
     wrapWithDelegation,