@warlock.js/ai-tools 5.30.0 → 5.32.0

package/esm/mcp/serve.mjs

@@ -1,4 +1,7 @@
-import { McpTransportError } from "../errors.mjs";
+import { McpServeError, McpTransportError } from "../errors.mjs";
+import { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from "./protocol.mjs";
+import { startHttpServer } from "./serve-http.mjs";
+import { assertMcpResult, isMcpResult, isRecord, looksLikeMcpResult, unwrapMcpResult } from "./result.mjs";
 import { extractJsonSchema } from "@warlock.js/ai";
 import { createInterface } from "node:readline";
 
@@ -9,59 +12,156 @@ const JSONRPC_VERSION = "2.0";
 const DEFAULT_SCHEMA_TARGET = "draft-2020-12";
 /** Default advertised server version when the caller omits one. */
 const DEFAULT_VERSION = "4.4.0";
-/** The MCP protocol version this server advertises in `initialize`. */
-const PROTOCOL_VERSION = "2025-06-18";
 /** JSON-RPC standard error codes we emit. */
 const JSON_RPC_METHOD_NOT_FOUND = -32601;
 const JSON_RPC_INVALID_PARAMS = -32602;
+/** MCP's "resource not found" error code (server/resources, error handling). */
+const MCP_RESOURCE_NOT_FOUND = -32002;
 /**
-* Resolve the {@link McpServeSource} (either an object exposing `tools()`
-* or a literal `ToolContract[]`) into a flat contract array.
+* A JSON-RPC failure raised inside a method handler, carrying the exact
+* code to answer with (unknown resource, missing prompt argument, …).
 */
-function resolveTools(source) {
-	if (Array.isArray(source)) return source;
-	return source.tools();
+var RpcFailure = class extends Error {
+	constructor(code, message, data) {
+		super(message);
+		this.code = code;
+		this.data = data;
+	}
+};
+/** Enumerate one tool set into a flat contract array. */
+function toolsOf(source) {
+	return Array.isArray(source) ? source : source.tools();
+}
+/** Narrow a serve source to its grouped shape. */
+function isGroupedSource(source) {
+	return !Array.isArray(source) && "groups" in source;
+}
+/**
+* Resolve the serve source into the exposed tool list, applying
+* `prefixToolNames` and refusing duplicate names. Throws
+* {@link McpServeError} — `"config"` for `prefixToolNames` on an ungrouped
+* source, `"collision"` when two tools would share a name.
+*/
+function resolveTools(source, options) {
+	const prefix = options.prefixToolNames ?? false;
+	const exposed = [];
+	if (isGroupedSource(source)) for (const [group, groupSource] of Object.entries(source.groups)) for (const contract of toolsOf(groupSource)) {
+		let name = contract.name;
+		if (prefix === true) name = `${group}_${contract.name}`;
+		else if (typeof prefix === "function") name = prefix(group, contract.name);
+		exposed.push({
+			name,
+			contract,
+			origin: `group "${group}"`
+		});
+	}
+	else {
+		if (prefix !== false) throw new McpServeError("prefixToolNames needs a grouped source: serve({ groups: { name: tools } }, …).", { type: "config" });
+		for (const contract of toolsOf(source)) exposed.push({
+			name: contract.name,
+			contract,
+			origin: "the source"
+		});
+	}
+	const seen = /* @__PURE__ */ new Map();
+	for (const tool of exposed) {
+		const previous = seen.get(tool.name);
+		if (previous !== void 0) throw new McpServeError(`MCP tool name "${tool.name}" is exposed twice (from ${previous} and ${tool.origin}). Rename one tool, or serve a grouped source with prefixToolNames.`, {
+			type: "collision",
+			context: { name: tool.name }
+		});
+		seen.set(tool.name, tool.origin);
+	}
+	return exposed.map(({ name, contract }) => ({
+		name,
+		contract
+	}));
+}
+/** Throw a collision error when two entries share the same key. */
+function assertUnique(entries, key, label) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of entries ?? []) {
+		const value = key(entry);
+		if (seen.has(value)) throw new McpServeError(`MCP ${label} "${value}" is declared twice.`, {
+			type: "collision",
+			context: { [label]: value }
+		});
+		seen.add(value);
+	}
 }
 /**
 * The pure protocol core of `serve` — maps one JSON-RPC request to its
-* response, with no I/O. Both the stdio and http serve-transports pump
+* response, with no I/O. Both the stdio and HTTP serve-transports pump
 * their inbound requests through this, and specs can drive it directly.
 *
-* Handles exactly the MCP slice this package serves: `initialize`,
-* `tools/list`, and `tools/call`. Any other method answers with a
-* JSON-RPC `method not found` error.
+* Handles `initialize`, `ping`, `tools/list`, `tools/call`, and — when
+* configured — `resources/list`, `resources/templates/list`,
+* `resources/read`, `prompts/list` and `prompts/get`. Any other method
+* answers with a JSON-RPC `method not found` error.
 *
 * Constructed via {@link createServeHandler}.
 */
 var McpServeHandler = class {
 	constructor(source, options) {
-		this.tools = resolveTools(source);
-		this.byName = new Map(this.tools.map((contract) => [contract.name, contract]));
+		this.tools = resolveTools(source, options);
+		this.byName = new Map(this.tools.map((tool) => [tool.name, tool.contract]));
+		assertUnique(options.resources, (resource) => resource.uri, "resource");
+		assertUnique(options.prompts, (prompt) => prompt.name, "prompt");
+		this.resources = options.resources ? new Map(options.resources.map((resource) => [resource.uri, resource])) : void 0;
+		this.prompts = options.prompts ? new Map(options.prompts.map((prompt) => [prompt.name, prompt])) : void 0;
 		this.options = options;
 	}
 	/**
 	* Dispatch one inbound JSON-RPC request to its handler and produce the
 	* response. A handler that throws is mapped to a JSON-RPC error response
 	* — the serve loop never crashes on a bad request.
+	*
+	* @param request - The JSON-RPC request.
+	* @param context - Per-call context: the inbound HTTP request (headers
+	*   reach tools as `ctx.request`) and an abort signal.
 	*/
-	async handle(request) {
+	async handle(request, context = {}) {
 		try {
-			switch (request.method) {
-				case "initialize": return this.ok(request.id, this.initializeResult());
-				case "tools/list": return this.ok(request.id, { tools: this.listTools() });
-				case "tools/call": return this.ok(request.id, await this.callTool(request.params));
-				default: return this.error(request.id, JSON_RPC_METHOD_NOT_FOUND, `Method "${request.method}" is not supported by this MCP server.`);
-			}
+			return this.ok(request.id, await this.dispatch(request, context));
 		} catch (cause) {
+			if (cause instanceof RpcFailure) return this.error(request.id, cause.code, cause.message, cause.data);
 			const message = cause instanceof Error ? cause.message : String(cause);
 			return this.error(request.id, JSON_RPC_INVALID_PARAMS, message);
 		}
 	}
-	/** Build the `initialize` result advertising name / version / capabilities. */
-	initializeResult() {
+	/** Route a method to its result builder. */
+	async dispatch(request, context) {
+		switch (request.method) {
+			case "initialize": return this.initializeResult(request.params);
+			case "ping": return {};
+			case "tools/list": return { tools: this.listTools() };
+			case "tools/call": return this.callTool(request.params, context);
+		}
+		if (this.resources) switch (request.method) {
+			case "resources/list": return { resources: this.listResources(this.resources) };
+			case "resources/templates/list": return { resourceTemplates: [] };
+			case "resources/read": return this.readResource(this.resources, request.params, context);
+		}
+		if (this.prompts) switch (request.method) {
+			case "prompts/list": return { prompts: this.listPrompts(this.prompts) };
+			case "prompts/get": return this.getPrompt(this.prompts, request.params, context);
+		}
+		throw new RpcFailure(JSON_RPC_METHOD_NOT_FOUND, `Method "${request.method}" is not supported by this MCP server.`);
+	}
+	/**
+	* Build the `initialize` result advertising name / version /
+	* capabilities, negotiating the protocol version: the client's requested
+	* version when supported, otherwise the newest this server speaks.
+	*/
+	initializeResult(params) {
+		const requested = readRecord(params).protocolVersion;
+		const protocolVersion = typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : LATEST_PROTOCOL_VERSION;
+		const capabilities = { tools: {} };
+		if (this.resources) capabilities.resources = {};
+		if (this.prompts) capabilities.prompts = {};
 		return {
-			protocolVersion: PROTOCOL_VERSION,
-			capabilities: { tools: {} },
+			protocolVersion,
+			capabilities,
 			serverInfo: {
 				name: this.options.name,
 				version: this.options.version ?? DEFAULT_VERSION
@@ -70,38 +170,52 @@ var McpServeHandler = class {
 	}
 	/**
 	* Build the `tools/list` payload: one {@link McpToolDescriptor} per
-	* contract, its `inputSchema` extracted via `extractJsonSchema` at the
-	* configured dialect (default `draft-2020-12` — overriding
+	* exposed tool, its `inputSchema` extracted via `extractJsonSchema` at
+	* the configured dialect (default `draft-2020-12` — overriding
 	* `extractJsonSchema`'s own `openai-strict` default to a neutral MCP draft).
 	*/
 	listTools() {
 		const target = this.options.schemaTarget ?? DEFAULT_SCHEMA_TARGET;
-		return this.tools.map((contract) => {
+		return this.tools.map(({ name, contract }) => {
 			const inputSchema = extractJsonSchema(contract.input, { target }) ?? {
 				type: "object",
 				properties: {}
 			};
 			return {
-				name: contract.name,
+				name,
 				description: contract.description,
-				inputSchema
+				inputSchema,
+				...isRecord(contract.meta?.outputSchema) ? { outputSchema: contract.meta.outputSchema } : {}
 			};
 		});
 	}
 	/**
 	* Route a `tools/call` to the named contract's `invoke()` and map the
 	* never-throwing {@link import("@warlock.js/ai").ToolInvokeResult}: `data`
-	* → a text content block, `error` → an `isError: true` result. An unknown
-	* tool name throws (mapped to a JSON-RPC error by {@link handle}).
+	* → a text content block (or an opted-in native result), `error` → an
+	* `isError: true` result. An unknown tool name throws (mapped to a
+	* JSON-RPC error by {@link handle}).
+	*
+	* The contract receives a `ToolContext` carrying the abort signal and,
+	* over HTTP, the inbound request's headers on `ctx.request`.
 	*/
-	async callTool(params) {
+	async callTool(params, context) {
 		const { name, args } = readCallParams(params);
 		const contract = this.byName.get(name);
 		if (!contract) throw new McpTransportError(`Unknown tool "${name}".`, {
 			type: "protocol",
 			method: "tools/call"
 		});
-		const result = await contract.invoke(args);
+		const toolContext = { artifacts: {} };
+		if (context.signal) toolContext.signal = context.signal;
+		if (context.request) {
+			const { headers, remoteAddress } = context.request;
+			toolContext.request = remoteAddress === void 0 ? { headers } : {
+				headers,
+				remoteAddress
+			};
+		}
+		const result = await contract.invoke(args, toolContext);
 		if (result.error) return {
 			content: [{
 				type: "text",
@@ -109,6 +223,16 @@ var McpServeHandler = class {
 			}],
 			isError: true
 		};
+		const mode = contract.meta?.mcpResults ?? this.options.results ?? "text";
+		if (isMcpResult(result.data) || mode === "native" && looksLikeMcpResult(result.data)) {
+			const native = isMcpResult(result.data) ? unwrapMcpResult(result.data) : result.data;
+			try {
+				assertMcpResult(native);
+			} catch {
+				throw new RpcFailure(JSON_RPC_INTERNAL_ERROR, "Invalid native MCP CallToolResult.");
+			}
+			return native;
+		}
 		return {
 			content: [{
 				type: "text",
@@ -117,6 +241,75 @@ var McpServeHandler = class {
 			isError: false
 		};
 	}
+	/** Build the `resources/list` payload (metadata only, no contents). */
+	listResources(resources) {
+		return [...resources.values()].map((resource) => compact({
+			uri: resource.uri,
+			name: resource.name,
+			title: resource.title,
+			description: resource.description,
+			mimeType: resource.mimeType
+		}));
+	}
+	/**
+	* Answer `resources/read`: run the resource's `read()` and wrap the
+	* result as one text or base64 blob content entry.
+	*/
+	async readResource(resources, params, context) {
+		const uri = readRecord(params).uri;
+		if (typeof uri !== "string") throw new RpcFailure(JSON_RPC_INVALID_PARAMS, "resources/read requires a string `uri`.");
+		const resource = resources.get(uri);
+		if (!resource) throw new RpcFailure(MCP_RESOURCE_NOT_FOUND, "Resource not found", { uri });
+		const body = await resource.read(context);
+		return { contents: [compact(typeof body === "string" ? {
+			uri,
+			mimeType: resource.mimeType,
+			text: body
+		} : {
+			uri,
+			mimeType: resource.mimeType,
+			blob: Buffer.from(body).toString("base64")
+		})] };
+	}
+	/** Build the `prompts/list` payload. */
+	listPrompts(prompts) {
+		return [...prompts.values()].map((prompt) => compact({
+			name: prompt.name,
+			title: prompt.title,
+			description: prompt.description,
+			arguments: prompt.arguments
+		}));
+	}
+	/**
+	* Answer `prompts/get`: validate the arguments (strings only; required
+	* ones present) and build the messages. An unknown prompt or a missing
+	* required argument answers invalid-params, per the MCP prompts spec.
+	*/
+	async getPrompt(prompts, params, context) {
+		const record = readRecord(params);
+		const name = record.name;
+		if (typeof name !== "string") throw new RpcFailure(JSON_RPC_INVALID_PARAMS, "prompts/get requires a string `name`.");
+		const prompt = prompts.get(name);
+		if (!prompt) throw new RpcFailure(JSON_RPC_INVALID_PARAMS, `Unknown prompt "${name}".`);
+		const args = {};
+		for (const [key, value] of Object.entries(readRecord(record.arguments))) {
+			if (typeof value !== "string") throw new RpcFailure(JSON_RPC_INVALID_PARAMS, `Prompt argument "${key}" must be a string.`);
+			args[key] = value;
+		}
+		for (const argument of prompt.arguments ?? []) if (argument.required && args[argument.name] === void 0) throw new RpcFailure(JSON_RPC_INVALID_PARAMS, `Prompt "${name}" requires the "${argument.name}" argument.`);
+		const built = await prompt.get(args, context);
+		const messages = typeof built === "string" ? [{
+			role: "user",
+			content: {
+				type: "text",
+				text: built
+			}
+		}] : built;
+		return compact({
+			description: prompt.description,
+			messages
+		});
+	}
 	/** Build a JSON-RPC success response. */
 	ok(id, result) {
 		return {
@@ -126,17 +319,77 @@ var McpServeHandler = class {
 		};
 	}
 	/** Build a JSON-RPC error response. */
-	error(id, code, message) {
+	error(id, code, message, data) {
 		return {
 			jsonrpc: JSONRPC_VERSION,
 			id,
-			error: {
+			error: data === void 0 ? {
 				code,
 				message
+			} : {
+				code,
+				message,
+				data
 			}
 		};
 	}
 };
+/** JSON-RPC "Invalid Request" — the line is JSON but not a request object. */
+const JSON_RPC_INVALID_REQUEST = -32600;
+/** JSON-RPC "Internal error" — answering the request failed unexpectedly. */
+const JSON_RPC_INTERNAL_ERROR = -32603;
+/**
+* Turn one stdio line into the line to write back, or `undefined` when
+* nothing is answered: blank or non-JSON lines and notifications (no `id`).
+* A JSON value that is not a request object (`null`, a number, an array) is
+* answered with a JSON-RPC "Invalid Request" error whose `id` is `null`.
+* Never rejects: a dispatch failure is answered as an internal error.
+*/
+async function answerStdioLine(line, dispatch) {
+	const trimmed = line.trim();
+	if (!trimmed) return;
+	let message;
+	try {
+		message = JSON.parse(trimmed);
+	} catch {
+		return;
+	}
+	if (typeof message !== "object" || message === null || Array.isArray(message)) return `${JSON.stringify({
+		jsonrpc: JSONRPC_VERSION,
+		id: null,
+		error: {
+			code: JSON_RPC_INVALID_REQUEST,
+			message: "Invalid request: not a JSON-RPC object."
+		}
+	})}\n`;
+	const request = message;
+	const id = request.id;
+	if (id === void 0 || id === null) return;
+	try {
+		const response = await dispatch(request);
+		return `${JSON.stringify(response)}\n`;
+	} catch {
+		return `${JSON.stringify({
+			jsonrpc: JSONRPC_VERSION,
+			id,
+			error: {
+				code: JSON_RPC_INTERNAL_ERROR,
+				message: "Internal error."
+			}
+		})}\n`;
+	}
+}
+/** Read an unknown value as a plain record (non-objects read as empty). */
+function readRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+	return value;
+}
+/** Drop `undefined` members so optional wire fields are omitted, not `null`. */
+function compact(value) {
+	const result = {};
+	for (const [key, member] of Object.entries(value)) if (member !== void 0) result[key] = member;
+	return result;
+}
 /**
 * Read and validate the `tools/call` params into `{ name, args }`. Throws
 * a typed {@link McpTransportError} when `name` is missing — mapped to a
@@ -172,9 +425,12 @@ function serializeData(data) {
 * {@link serve}) so callers and tests can drive the MCP protocol without an
 * actual transport — feed it a JSON-RPC request, get the response.
 *
-* @param source - The tools to expose (an object with `tools()` or a literal array).
-* @param options - Serve options (name / version / schema target).
-* @returns An object whose `handle(request)` maps a request to a response.
+* Throws {@link McpServeError} on duplicate tool names / resource URIs /
+* prompt names, or `prefixToolNames` on an ungrouped source.
+*
+* @param source - The tools to expose (one tool set or `{ groups }`).
+* @param options - Serve options (name / version / schema target / resources / prompts).
+* @returns An object whose `handle(request, context?)` maps a request to a response.
 */
 function createServeHandler(source, options) {
 	return new McpServeHandler(source, options);
@@ -182,83 +438,70 @@ function createServeHandler(source, options) {
 /**
 * The internal {@link McpServer} — owns a {@link McpServeHandler} and a
 * transport pump. For `stdio` it reads newline-delimited JSON-RPC requests
-* from `process.stdin` and writes responses to `process.stdout`; the
-* `http` transport is accepted but listening is deferred to the host
-* (a serve-over-HTTP needs a server the caller owns).
+* from `process.stdin` and writes responses to `process.stdout`; for
+* `http` it binds a Streamable HTTP endpoint (see `./serve-http`).
 *
 * Constructed via {@link serve}; the class itself is internal.
 */
 var McpServerImpl = class {
 	constructor(source, options) {
-		this.running = false;
 		this.handler = new McpServeHandler(source, options);
 		this.options = options;
 	}
-	async start() {
-		if (this.running) return;
-		if ((this.options.transport ?? { type: "stdio" }).type !== "stdio") throw new McpTransportError("serve() over http requires a host-provided server; only stdio is auto-pumped.", { type: "connect" });
-		this.running = true;
-		this.reader = createInterface({ input: process.stdin });
-		this.reader.on("line", (line) => {
-			this.onLine(line);
+	start() {
+		if (!this.running) {
+			const transport = this.options.transport ?? { type: "stdio" };
+			const starting = transport.type === "http" ? this.startHttp(transport) : Promise.resolve(this.startStdio());
+			this.running = starting.catch((error) => {
+				this.running = void 0;
+				throw error;
+			});
+		}
+		return this.running;
+	}
+	/** Bind the HTTP endpoint; its `close()` also makes this server startable again. */
+	async startHttp(transport) {
+		const http = await startHttpServer(transport, (request, context) => this.handler.handle(request, context));
+		return {
+			url: http.url,
+			close: async () => {
+				await http.close();
+				this.running = void 0;
+			}
+		};
+	}
+	/** Wire the stdin line reader and answer each request on stdout. */
+	startStdio() {
+		const reader = createInterface({ input: process.stdin });
+		reader.on("line", (line) => {
+			this.onLine(line).catch(() => {});
 		});
+		return { close: async () => {
+			reader.close();
+			this.running = void 0;
+		} };
 	}
-	/**
-	* Parse one stdin line as a JSON-RPC request, dispatch it through the
-	* handler, and write the response as a single line to stdout. Non-JSON
-	* lines and notifications (no `id`) are ignored.
-	*/
+	/** Answer one stdin line on stdout (see {@link answerStdioLine}). */
 	async onLine(line) {
-		const trimmed = line.trim();
-		if (!trimmed) return;
-		let request;
+		const reply = await answerStdioLine(line, (request) => this.handler.handle(request));
+		if (reply !== void 0) process.stdout.write(reply);
+	}
+	async stop() {
+		const running = this.running;
+		if (!running) return;
+		let handle;
 		try {
-			request = JSON.parse(trimmed);
+			handle = await running;
 		} catch {
 			return;
 		}
-		if (request.id === void 0 || request.id === null) return;
-		const response = await this.handler.handle(request);
-		process.stdout.write(`${JSON.stringify(response)}\n`);
-	}
-	async stop() {
-		this.running = false;
-		this.reader?.close();
-		this.reader = void 0;
+		await handle.close();
 	}
 };
-/**
-* Expose a built agent / supervisor / orchestrator (or a raw
-* `ToolContract[]`) AS an MCP server (Direction B: local primitive → MCP
-* server other clients consume).
-*
-* Enumerates `source.tools()` (or the literal array) once at construction.
-* `tools/list` answers with each tool's `inputSchema` extracted via
-* `extractJsonSchema` at the configured `schemaTarget` (default
-* `draft-2020-12`). `tools/call` routes to the named contract's
-* `invoke()` and maps the never-throwing result — `data` becomes a text
-* content block, `error` becomes an `isError: true` result — so a failing
-* tool surfaces as a normal MCP tool error rather than crashing the server.
-*
-* The default transport is `stdio`, pumped over `process.stdin` /
-* `process.stdout`. Serving over HTTP is left to a host-owned server;
-* `start()` rejects an `http` transport (the protocol core is available
-* via {@link createServeHandler} for a caller's own HTTP wiring).
-*
-* @param source - The tools to expose.
-* @param options - Server name, version, transport, and schema dialect.
-* @returns An {@link McpServer} with `start()` / `stop()`.
-*
-* @example
-* serve(
-*   { tools: () => ws.allTools() },
-*   { name: "warlock-workspace", transport: { type: "stdio" } },
-* ).start();
-*/
 function serve(source, options) {
 	return new McpServerImpl(source, options);
 }
 
 //#endregion
-export { createServeHandler, serve };
+export { answerStdioLine, createServeHandler, serve };
 //# sourceMappingURL=serve.mjs.map