@orkestrel/mcp 0.0.9 → 0.0.11

package/dist/src/core/index.d.cts

@@ -1288,10 +1288,20 @@ export declare interface MCPDiscoverResult {
     readonly _meta?: Readonly<Record<string, unknown>>;
 }
 
-/** Per-request execution options every dispatched handler receives. */
+/**
+ * Per-request execution options every dispatched handler receives.
+ *
+ * @remarks
+ * `caller` is consumer-ASSERTED and NEVER VERIFIED. Sessions mint transport identity, not
+ * caller identity, and nothing in MCP authenticates this value. This package carries it
+ * opaquely without inspecting, validating, or serializing it. A consumer must narrow it with
+ * its own total guard and treat absence as unauthenticated.
+ */
 export declare interface MCPDispatchOptions {
     /** Aborts when the bound transport can observe that the caller's request has ended. */
     readonly signal?: AbortSignal;
+    /** Consumer-asserted caller context, forwarded opaquely and never protocol-verified. */
+    readonly caller?: unknown;
 }
 
 /** One consumer-requested form elicitation, before MCP assigns its map key and signs state. */
@@ -1437,7 +1447,8 @@ export declare interface MCPListResult {
  * @remarks
  * `undefined` answers nothing (the notification arm); an {@link MCPStream} holds the
  * request open. `options.signal` aborts when the caller's request ends — what a handler
- * does with it is the handler's decision, never this package's.
+ * does with it is the handler's decision, never this package's. `options.caller` is
+ * consumer-asserted and never verified by this package.
  *
  * @param request - The parsed modern request being dispatched
  * @param options - The per-request execution options (see {@link MCPDispatchOptions})
@@ -1503,8 +1514,14 @@ export declare interface MCPMethodManagerInterface {
     method(name: string): MCPMethodHandler | undefined;
 }
 
-/** Derive the deployment-authenticated principal bound into signed request state. */
-export declare type MCPPrincipalHandler = (request: JSONRPCRequest) => string | Promise<string>;
+/**
+ * Derive the deployment-authenticated principal bound into signed request state.
+ *
+ * @param request - The parsed `tools/call` request
+ * @param options - The per-request execution options
+ * @returns The authenticated principal to bind into protected state
+ */
+export declare type MCPPrincipalHandler = (request: JSONRPCRequest, options: MCPDispatchOptions) => string | Promise<string>;
 
 /**
  * The validated per-request context projected from a modern request's reserved

package/dist/src/core/index.d.ts

@@ -1288,10 +1288,20 @@ export declare interface MCPDiscoverResult {
     readonly _meta?: Readonly<Record<string, unknown>>;
 }
 
-/** Per-request execution options every dispatched handler receives. */
+/**
+ * Per-request execution options every dispatched handler receives.
+ *
+ * @remarks
+ * `caller` is consumer-ASSERTED and NEVER VERIFIED. Sessions mint transport identity, not
+ * caller identity, and nothing in MCP authenticates this value. This package carries it
+ * opaquely without inspecting, validating, or serializing it. A consumer must narrow it with
+ * its own total guard and treat absence as unauthenticated.
+ */
 export declare interface MCPDispatchOptions {
     /** Aborts when the bound transport can observe that the caller's request has ended. */
     readonly signal?: AbortSignal;
+    /** Consumer-asserted caller context, forwarded opaquely and never protocol-verified. */
+    readonly caller?: unknown;
 }
 
 /** One consumer-requested form elicitation, before MCP assigns its map key and signs state. */
@@ -1437,7 +1447,8 @@ export declare interface MCPListResult {
  * @remarks
  * `undefined` answers nothing (the notification arm); an {@link MCPStream} holds the
  * request open. `options.signal` aborts when the caller's request ends — what a handler
- * does with it is the handler's decision, never this package's.
+ * does with it is the handler's decision, never this package's. `options.caller` is
+ * consumer-asserted and never verified by this package.
  *
  * @param request - The parsed modern request being dispatched
  * @param options - The per-request execution options (see {@link MCPDispatchOptions})
@@ -1503,8 +1514,14 @@ export declare interface MCPMethodManagerInterface {
     method(name: string): MCPMethodHandler | undefined;
 }
 
-/** Derive the deployment-authenticated principal bound into signed request state. */
-export declare type MCPPrincipalHandler = (request: JSONRPCRequest) => string | Promise<string>;
+/**
+ * Derive the deployment-authenticated principal bound into signed request state.
+ *
+ * @param request - The parsed `tools/call` request
+ * @param options - The per-request execution options
+ * @returns The authenticated principal to bind into protected state
+ */
+export declare type MCPPrincipalHandler = (request: JSONRPCRequest, options: MCPDispatchOptions) => string | Promise<string>;
 
 /**
  * The validated per-request context projected from a modern request's reserved

package/dist/src/core/index.js

@@ -1382,7 +1382,7 @@ var MCPServer = class {
 			keys: this.#limits.keys,
 			depth: this.#limits.depth
 		})) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: `_meta` exceeds the configured limit or contains an unsafe value");
-		return modern ? this.#modern(request, id, options) : this.#legacy(request, id);
+		return modern ? this.#modern(request, id, options) : this.#legacy(request, id, options);
 	}
 	async handle(message, options) {
 		if (!isBoundedString(message, this.#limits.message)) return JSON.stringify(buildJSONRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"));
@@ -1398,7 +1398,7 @@ var MCPServer = class {
 		if (answer === void 0) return void 0;
 		return Symbol.asyncIterator in answer ? serializeStream(answer) : JSON.stringify(answer);
 	}
-	async #legacy(request, id) {
+	async #legacy(request, id, options) {
 		switch (request.method) {
 			case "initialize": {
 				const requested = request.params?.["protocolVersion"];
@@ -1407,7 +1407,7 @@ var MCPServer = class {
 			case "ping": return buildJSONRPCResult(id, {});
 			case "tools/list": return buildJSONRPCResult(id, { tools: buildToolDescriptors(this.#options.tools) });
 			case "tools/call": {
-				const result = await this.#runTool(request, id);
+				const result = await this.#runTool(request, id, options);
 				return "jsonrpc" in result ? result : buildJSONRPCResult(id, result);
 			}
 			default: return buildJSONRPCError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${request.method}`);
@@ -1440,7 +1440,7 @@ var MCPServer = class {
 		const id = request.id ?? null;
 		const input = await this.#input(request, options);
 		if (input !== void 0) return input;
-		const result = await this.#runTool(request, id);
+		const result = await this.#runTool(request, id, options);
 		return "jsonrpc" in result ? result : buildJSONRPCResult(id, buildModernResult(result, this.#options.identity));
 	}
 	async #input(request, options) {
@@ -1462,12 +1462,12 @@ var MCPServer = class {
 				arguments: args
 			}, options);
 			if (elicitation === void 0) return void 0;
-			const principal = await configured.principal(request);
+			const principal = await configured.principal(request, options);
 			return this.#required(request, name, elicitation, principal);
 		}
 		if (!isBoundedString(requestState, this.#limits.state) || !isRecord(inputResponses)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: `inputResponses` and `requestState` are required together");
 		const state = parseMCPInputState(await verifyToken(requestState, configured.secret));
-		const principal = await configured.principal(request);
+		const principal = await configured.principal(request, options);
 		if (state === void 0 || state.principal !== principal || state.ttl !== configured.ttl || state.origin === id || state.name !== name || !Object.hasOwn(inputResponses, state.key)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: request state could not be verified for this retry");
 		const response = inputResponses[state.key];
 		if (!isElicitResult(response)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: the elicitation response is missing or malformed");
@@ -1542,7 +1542,7 @@ var MCPServer = class {
 			this.#subscriptions -= 1;
 		}
 	}
-	async #runTool(request, id) {
+	async #runTool(request, id, options) {
 		const params = request.params;
 		const name = params?.["name"];
 		if (!isString(name)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: a string `name` is required");
@@ -1552,7 +1552,8 @@ var MCPServer = class {
 		const result = await this.#options.tools.execute({
 			id: callId,
 			name,
-			arguments: args
+			arguments: args,
+			...options.caller === void 0 ? {} : { caller: options.caller }
 		});
 		if (!result.success && !isBoundedString(result.error, this.#limits.content)) return buildJSONRPCError(id, JSONRPC_SERVER_ERROR, "Server limit exceeded: tool content is too large");
 		if (result.success && result.value !== void 0 && !isBoundedJSON(result.value, {