@orkestrel/mcp 0.0.30 → 0.0.31

package/dist/src/core/index.cjs

@@ -275,9 +275,12 @@ var DEFAULT_MCP_SUBSCRIPTION_CAPACITY = 64;
 * optional structured context.
 *
 * @remarks
-* {@link MCPClient} throws this error for a remote JSON-RPC `error` response and for a
-* locally detected protocol incompatibility. Local lifecycle and transport conditions such
-* as disconnects and request timeouts remain plain `Error`s. For a remote response, `context`
+* {@link MCPClient} throws this error for a remote JSON-RPC `error` response, for a locally
+* detected protocol incompatibility, and for a session-bound request refused because the
+* client holds no connection — that one carries `-32600`, so a caller separates "reconnect"
+* from "retry" without reading a message. Local lifecycle and transport conditions that
+* settle a request already in flight, such as a disconnect and a request timeout, remain
+* plain `Error`s. For a remote response, `context`
 * carries the optional `error.data` unchanged and is `undefined` when the peer omitted it.
 * This includes the modern reserved paths: `-32020` carries no context, `-32021` may carry
 * `requiredCapabilities`, and `-32022` carries the peer's `supported` revisions and
@@ -1128,19 +1131,17 @@ function buildCallOutcome(name, result) {
 * Builds the canonical Tool call for one validated MCP `tools/call` request.
 *
 * @param request - The original MCP request
-* @param caller - Optional consumer-asserted caller context
 * @param args - Optional once-validated modern arguments; omission retains legacy normalization
 * @returns The canonical call, or `undefined` when the name is invalid
 */
-function buildToolCall(request, caller, args) {
+function buildToolCall(request, args) {
 	const name = request.params?.["name"];
 	if (typeof name !== "string") return void 0;
 	const rawArguments = request.params?.["arguments"];
 	return {
 		id: String(request.id),
 		name,
-		arguments: args ?? ((0, _orkestrel_contract.isRecord)(rawArguments) ? rawArguments : {}),
-		...caller === void 0 ? {} : { caller }
+		arguments: args ?? ((0, _orkestrel_contract.isRecord)(rawArguments) ? rawArguments : {})
 	};
 }
 /**
@@ -1231,7 +1232,8 @@ function buildMethodOptions(options, lifetime) {
 *
 * @remarks
 * Each {@link import('@orkestrel/tool').ToolDefinition} carries through its
-* `name` and (when present) `description`; its open JSON-Schema `parameters`
+* `name`, optional `title` and `description`, and mapped annotation hints;
+* its open JSON-Schema `parameters`
 * becomes `inputSchema`, defaulting to an empty object schema (`{ type: 'object' }`)
 * when a tool declares none (MCP requires an `inputSchema`).
 *
@@ -1240,14 +1242,50 @@ function buildMethodOptions(options, lifetime) {
 */
 function buildToolDescriptors(manager) {
 	return manager.definitions().map((definition) => {
-		const descriptor = {
+		const annotations = definition.annotations === void 0 ? {} : toolAnnotationsToMCP(definition.annotations);
+		return {
 			name: definition.name,
-			inputSchema: definition.parameters ?? { type: "object" }
+			inputSchema: definition.parameters ?? { type: "object" },
+			...definition.title === void 0 ? {} : { title: definition.title },
+			...definition.description === void 0 ? {} : { description: definition.description },
+			...Object.keys(annotations).length === 0 ? {} : { annotations }
 		};
-		if (definition.description !== void 0) descriptor.description = definition.description;
-		return descriptor;
 	});
 }
+/**
+* Projects domain tool annotations onto MCP wire hints without inventing defaults.
+*
+* @param annotations - The authored domain annotations
+* @returns The mapped hints; `untrusted` has no MCP counterpart
+*
+* @example
+* ```ts
+* toolAnnotationsToMCP({ pure: true, consequential: false }) // { readOnlyHint: true, destructiveHint: false }
+* ```
+*/
+function toolAnnotationsToMCP(annotations) {
+	return {
+		...annotations.pure === void 0 ? {} : { readOnlyHint: annotations.pure },
+		...annotations.consequential === void 0 ? {} : { destructiveHint: annotations.consequential }
+	};
+}
+/**
+* Projects MCP wire hints onto domain tool annotations without inventing defaults.
+*
+* @param annotations - The validated MCP wire annotations
+* @returns The mapped annotations; unmapped wire hints are omitted
+*
+* @example
+* ```ts
+* mcpAnnotationsToTool({ readOnlyHint: false, destructiveHint: true }) // { pure: false, consequential: true }
+* ```
+*/
+function mcpAnnotationsToTool(annotations) {
+	return {
+		...annotations.readOnlyHint === void 0 ? {} : { pure: annotations.readOnlyHint },
+		...annotations.destructiveHint === void 0 ? {} : { consequential: annotations.destructiveHint }
+	};
+}
 function buildModernResult(result, identity, ttl, scope) {
 	const currentMetadata = (0, _orkestrel_contract.isRecord)(result) ? result["_meta"] : void 0;
 	if (!(0, _orkestrel_contract.isJSONValue)(identity)) throw new TypeError("MCP identity must be exact JSON");
@@ -1452,10 +1490,11 @@ function buildSubscriptionResult(id, identity) {
 * @remarks
 * `capabilities.resources` and `capabilities.prompts` appear only for servers with their
 * respective managers and derive notification flags from the configured subscription filter.
-* `capabilities.completions` is independent and appears only with a completion provider.
-* `capabilities.extensions` appears only for a server that configured the extension it
-* would name. An advertisement is a promise a client is entitled to act on, so a server
-* with no `task` policy omits the member entirely rather than advertising an empty
+* `tools.listChanged` is always advertised because the server produces the family from its
+* own registry. `capabilities.completions` is independent and appears only with a completion
+* provider. `capabilities.extensions` appears only for a server that configured the
+* extension it would name. An advertisement is a promise a client is entitled to act on, so
+* a server with no `task` policy omits the member entirely rather than advertising an empty
 * record — and its discovery answer stays byte-for-byte what it was before the extension
 * existed.
 *
@@ -1466,7 +1505,7 @@ function buildDiscoverResult(options) {
 	return buildModernResult({
 		supportedVersions: SUPPORTED_MODERN_PROTOCOL_VERSIONS,
 		capabilities: {
-			tools: {},
+			tools: { listChanged: true },
 			...options.resources === void 0 ? {} : { resources: {
 				...options.subscription?.notifications.resourceSubscriptions === void 0 ? {} : { subscribe: true },
 				...options.subscription?.notifications.resourcesListChanged === true ? { listChanged: true } : {}
@@ -2665,6 +2704,28 @@ function isMCPResource(value) {
 	}
 }
 /**
+* Checks whether a value carries valid consumed MCP 2026-07-28 tool annotation hints.
+*
+* @remarks
+* Validates only `readOnlyHint` and `destructiveHint`; other wire fields are not consumed, so
+* the open `objectOf` combinator carries them through unread. Every declared member is
+* optional, a hostile read answers `false` rather than throwing, and an array is refused.
+*
+* @param value - The unknown wire annotations
+* @returns True if consumed annotation fields are optional booleans; false otherwise
+*
+* @example
+* ```ts
+* isMCPToolAnnotations({ readOnlyHint: false }) // true
+* ```
+*/
+function isMCPToolAnnotations(value) {
+	return (0, _orkestrel_contract.objectOf)({
+		readOnlyHint: _orkestrel_contract.isBoolean,
+		destructiveHint: _orkestrel_contract.isBoolean
+	}, true)(value);
+}
+/**
 * Determines whether a value is one resource-template descriptor.
 *
 * @remarks
@@ -3273,6 +3334,22 @@ function isMCPSubscriptionFilter(value) {
 	return (0, _orkestrel_contract.isUndefined)(tasks) || (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(tasks);
 }
 /**
+* Checks whether a subscription filter leaves the built-in tools family to the server.
+*
+* @param value - The unknown value to inspect
+* @returns True if the filter is valid and does not claim tools changes; false otherwise
+*
+* @example
+* ```ts
+* isMCPConsumerFilter({ promptsListChanged: true }) // true
+* isMCPConsumerFilter({ toolsListChanged: true }) // false
+* ```
+*/
+function isMCPConsumerFilter(value) {
+	const owned = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.cloneJSONRecord)(value));
+	return owned.success && isMCPSubscriptionFilter(owned.value) && owned.value["toolsListChanged"] !== true;
+}
+/**
 * Determines whether a value is a graceful `subscriptions/listen` result.
 *
 * @param value - The unknown value to inspect
@@ -5015,6 +5092,7 @@ var MCPServer = class {
 	#limits;
 	#subscriptions = 0;
 	constructor(options) {
+		if (options.subscription !== void 0 && !isMCPConsumerFilter(options.subscription.notifications)) throw new MCPError("The consumer filter must be a valid filter that omits tools changes, because the server produces that family from its registry", JSONRPC_INVALID_PARAMS);
 		this.#emitter = new _orkestrel_emitter.Emitter({
 			...options.on !== void 0 ? { on: options.on } : {},
 			...options.error !== void 0 ? { error: options.error } : {}
@@ -5287,14 +5365,14 @@ var MCPServer = class {
 		const args = (0, _orkestrel_contract.isRecord)(rawArguments) ? rawArguments : EMPTY_MCP_ARGUMENTS;
 		const input = await this.#input(request, args, options);
 		if (input !== void 0) return input;
-		const call = buildToolCall(request, options.caller, args);
+		const call = buildToolCall(request, args);
 		if (call === void 0) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: a string `name` is required");
 		const deferred = await this.#defer(request, call, options);
 		if (deferred !== void 0) return deferred;
 		const token = params?.["_meta"];
 		const progressToken = (0, _orkestrel_contract.isRecord)(token) ? token["progressToken"] : void 0;
 		if (this.#options.execution !== void 0 && ((0, _orkestrel_contract.isString)(progressToken) || typeof progressToken === "number" && Number.isInteger(progressToken))) return this.#progress(request, call, progressToken, options);
-		const result = await this.#execute(request, call, options.signal);
+		const result = await this.#execute(request, call, options);
 		return "jsonrpc" in result ? result : buildJSONRPCResult(id, result);
 	}
 	async #defer(request, call, options) {
@@ -5338,7 +5416,7 @@ var MCPServer = class {
 			keys: this.#limits.keys,
 			depth: this.#limits.depth
 		}, signal);
-		const execution = this.#execute(request, call, signal, reporter);
+		const execution = this.#execute(request, call, options, reporter);
 		try {
 			while (true) {
 				const outcome = await Promise.race([reporter.take(), execution]);
@@ -5356,14 +5434,19 @@ var MCPServer = class {
 			reporter.stop();
 		}
 	}
-	async #execute(request, call, signal, progress) {
+	async #execute(request, call, options, progress) {
+		const { signal, caller } = options;
 		let result;
 		try {
-			result = this.#options.execution === void 0 ? await this.#options.tools.execute(call) : await this.#options.execution({
+			result = this.#options.execution === void 0 ? await this.#options.tools.execute(call, {
+				signal,
+				...caller === void 0 ? {} : { caller }
+			}) : await this.#options.execution({
 				request,
 				call,
 				tools: this.#options.tools,
 				signal,
+				...caller === void 0 ? {} : { caller },
 				...progress === void 0 ? {} : { progress }
 			});
 		} catch (error) {
@@ -5551,7 +5634,10 @@ var MCPServer = class {
 			const task = this.#options.task;
 			const configured = this.#options.subscription;
 			const tasks = task !== void 0 && configured !== void 0;
-			let notifications = buildSubscriptionFilter(requested, configured?.notifications ?? {}, tasks);
+			let notifications = buildSubscriptionFilter(requested, {
+				...configured?.notifications,
+				toolsListChanged: true
+			}, tasks);
 			const requestedTaskIds = notifications.taskIds;
 			if (requestedTaskIds !== void 0) {
 				const resolved = [];
@@ -5564,19 +5650,22 @@ var MCPServer = class {
 					taskIds: resolved
 				} : rest;
 			}
+			const state = {
+				frame: void 0,
+				failure: void 0,
+				iterator: void 0
+			};
+			const source = new ReadableStream({
+				start: this.#startSubscription.bind(this, notifications, options, configured, state),
+				pull: this.#pullSubscription.bind(this, notifications, options, state)
+			});
 			yield buildSubscriptionAcknowledgement(notifications, id);
-			if (configured !== void 0) {
-				const iterator = (await configured.producer(notifications, options))[Symbol.asyncIterator]();
-				options.signal.addEventListener("abort", () => void iterator.return?.(void 0)?.catch(() => void 0), { once: true });
-				for (let next = await iterator.next(); next.done !== true; next = await iterator.next()) {
-					const owned = parseJSONRPCMessage(next.value, {
-						bytes: this.#limits.message,
-						depth: this.#limits.depth
-					});
-					if (owned === void 0 || !isJSONRPCNotification(owned)) continue;
-					if (matchesSubscriptionNotification(owned, notifications)) yield stampSubscriptionNotification(owned, id);
-				}
+			for await (const notification of source) {
+				if (notification === void 0) continue;
+				if (notification === state.frame) state.frame = void 0;
+				yield stampSubscriptionNotification(notification, id);
 			}
+			if (state.failure !== void 0) throw state.failure.error;
 			return buildSubscriptionResult(id, this.#options.identity);
 		} catch (error) {
 			if (options.signal.aborted) throw error;
@@ -5585,6 +5674,72 @@ var MCPServer = class {
 			slot.abort();
 		}
 	}
+	async #startSubscription(notifications, options, configured, state, controller) {
+		const emitter = this.#options.tools.emitter;
+		const changed = this.#change.bind(this, controller, options.signal, state);
+		if (options.signal.aborted) {
+			controller.error(options.signal.reason);
+			return;
+		}
+		if (notifications.toolsListChanged === true && !emitter.destroyed) {
+			emitter.on("add", changed);
+			emitter.on("remove", changed);
+			emitter.on("clear", changed);
+		}
+		options.signal.addEventListener("abort", () => {
+			emitter.off("add", changed);
+			emitter.off("remove", changed);
+			emitter.off("clear", changed);
+			const iterator = state.iterator;
+			state.iterator = void 0;
+			if (iterator !== void 0) this.#releaseProducer(iterator, options.signal.reason);
+			controller.error(options.signal.reason);
+		}, { once: true });
+		try {
+			if (configured === void 0) return;
+			const iterator = (await configured.producer(notifications, options))[Symbol.asyncIterator]();
+			if (options.signal.aborted) this.#releaseProducer(iterator, options.signal.reason);
+			else state.iterator = iterator;
+		} catch (error) {
+			this.#failSubscription(state, options.signal, controller, error);
+		}
+	}
+	#change(controller, signal, state) {
+		if (signal.aborted || state.failure !== void 0 || state.frame !== void 0) return;
+		const notification = {
+			jsonrpc: "2.0",
+			method: "notifications/tools/list_changed"
+		};
+		state.frame = notification;
+		controller.enqueue(notification);
+	}
+	async #pullSubscription(notifications, options, state, controller) {
+		try {
+			if (options.signal.aborted) return;
+			const next = await state.iterator?.next();
+			if (options.signal.aborted) return;
+			if (next === void 0 || next.done === true) {
+				state.iterator = void 0;
+				if (notifications.toolsListChanged !== true) controller.close();
+				return;
+			}
+			const owned = parseJSONRPCMessage(next.value, {
+				bytes: this.#limits.message,
+				depth: this.#limits.depth
+			});
+			controller.enqueue(owned !== void 0 && isJSONRPCNotification(owned) && owned.method !== "notifications/tools/list_changed" && matchesSubscriptionNotification(owned, notifications) ? owned : void 0);
+		} catch (error) {
+			this.#failSubscription(state, options.signal, controller, error);
+		}
+	}
+	#failSubscription(state, signal, controller, error) {
+		if (signal.aborted) return;
+		state.failure = { error };
+		controller.close();
+	}
+	#releaseProducer(iterator, reason) {
+		iterator.return?.(reason)?.catch(() => void 0);
+	}
 	#readTaskId(request) {
 		const id = request.id;
 		const context = parseRequestContext(request, {
@@ -5952,9 +6107,11 @@ var MCPClient = class {
 	async *#openSubscription(notifications, signal, capacity) {
 		signal.throwIfAborted();
 		if (!(0, _orkestrel_contract.isInteger)(capacity) || capacity < 1) throw new MCPError("MCP subscription capacity must be a positive integer", JSONRPC_INVALID_PARAMS);
+		const method = "subscriptions/listen";
+		const opening = this.#refuse(method);
+		if (opening !== void 0) throw opening;
 		this.#nextId += 1;
 		const id = this.#nextId;
-		const method = "subscriptions/listen";
 		const modern = this.#version;
 		const request = {
 			jsonrpc: "2.0",
@@ -6002,7 +6159,16 @@ var MCPClient = class {
 			this.#cancelSubscription(id, /* @__PURE__ */ new Error("MCP subscription closed by its consumer"));
 		}
 	}
+	#refuse(method) {
+		if (method === "server/discover") return void 0;
+		if (this.#connected) return void 0;
+		const inflight = this.#connecting;
+		if (inflight !== void 0 && inflight.generation === this.#generation) return void 0;
+		return new MCPError(`MCP client is not connected, so '${method}' was not issued`, JSONRPC_INVALID_REQUEST);
+	}
 	#request(method, params, deadline, version, options) {
+		const refusal = this.#refuse(method);
+		if (refusal !== void 0) return Promise.reject(refusal);
 		this.#nextId += 1;
 		const id = this.#nextId;
 		const timeout = deadline;
@@ -6144,16 +6310,20 @@ var MCPClient = class {
 	#tool(name, descriptor) {
 		const inputSchema = descriptor["inputSchema"];
 		const description = descriptor["description"];
-		const options = {
+		const title = descriptor["title"];
+		const annotations = descriptor["annotations"];
+		const projected = isMCPToolAnnotations(annotations) ? mcpAnnotationsToTool(annotations) : {};
+		return new _orkestrel_tool.Tool({
 			name,
+			...(0, _orkestrel_contract.isString)(title) ? { title } : {},
+			...(0, _orkestrel_contract.isString)(description) ? { description } : {},
+			...(0, _orkestrel_contract.isRecord)(inputSchema) ? { parameters: inputSchema } : {},
+			...Object.keys(projected).length === 0 ? {} : { annotations: projected },
 			execute: this.#execute.bind(this, name)
-		};
-		if ((0, _orkestrel_contract.isString)(description)) options.description = description;
-		if ((0, _orkestrel_contract.isRecord)(inputSchema)) options.parameters = inputSchema;
-		return new _orkestrel_tool.Tool(options);
+		});
 	}
-	async #execute(name, args) {
-		const outcome = await this.call(name, args);
+	async #execute(name, args, context) {
+		const outcome = await this.call(name, args, { signal: context.signal });
 		if (outcome.resultType !== "complete") throw new Error(`MCP tool '${name}' answered '${outcome.resultType}' and has no inline value`);
 		return outcome.value;
 	}
@@ -6809,6 +6979,7 @@ exports.isMCPCompletion = isMCPCompletion;
 exports.isMCPCompletionParams = isMCPCompletionParams;
 exports.isMCPCompletionReference = isMCPCompletionReference;
 exports.isMCPCompletionResult = isMCPCompletionResult;
+exports.isMCPConsumerFilter = isMCPConsumerFilter;
 exports.isMCPContent = isMCPContent;
 exports.isMCPElicitFieldSchema = isMCPElicitFieldSchema;
 exports.isMCPElicitForm = isMCPElicitForm;
@@ -6859,6 +7030,7 @@ exports.isMCPTaskNotification = isMCPTaskNotification;
 exports.isMCPTaskResult = isMCPTaskResult;
 exports.isMCPTaskStatus = isMCPTaskStatus;
 exports.isMCPTextResource = isMCPTextResource;
+exports.isMCPToolAnnotations = isMCPToolAnnotations;
 exports.isMCPVersion = isMCPVersion;
 exports.isModernRequest = isModernRequest;
 exports.isRFC3339Date = isRFC3339Date;
@@ -6868,6 +7040,7 @@ exports.legacyInvocationToModern = legacyInvocationToModern;
 exports.legacyResultToModern = legacyResultToModern;
 exports.matchesResultType = matchesResultType;
 exports.matchesSubscriptionNotification = matchesSubscriptionNotification;
+exports.mcpAnnotationsToTool = mcpAnnotationsToTool;
 exports.modernInvocationToLegacy = modernInvocationToLegacy;
 exports.modernResultToLegacy = modernResultToLegacy;
 exports.parseJSONRPCMessage = parseJSONRPCMessage;
@@ -6883,5 +7056,6 @@ exports.snapshotToolResult = snapshotToolResult;
 exports.stampSubscriptionNotification = stampSubscriptionNotification;
 exports.supportsFormElicitation = supportsFormElicitation;
 exports.supportsTask = supportsTask;
+exports.toolAnnotationsToMCP = toolAnnotationsToMCP;
 
 //# sourceMappingURL=index.cjs.map