@orkestrel/mcp 0.0.35 → 0.0.36

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

@@ -2297,6 +2297,8 @@ export declare const JSONRPC_PARSE_ERROR = -32700;
  * Retained for the legacy branch alone. A modern fault answers
  * {@link JSONRPC_INTERNAL_ERROR}; this code survives only where an old-wire peer was
  * already characterized against it.
+ * A `handshake` hook that rejects with an `MCPError` answers the legacy `initialize`
+ * with that error's own code and data.
  */
 export declare const JSONRPC_SERVER_ERROR = -32000;
 
@@ -3466,6 +3468,19 @@ export declare interface MCPExecutionContext {
 /** Executes one canonical tool call or returns a fully formed complete MCP result. */
 export declare type MCPExecutionHandler = (context: MCPExecutionContext) => ToolResult | MCPCallResult | Promise<ToolResult | MCPCallResult>;
 
+/**
+ * Gates a legacy `initialize` response on consumer readiness.
+ *
+ * @remarks
+ * Only legacy initialization awaits this hook. An `MCPError` rejection preserves its
+ * code, message, and context; another rejection emits `error` and answers `Server error`.
+ * Observe `options.signal` to stop when the request ends.
+ *
+ * @param options - The resolved request lifetime and optional caller context
+ * @returns Completion when initialization may answer
+ */
+export declare type MCPHandshakeHandler = (options: MCPMethodOptions) => Promise<void>;
+
 /**
  * Represents one `x-mcp-header` projection a tool's `inputSchema` declares.
  *
@@ -3758,6 +3773,8 @@ export declare interface MCPLegacyOptions {
     readonly dispatcher: MCPDispatcherInterface;
     /** Holds the identity returned by the legacy `initialize` handshake. */
     readonly identity: MCPIdentity;
+    /** Holds the optional readiness hook awaited before the initialization result. */
+    readonly handshake?: MCPHandshakeHandler;
 }
 
 /**
@@ -4668,6 +4685,7 @@ export declare class MCPServer implements MCPServerInterface {
     constructor(options: MCPServerOptions);
     get emitter(): EmitterInterface<MCPServerEventMap>;
     get identity(): MCPIdentity;
+    get handshake(): MCPHandshakeHandler | undefined;
     get methods(): MCPMethodManagerInterface;
     get limit(): Required<MCPLimitOptions>;
     dispatch(request: JSONRPCRequest, options?: MCPDispatchOptions): Promise<JSONRPCResponse | MCPStreamControllerInterface>;
@@ -4782,6 +4800,8 @@ export declare type MCPServerEventMap = {
  */
 export declare interface MCPServerInterface extends MCPDispatcherInterface {
     readonly identity: MCPIdentity;
+    /** Holds the readiness hook consumed by the legacy decorator. */
+    readonly handshake: MCPHandshakeHandler | undefined;
     /** Holds the modern method registry this server dispatches through (built-ins included). */
     readonly methods: MCPMethodManagerInterface;
     /**
@@ -4865,6 +4885,9 @@ export declare interface MCPServerInterface extends MCPDispatcherInterface {
  *
  * @remarks
  * `identity` identifies the server in the `initialize` handshake (`serverInfo`).
+ * `handshake` is the optional readiness hook that the legacy decorator awaits before
+ * answering `initialize`; it receives the request signal and optional caller context.
+ * The hook must observe the signal to stop pending work. Other methods do not await it.
  * `tools` is the live registry the server dispatches `tools/list` / `tools/call`
  * over — its `definitions()` advertise the tools and its `execute()` runs a call
  * (the manager already isolates a tool throw into a `success: false` result, so
@@ -4891,6 +4914,8 @@ export declare interface MCPServerOptions {
     /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
     readonly identity: MCPIdentity;
+    /** Holds the optional readiness hook awaited only by legacy initialization. */
+    readonly handshake?: MCPHandshakeHandler;
     /** Holds the live tool registry the server exposes over `tools/list` / `tools/call`. */
     readonly tools: ToolManagerInterface;
     /**

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

@@ -2297,6 +2297,8 @@ export declare const JSONRPC_PARSE_ERROR = -32700;
  * Retained for the legacy branch alone. A modern fault answers
  * {@link JSONRPC_INTERNAL_ERROR}; this code survives only where an old-wire peer was
  * already characterized against it.
+ * A `handshake` hook that rejects with an `MCPError` answers the legacy `initialize`
+ * with that error's own code and data.
  */
 export declare const JSONRPC_SERVER_ERROR = -32000;
 
@@ -3466,6 +3468,19 @@ export declare interface MCPExecutionContext {
 /** Executes one canonical tool call or returns a fully formed complete MCP result. */
 export declare type MCPExecutionHandler = (context: MCPExecutionContext) => ToolResult | MCPCallResult | Promise<ToolResult | MCPCallResult>;
 
+/**
+ * Gates a legacy `initialize` response on consumer readiness.
+ *
+ * @remarks
+ * Only legacy initialization awaits this hook. An `MCPError` rejection preserves its
+ * code, message, and context; another rejection emits `error` and answers `Server error`.
+ * Observe `options.signal` to stop when the request ends.
+ *
+ * @param options - The resolved request lifetime and optional caller context
+ * @returns Completion when initialization may answer
+ */
+export declare type MCPHandshakeHandler = (options: MCPMethodOptions) => Promise<void>;
+
 /**
  * Represents one `x-mcp-header` projection a tool's `inputSchema` declares.
  *
@@ -3758,6 +3773,8 @@ export declare interface MCPLegacyOptions {
     readonly dispatcher: MCPDispatcherInterface;
     /** Holds the identity returned by the legacy `initialize` handshake. */
     readonly identity: MCPIdentity;
+    /** Holds the optional readiness hook awaited before the initialization result. */
+    readonly handshake?: MCPHandshakeHandler;
 }
 
 /**
@@ -4668,6 +4685,7 @@ export declare class MCPServer implements MCPServerInterface {
     constructor(options: MCPServerOptions);
     get emitter(): EmitterInterface<MCPServerEventMap>;
     get identity(): MCPIdentity;
+    get handshake(): MCPHandshakeHandler | undefined;
     get methods(): MCPMethodManagerInterface;
     get limit(): Required<MCPLimitOptions>;
     dispatch(request: JSONRPCRequest, options?: MCPDispatchOptions): Promise<JSONRPCResponse | MCPStreamControllerInterface>;
@@ -4782,6 +4800,8 @@ export declare type MCPServerEventMap = {
  */
 export declare interface MCPServerInterface extends MCPDispatcherInterface {
     readonly identity: MCPIdentity;
+    /** Holds the readiness hook consumed by the legacy decorator. */
+    readonly handshake: MCPHandshakeHandler | undefined;
     /** Holds the modern method registry this server dispatches through (built-ins included). */
     readonly methods: MCPMethodManagerInterface;
     /**
@@ -4865,6 +4885,9 @@ export declare interface MCPServerInterface extends MCPDispatcherInterface {
  *
  * @remarks
  * `identity` identifies the server in the `initialize` handshake (`serverInfo`).
+ * `handshake` is the optional readiness hook that the legacy decorator awaits before
+ * answering `initialize`; it receives the request signal and optional caller context.
+ * The hook must observe the signal to stop pending work. Other methods do not await it.
  * `tools` is the live registry the server dispatches `tools/list` / `tools/call`
  * over — its `definitions()` advertise the tools and its `execute()` runs a call
  * (the manager already isolates a tool throw into a `success: false` result, so
@@ -4891,6 +4914,8 @@ export declare interface MCPServerOptions {
     /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
     readonly identity: MCPIdentity;
+    /** Holds the optional readiness hook awaited only by legacy initialization. */
+    readonly handshake?: MCPHandshakeHandler;
     /** Holds the live tool registry the server exposes over `tools/list` / `tools/call`. */
     readonly tools: ToolManagerInterface;
     /**

package/dist/src/core/index.js

@@ -248,6 +248,8 @@ var JSONRPC_INTERNAL_ERROR = -32603;
 * Retained for the legacy branch alone. A modern fault answers
 * {@link JSONRPC_INTERNAL_ERROR}; this code survives only where an old-wire peer was
 * already characterized against it.
+* A `handshake` hook that rejects with an `MCPError` answers the legacy `initialize`
+* with that error's own code and data.
 */
 var JSONRPC_SERVER_ERROR = -32e3;
 /**
@@ -4751,6 +4753,23 @@ var MCPLegacy = class {
 		}) === void 0) return buildJSONRPCError(void 0, JSONRPC_INVALID_REQUEST, "Invalid Request");
 		switch (invocation.method) {
 			case "initialize": {
+				if (this.#options.handshake !== void 0) {
+					const closure = new AbortController();
+					const resolved = buildMethodOptions(options ?? {}, closure.signal);
+					try {
+						await this.#options.handshake(resolved);
+					} catch (error) {
+						if (resolved.signal.aborted) throw error;
+						if (isMCPError(error)) {
+							const context = attempt(() => parseJSON(JSON.stringify(error.context)));
+							return buildJSONRPCError(id, error.code, error.message, context.success ? context.value : void 0);
+						}
+						this.emitter.emit("error", error);
+						return buildJSONRPCError(id, JSONRPC_INTERNAL_ERROR, "Server error");
+					} finally {
+						closure.abort();
+					}
+				}
 				const requested = invocation.params?.["protocolVersion"];
 				return buildJSONRPCResult(id, buildInitializeResult(this.#options.identity.name, this.#options.identity.version, isString(requested) ? requested : void 0));
 			}
@@ -5110,6 +5129,9 @@ var MCPServer = class {
 	get identity() {
 		return this.#options.identity;
 	}
+	get handshake() {
+		return this.#options.handshake;
+	}
 	get methods() {
 		return this.#methods;
 	}
@@ -6752,7 +6774,8 @@ function createMCPServer(options) {
 function createMCPLegacy(server) {
 	return new MCPLegacy({
 		dispatcher: server,
-		identity: server.identity
+		identity: server.identity,
+		...server.handshake === void 0 ? {} : { handshake: server.handshake }
 	});
 }
 /**