mcpose 2.0.2 → 3.0.0

package/dist/backendClient.d.ts

@@ -2,6 +2,7 @@
  * Backend MCP client factory.
  * Modes: stdio (spawns child process) or HTTP/SSE (connects to running server).
  */
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 /** Backend connection config. */
 export interface BackendConfig {
@@ -11,6 +12,10 @@ export interface BackendConfig {
     args?: string[];
     /** HTTP/SSE URL of running backend. Takes precedence over stdio. */
     url?: string;
+    /** Custom HTTP headers sent on every request to the backend (HTTP/SSE only). */
+    headers?: Record<string, string>;
+    /** OAuth provdider for interactive/browser auth + transparent token refresh (HHT/SSE only). */
+    authProvider?: OAuthClientProvider;
 }
 export type BackendClient = Client;
 /**

package/dist/backendClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backendClient.d.ts","sourceRoot":"","sources":["../src/backendClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAInE,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC,CAqBxB"}
+{"version":3,"file":"backendClient.d.ts","sourceRoot":"","sources":["../src/backendClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AASnE,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+FAA+F;IAC/F,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC,CAyBxB"}

package/dist/backendClient.js

@@ -1,10 +1,7 @@
-/**
- * Backend MCP client factory.
- * Modes: stdio (spawns child process) or HTTP/SSE (connects to running server).
- */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StreamableHTTPClientTransport, } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { VERSION } from './version.js';
 /**
  * Creates and connects an MCP client to the backend.
  * @throws If neither `command` nor `url` provided, or connection fails.
@@ -13,21 +10,32 @@ export async function createBackendClient(config) {
     if (!config.command && !config.url) {
         throw new Error('mcpose: either command or url must be provided in BackendConfig');
     }
-    const client = new Client({ name: 'mcpose-backend', version: '1.1.1' }, { capabilities: {} });
+    const client = new Client({ name: 'mcpose-backend', version: VERSION }, { capabilities: {} });
     const transport = config.url
-        ? getHttpTransport(config.url)
+        ? getHttpTransport(config.url, config.headers, config.authProvider)
         : new StdioClientTransport({
             command: config.command,
             args: config.args ?? [],
         });
+    // The SDK's own transports are not assignable to its own `Transport`
+    // interface under `exactOptionalPropertyTypes` (the interface declares
+    // `sessionId?: string`, the implementations `sessionId: string | undefined`).
+    // Purely a declaration mismatch upstream — the value is a real Transport.
     await client.connect(transport);
     return client;
 }
-const getHttpTransport = (urlString) => {
+const getHttpTransport = (urlString, headers, authProvider) => {
     const url = new URL(urlString);
     if (url.protocol !== 'http:' && url.protocol !== 'https:') {
         throw new Error(`mcpose: unsupported URL protocol "${url.protocol}" — only http: and https: are allowed`);
     }
-    return new StreamableHTTPClientTransport(url);
+    const opts = {};
+    if (headers) {
+        opts.requestInit = { headers };
+    }
+    if (authProvider) {
+        opts.authProvider = authProvider;
+    }
+    return new StreamableHTTPClientTransport(url, opts);
 };
 //# sourceMappingURL=backendClient.js.map

package/dist/backendClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"backendClient.js","sourceRoot":"","sources":["../src/backendClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAcnG;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAqB;IAErB,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC5C,EAAE,YAAY,EAAE,EAAE,EAAE,CACrB,CAAC;IAEF,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG;QAC1B,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC;QAC9B,CAAC,CAAC,IAAI,oBAAoB,CAAC;YACvB,OAAO,EAAE,MAAM,CAAC,OAAQ;YACxB,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE;SACxB,CAAC,CAAC;IAEP,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,gBAAgB,GAAG,CAAC,SAAiB,EAAE,EAAE;IAC7C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,qCAAqC,GAAG,CAAC,QAAQ,uCAAuC,CACzF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,6BAA6B,CAAC,GAAG,CAAC,CAAC;AAChD,CAAC,CAAC"}
+{"version":3,"file":"backendClient.js","sourceRoot":"","sources":["../src/backendClient.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,6BAA6B,GAE9B,MAAM,oDAAoD,CAAC;AAE5D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAkBvC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAqB;IAErB,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC5C,EAAE,YAAY,EAAE,EAAE,EAAE,CACrB,CAAC;IAEF,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG;QAC1B,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,YAAY,CAAC;QACnE,CAAC,CAAC,IAAI,oBAAoB,CAAC;YACvB,OAAO,EAAE,MAAM,CAAC,OAAQ;YACxB,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE;SACxB,CAAC,CAAC;IAEP,qEAAqE;IACrE,uEAAuE;IACvE,8EAA8E;IAC9E,0EAA0E;IAC1E,MAAM,MAAM,CAAC,OAAO,CAAC,SAAsB,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,gBAAgB,GAAG,CACvB,SAAiB,EACjB,OAAgC,EAChC,YAAkC,EAClC,EAAE;IACF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,qCAAqC,GAAG,CAAC,QAAQ,uCAAuC,CACzF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAkD,EAAE,CAAC;IAC/D,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC,WAAW,GAAG,EAAE,OAAO,EAAE,CAAC;IACjC,CAAC;IACD,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IACD,OAAO,IAAI,6BAA6B,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACtD,CAAC,CAAC"}

package/dist/core.d.ts

@@ -1,13 +1,15 @@
 import * as http from 'node:http';
 import * as https from 'node:https';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { type ListToolsRequest, type ListToolsResult, type CallToolRequest, type CallToolResult, type CompatibilityCallToolResult, type ReadResourceRequest, type ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import { type ListToolsRequest, type ListToolsResult, type CallToolRequest, type CallToolRequestParams, type CallToolResult, type CompatibilityCallToolResult, type ContentBlock, type GetPromptRequest, type GetPromptResult, type TextContent, type ReadResourceRequest, type ReadResourceResult, type Tool } from '@modelcontextprotocol/sdk/types.js';
 import { type Middleware } from './middleware.js';
-import type { BackendClient } from './backendClient.js';
+import type { HiddenToolPredicate } from './hiddenTools.js';
+import { type ProxyContext } from './proxyContext.js';
 import type { Identity } from './identity.js';
 import type { TelemetryEvent } from './telemetry.js';
+import { type Backends } from './mesh.js';
+import { type SessionRegistry } from './sessionRegistry.js';
 import type { EventStore } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-export type { ProxyContext } from './proxyContext.js';
 /**
  * Middleware for tool calls.
  * Uses `CompatibilityCallToolResult` to cover legacy `{ toolResult }` shape
@@ -16,30 +18,103 @@ export type { ProxyContext } from './proxyContext.js';
 export type ToolMiddleware = Middleware<CallToolRequest, CompatibilityCallToolResult>;
 /** Middleware for resource reads. */
 export type ResourceMiddleware = Middleware<ReadResourceRequest, ReadResourceResult>;
+/** Middleware for prompt fetches (`prompts/get`). */
+export type PromptMiddleware = Middleware<GetPromptRequest, GetPromptResult>;
 /** Middleware for tool-list responses. */
 export type ListToolsMiddleware = Middleware<ListToolsRequest, ListToolsResult>;
 /**
- * Narrows `CompatibilityCallToolResult` to `CallToolResult` (has `.content` array).
- * Both union members carry `[x: string]: unknown`, so this avoids unsafe casts.
+ * The result channels of a `CallToolResult` — everything a redaction or
+ * transform middleware must account for:
+ *
+ * 1. `content` blocks (text, image, audio, resource link, embedded
+ *    resource), each carrying its own block-level `_meta`,
+ * 2. `structuredContent`, the machine-readable mirror of the content,
+ * 3. result-level `_meta`,
+ * 4. `isError`,
+ * 5. unknown extra keys via the index signature.
+ *
+ * Redaction that maps only `.content` misses 2, 3, and the non-text
+ * members of 1. Use {@link mapToolResult} to cover every payload channel
+ * by construction; channel 3 is stripped at the proxy boundary by default
+ * via `ProxyOptions.stripResultMeta` (ADR-0009).
+ *
+ * This guard narrows `CompatibilityCallToolResult` to `CallToolResult`
+ * (has `.content` array). Both union members carry `[x: string]: unknown`,
+ * so this avoids unsafe casts.
  */
 export declare function hasToolContent(r: CompatibilityCallToolResult): r is CallToolResult;
+/**
+ * Handlers for {@link mapToolResult}, one per payload channel. All three
+ * are required, so forgetting a channel is a compile error rather than a
+ * silent leak.
+ */
+export interface ToolResultHandlers {
+    /** Maps a text content block. Return `null` to drop the block. */
+    onText: (block: TextContent) => ContentBlock | null;
+    /**
+     * Maps a non-text content block (image, audio, resource link, embedded
+     * resource). Return `null` to drop the block.
+     */
+    onOther: (block: Exclude<ContentBlock, TextContent>) => ContentBlock | null;
+    /**
+     * Maps `structuredContent`. Called only when the field is present.
+     * Return `undefined` to remove the field entirely.
+     */
+    onStructured: (structured: Record<string, unknown>) => Record<string, unknown> | undefined;
+}
+/**
+ * Maps every payload channel of a tool result through the given handlers.
+ *
+ * The legacy `{ toolResult }` shape (protocol 2024-10-07) is returned
+ * untouched. `isError`, result-level `_meta`, and unknown extra keys are
+ * preserved by spread — result-level `_meta` needs no handler because the
+ * proxy strips it by default (`stripResultMeta`, ADR-0009); with
+ * `stripResultMeta: false` forwarding it is the consumer's explicit choice.
+ */
+export declare function mapToolResult(result: CompatibilityCallToolResult, handlers: ToolResultHandlers): CompatibilityCallToolResult;
 /** HTTP transport options for {@link startHttpProxy}. */
 export interface HttpProxyOptions {
     /** Default: 3000 */
     port?: number;
-    /** Default: all interfaces */
+    /**
+     * Bind address. Default: `'127.0.0.1'` (loopback).
+     *
+     * Binding a non-loopback address (e.g. `'0.0.0.0'`) exposes an
+     * unauthenticated MCP proxy holding an authenticated upstream session to
+     * the network, so it is a deliberate opt-in; doing so without
+     * {@link resolveIdentity} reports a startup warning through {@link onError}.
+     */
     host?: string;
     /** Default: '/mcp' */
     path?: string;
-    /** Called for every incoming request before MCP handling. Return false to block (caller writes its own response). Throw to get a 401. */
+    /**
+     * Called for every incoming request before MCP handling. Return false to
+     * block (caller writes its own response). Throw to get a 401, with the error
+     * reported through {@link onError}.
+     */
     onRequest?: (req: http.IncomingMessage, res: http.ServerResponse) => boolean | Promise<boolean>;
-    /** Called on unhandled errors instead of console.error. */
+    /**
+     * Called on unhandled errors instead of console.error, and on every auth
+     * hook that throws: the request still fails closed, and the operator still
+     * sees why.
+     */
     onError?: (err: unknown) => void;
     /** Maximum request body size in bytes. Default: 4 MB. */
     maxBodyBytes?: number;
-    /** Maximum number of concurrent MCP sessions. Excess requests return 503. */
+    /**
+     * Maximum number of concurrent MCP sessions. Excess requests return 503.
+     * Default: 1000. Set to `Infinity` to opt out of the cap.
+     *
+     * `0` is a valid value and means "reject every session", so it is not the
+     * opt-out.
+     */
     maxSessions?: number;
-    /** Session TTL in milliseconds. Sessions are closed after this duration. */
+    /**
+     * Session TTL in milliseconds. Sessions are closed after this duration,
+     * which fires {@link onSessionClosed}. Default: 30 minutes. Finite values
+     * must not exceed Node's maximum timer delay of 2,147,483,647 ms. Set to
+     * `Infinity` to opt out of the TTL.
+     */
     sessionTtlMs?: number;
     /**
      * Resolves caller identity from the initial session request.
@@ -48,7 +123,7 @@ export interface HttpProxyOptions {
      *
      * Supply a JWT extractor, mTLS cert reader, API-key lookup, or any async
      * function returning an {@link Identity}. Errors thrown here abort the
-     * session with a 401.
+     * session with a 401 and are reported through {@link onError}.
      *
      * @example
      * resolveIdentity: extractJwtIdentity({ jwksUri: '...' })
@@ -73,21 +148,118 @@ export interface HttpProxyOptions {
      * (suitable for single-instance deployments). For multi-instance / HA
      * deployments, supply a Redis or Postgres-backed implementation.
      *
+     * Stream ids reach the store namespaced as `<sessionId>:<streamId>`, so
+     * one store serves every session without their replay histories mixing.
+     *
      * Set to `null` to disable reconnect replay entirely.
      */
     eventStore?: EventStore | null;
     /**
-     * Called when a session is closed (client DELETE or TTL expiry).
-     * Wire {@link AuditMiddlewareHandle.closeSession} here to flush the
-     * ReplayManifest for the session.
+     * Shared record of live sessions, so a client can resume after a proxy
+     * restart or on another instance behind a load balancer. Without one,
+     * sessions live only in this process and a resume against a fresh process
+     * is a 404.
+     *
+     * A record is written before the initialize response goes out and read
+     * only for an `mcp-session-id` this instance does not hold; the resumed
+     * session negotiates what the original did, keeps its identity, and dies
+     * at the original deadline. Client DELETE and TTL expiry delete the
+     * record, server shutdown keeps it. Pair it with the matching
+     * {@link eventStore} adapter, or a resumed session has no replay history.
+     *
+     * @example
+     * sessionRegistry: createRedisSessionRegistry(redis),
+     * eventStore: createRedisEventStore(redis),
+     */
+    sessionRegistry?: SessionRegistry;
+    /**
+     * Called when a session is closed (client DELETE, TTL expiry, or server
+     * shutdown). Wire {@link AuditMiddlewareHandle.closeSession} here to flush
+     * the ReplayManifest for the session.
+     *
+     * A returned promise is awaited: `server.close()` does not complete until
+     * every session's hook has settled, so a host that exits in the close
+     * callback never loses a final manifest. A throw or a rejection is routed
+     * to {@link onError} and never breaks teardown.
      *
      * @example
      * onSessionClosed: (sessionId) => auditHandle.closeSession(sessionId)
      */
-    onSessionClosed?: (sessionId: string) => void;
+    onSessionClosed?: (sessionId: string) => unknown;
+    /**
+     * Re-validates an existing session on every routed request. Return `false`
+     * (or throw, which is reported through {@link onError}) to reject with 401.
+     * Use to bind sessions to their original credential — e.g. re-check the
+     * bearer token — so a leaked `mcp-session-id` alone cannot take over a
+     * session.
+     */
+    validateSession?: (req: http.IncomingMessage, session: {
+        sessionId: string;
+        identity?: Identity;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Hosts allowed in the `Host` header when
+     * {@link enableDnsRebindingProtection} is on. Forwarded to the SDK
+     * transport, which only validates against a non-empty list.
+     *
+     * Default: for a loopback bind, derived from the effective bind address
+     * and the real listening port (`127.0.0.1:<port>`, `localhost:<port>`,
+     * `[::1]:<port>`). An explicit value is used verbatim, never merged with
+     * the derived list. No list is derived for a non-loopback bind.
+     */
+    allowedHosts?: string[];
+    /**
+     * Origins allowed in the `Origin` header. Forwarded to the SDK transport,
+     * which only validates against a non-empty list.
+     *
+     * Default: for a loopback bind, the derived {@link allowedHosts} entries
+     * as origins (`http://` or `https://` matching {@link tlsOptions}). An
+     * explicit value is used verbatim, never merged.
+     */
+    allowedOrigins?: string[];
+    /**
+     * Enables the SDK transport's DNS-rebinding protection (Host/Origin
+     * checks). Default: `true` when the effective bind address is loopback,
+     * `false` otherwise (a non-loopback bind usually sits behind a gateway
+     * that rewrites `Host`).
+     *
+     * Enabling this on a non-loopback bind without explicit
+     * {@link allowedHosts} / {@link allowedOrigins} validates nothing and
+     * reports a startup warning through {@link onError}.
+     */
+    enableDnsRebindingProtection?: boolean;
+}
+/**
+ * A tool the proxy implements itself, instead of forwarding to the
+ * upstream. See ADR-0007.
+ */
+export interface LocalTool {
+    /** The tool definition advertised in `tools/list`. */
+    tool: Tool;
+    /**
+     * Runs instead of the upstream call, from inside the innermost `next`,
+     * so the whole `toolMiddleware` pipeline (audit, redaction) still
+     * applies.
+     */
+    handler: (params: CallToolRequestParams, context: ProxyContext) => Promise<CallToolResult>;
 }
 /** Proxy server options. */
 export interface ProxyOptions {
+    /**
+     * Human-readable name for this proxy instance. Required, and rejected at
+     * construction when empty or whitespace-only.
+     *
+     * It is stamped onto every `ProxyContext`, every audit event, and the
+     * `ReplayManifest` as provenance (ADR-0012), so a default would record a
+     * whole fleet under one name: attribution in appearance only (#122).
+     */
+    name: string;
+    /**
+     * Version of this proxy server (yours, not the mcpose library). MCP clients see
+     * it in the `initialize` response. Defaults to the mcpose library version when
+     * omitted; set it to your own release version when you ship your proxy.
+     */
+    version?: string;
     /**
      * Tool middleware in response-processing order (first = innermost).
      * @example [piiMW, auditMW]  // pii redacts first, audit logs clean data
@@ -95,20 +267,110 @@ export interface ProxyOptions {
     toolMiddleware?: ReadonlyArray<ToolMiddleware>;
     /** Resource middleware in response-processing order (first = innermost). */
     resourceMiddleware?: ReadonlyArray<ResourceMiddleware>;
+    /**
+     * Prompt middleware in response-processing order (first = innermost),
+     * per ADR-0002. Runs around every `prompts/get`, in both 1:1 and mesh
+     * mode.
+     *
+     * Mesh routing and the `BACKEND_UNROUTABLE` rejection for an unroutable
+     * prompt name happen inside the innermost `next` (the ADR-0007 pattern),
+     * so an observing middleware such as audit records every prompt call
+     * including the rejected ones.
+     *
+     * `prompts/list` has no pipeline yet; hiding and pass-through for prompts
+     * are deferred with it (ADR-0014).
+     */
+    promptMiddleware?: ReadonlyArray<PromptMiddleware>;
     /** Tool-list middleware in response-processing order (first = innermost). */
     listToolsMiddleware?: ReadonlyArray<ListToolsMiddleware>;
-    /** Tools that skip middleware — upstream response forwarded as-is. */
+    /**
+     * Tools that skip transforming middleware — upstream response forwarded
+     * as-is. Middleware wrapped in `markPassThroughObserver()` (e.g. audit)
+     * still runs for these tools.
+     */
     passThroughTools?: ReadonlyArray<string>;
-    /** Resources that skip middleware — upstream response forwarded as-is. */
+    /**
+     * Resources that skip middleware — upstream response forwarded as-is.
+     * Matched against the URI the client sees, which in mesh mode is
+     * `mcpose://<backendKey>/<uri>` (ADR-0022).
+     */
     passThroughResources?: ReadonlyArray<string>;
-    /** Tools hidden from list_tools and rejected at runtime with MethodNotFound. */
-    hiddenTools?: ReadonlyArray<string>;
-    /** Resources hidden from list_resources and rejected at runtime with InvalidRequest. */
+    /**
+     * Tools hidden from list_tools and rejected at runtime with
+     * MethodNotFound. Precedence: a tool listed here AND in
+     * `passThroughTools` stays hidden. Hidden filtering is applied both
+     * before and after `listToolsMiddleware`, so list middleware cannot
+     * re-expose a hidden tool.
+     *
+     * A name array cannot see through a dispatcher (meta-tool) that takes
+     * the real tool name as an argument. Pass a {@link HiddenToolPredicate}
+     * (e.g. {@link dispatcherAwareBlock}) to close that bypass: it receives
+     * `undefined` args during list filtering and always an object at call
+     * time. See ADR-0006.
+     */
+    hiddenTools?: ReadonlyArray<string> | HiddenToolPredicate;
+    /**
+     * Resources hidden from list_resources and rejected at runtime with
+     * InvalidRequest. Matched against the URI the client sees, which in mesh
+     * mode is `mcpose://<backendKey>/<uri>` (ADR-0022).
+     */
     hiddenResources?: ReadonlyArray<string>;
     /**
-     * Called after every tool call with timing and outcome data.
-     * Wire to {@link https://www.npmjs.com/package/@mcpose/otel | @mcpose/otel}
-     * or any custom telemetry sink.
+     * Strips `params._meta` from every request the proxy forwards (tool
+     * calls, resource reads, list and prompt calls). Default: `true`.
+     *
+     * MCP clients put correlation identifiers there (VS Code sends
+     * `progressToken`, a W3C `traceparent`, and `vscode/conversationId`),
+     * and the upstream is frequently a third party. The strip happens at the
+     * proxy boundary, before the pipeline, so middleware sees the stripped
+     * request and can still add its own `_meta` deliberately. Progress relay
+     * is unaffected: the proxy reads the client's progress token from the
+     * server-side request `extra`, and the SDK client stamps its own token
+     * on the upstream request.
+     *
+     * Applies to `passThroughTools` too; disable only globally with `false`
+     * for upstreams that read other `_meta` keys. See ADR-0008.
+     */
+    stripRequestMeta?: boolean;
+    /**
+     * Strips top-level `_meta` from every result the proxy returns from the
+     * upstream (tool calls, resource reads, list and prompt calls).
+     * Default: `true`.
+     *
+     * The response-direction mirror of {@link stripRequestMeta}: upstreams
+     * stamp correlation identifiers there (the SDK stamps
+     * `io.modelcontextprotocol/related-task`), and the client is a third
+     * party to them. The strip happens at the upstream boundary, inside the
+     * innermost `next`, so middleware sees the stripped result and any
+     * `_meta` middleware adds deliberately still reaches the client.
+     *
+     * Local tool results are not stripped (they have no upstream), and
+     * nested `_meta` (per-tool in `tools[]`, per-block in `content`) is
+     * untouched. Applies to pass-through tools and resources too; disable
+     * only globally with `false`. See ADR-0009.
+     */
+    stripResultMeta?: boolean;
+    /**
+     * Tools the proxy implements itself. Local tools appear in `tools/list`
+     * (first page only, so pagination does not duplicate them) and route to
+     * their handler instead of the upstream, from inside the innermost
+     * `next`, so the full `toolMiddleware` pipeline still runs.
+     *
+     * Precedence: `hiddenTools` beats a local tool; a local tool beats (and
+     * shadows) an upstream tool of the same name; `passThroughTools` has no
+     * effect on a local tool, because pass-through means "forward the
+     * upstream response as-is" and a local tool has no upstream.
+     *
+     * The proxy advertises the `tools` capability when this is non-empty
+     * even if the upstream has none. A duplicate local tool name throws at
+     * {@link createProxyServer}. See ADR-0007.
+     */
+    localTools?: ReadonlyArray<LocalTool>;
+    /**
+     * Called after every tool call with timing and outcome data. Wire to any
+     * custom telemetry sink, or to `createOtelTelemetry` from `@mcpose/otel`
+     * for OpenTelemetry spans.
+     * A throwing sink is logged and never fails the tool call.
      */
     onTelemetry?: (event: TelemetryEvent) => void;
 }
@@ -116,22 +378,25 @@ export interface ProxyOptions {
  * Creates a proxy MCP server without connecting it to a transport.
  *
  * Mirrors upstream tool/resource/prompt lists and routes requests through
- * middleware pipelines. Prompts are forwarded as-is.
+ * middleware pipelines. `prompts/list` is forwarded as-is; `prompts/get`
+ * runs `promptMiddleware` (ADR-0014).
  *
  * Uses low-level `Server` (not `McpServer`) — transparent proxying requires
  * generic list interception; `McpServer.tool()` needs names upfront.
  *
- * @param backend - Connected (or mock) upstream MCP client.
+ * @param backends - Connected (or mock) upstream MCP client for a 1:1 proxy,
+ * or a record of named backends for mesh mode (ADR-0013), where every
+ * upstream tool and prompt is exposed as `<backendKey>__<name>`.
  * @param options - Middleware stacks, hidden/passthrough sets.
  * @returns Configured {@link Server} ready to connect.
  */
-export declare function createProxyServer(backend: BackendClient, options?: ProxyOptions): Server;
+export declare function createProxyServer(backends: Backends, options: ProxyOptions): Server;
 /**
  * Starts the proxy on stdio.
  * Calls {@link createProxyServer} then connects to `StdioServerTransport`.
  * Use `createProxyServer` directly for testable access to the server.
  */
-export declare function startProxy(backend: BackendClient, options?: ProxyOptions): Promise<void>;
+export declare function startProxy(backends: Backends, options: ProxyOptions): Promise<void>;
 /**
  * Starts the proxy over Streamable HTTP with stateful sessions.
  *
@@ -143,5 +408,5 @@ export declare function startProxy(backend: BackendClient, options?: ProxyOption
  * @returns Promise resolving to the listening `http.Server` (or `https.Server`
  * when `tlsOptions` is supplied).
  */
-export declare function startHttpProxy(backend: BackendClient, options?: ProxyOptions, httpOptions?: HttpProxyOptions): Promise<http.Server>;
+export declare function startHttpProxy(backends: Backends, options: ProxyOptions, httpOptions?: HttpProxyOptions): Promise<http.Server>;
 //# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAEpC,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAInE,OAAO,EAML,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAMpB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAEvB,KAAK,IAAI,EAEV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAEV,cAAc,EAEf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAOL,KAAK,QAAQ,EAEd,MAAM,WAAW,CAAC;AAOnB,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oDAAoD,CAAC;AAKrF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,CACrC,eAAe,EACf,2BAA2B,CAC5B,CAAC;AAEF,qCAAqC;AACrC,MAAM,MAAM,kBAAkB,GAAG,UAAU,CACzC,mBAAmB,EACnB,kBAAkB,CACnB,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;AAE7E,0CAA0C;AAC1C,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,2BAA2B,GAC7B,CAAC,IAAI,cAAc,CAErB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,MAAM,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI,CAAC;IACpD;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE,WAAW,CAAC,KAAK,YAAY,GAAG,IAAI,CAAC;IAC5E;;;OAGG;IACH,YAAY,EAAE,CACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,2BAA2B,EACnC,QAAQ,EAAE,kBAAkB,GAC3B,2BAA2B,CAiB7B;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,CACV,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,KACrB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9E;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IACjC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAChB,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE,KAChD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,IAAI,EAAE,IAAI,CAAC;IACX;;;;OAIG;IACH,OAAO,EAAE,CACP,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,YAAY,KAClB,OAAO,CAAC,cAAc,CAAC,CAAC;CAC9B;AAED,4BAA4B;AAC5B,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAE/C,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAEvD;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAEnD,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAEzD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEzC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAE7C;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,mBAAmB,CAAC;IAE1D;;;;OAIG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC/C;AAgXD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,YAAY,GACpB,MAAM,CAqgBR;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAGf;AAqFD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,YAAY,EACrB,WAAW,GAAE,gBAAqB,GACjC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CA6gBtB"}