@dougbots/avenor-mcp 0.17.0 → 0.18.0

package/dist/index.d.ts

@@ -6,5 +6,19 @@ declare function isAllowedOrigin(originHeader: string | null | undefined): boole
 declare function isAllowedHost(hostHeader: string | null | undefined, port: number): boolean;
 declare function getMcpAuthToken(): string;
 declare const server: McpServer;
+interface HttpServerOptions {
+  authToken: string;
+  /** 0 binds an ephemeral port; the bound port is reported back. */
+  port?: number;
+}
+/**
+ * Serve the MCP endpoint over HTTP with the transport's web-standard
+ * implementation: Hono already hands out a Web `Request`, and the request
+ * checks below answer before the transport sees a message.
+ */
+declare function startHttpServer(options: HttpServerOptions): Promise<{
+  port: number;
+  stop: () => Promise<void>;
+}>;
 //#endregion
-export { getMcpAuthToken, isAllowedHost, isAllowedOrigin, parseBearerToken, server };
+export { HttpServerOptions, getMcpAuthToken, isAllowedHost, isAllowedOrigin, parseBearerToken, server, startHttpServer };

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { Hono } from "hono";
 import { z } from "zod";
 import { THINKING_LEVELS, ToolError, answerPermissionTool, createHostMessageProvider, eventsTool, getSupervisorClient, isGenerationMismatchError, killTool, messageTool, peersDetails, peersTool, renderPeerList, resultOutput, resultTool, shutdownTool, spawnTool, statusTool, validateSpawnSelection, workflowCancelTool, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
@@ -64,7 +64,7 @@ var message_input_flat_default = {
 	description: "Flat input schema for the avenor_message tool, compiled from schemas/message.input.json's per-action union so an MCP client publishes one object whose property types survive: an integer stays an integer and an object stays an object. Every action's properties appear here, so a field belonging to another action is not a schema error. Per-action admission (required fields, unknown properties, types and limits) belongs to the router, which answers a mismatch at once with the contract's typed invalid_request and its repair text. Generated by internal/messaging/cmd/genschema; do not edit.",
 	properties: {
 		"action": {
-			"description": "Action to perform: tell — Deliver a message without creating a reply edge; ask — Deliver a message and wait for one reply; reply — Answer an ask this surface received; resume — Continue a finished run in a new run; withdraw — Retract an ask this caller sent; control_reply — Answer a claude-channel control request; registered only on the claude-channel backend.",
+			"description": "Action to perform: tell — Deliver a message without creating a reply edge; ask — Deliver a message and wait for one reply; reply — Answer an ask this surface received; resume — Continue a finished run in a new run; withdraw — Retract an ask this caller sent; control_reply — Retained in the contract for the retired claude-channel backend's reply path; no surface can deliver one.",
 			"enum": [
 				"tell",
 				"ask",
@@ -100,7 +100,7 @@ var message_input_flat_default = {
 			"type": "string"
 		},
 		"target": {
-			"description": "Recipient: a reserved self alias, a broker/runtime id, a host-surface public run id, or a peer label. Prior run: a reserved self alias, a broker/runtime id, a host-surface public run id, or a peer label. Opaque claude-channel control message id, passed through unchanged.",
+			"description": "Recipient: a reserved self alias, a broker/runtime id, a host-surface public run id, or a peer label. Prior run: a reserved self alias, a broker/runtime id, a host-surface public run id, or a peer label. Opaque control message id, passed through unchanged.",
 			"type": "string"
 		},
 		"timeout_ms": {
@@ -204,7 +204,7 @@ server.registerTool("spawn", {
 		roster_file,
 		roster_entry
 	});
-	return spawnTool({
+	return passthroughResult(spawnTool({
 		agent,
 		dir: repo_dir,
 		prompt,
@@ -218,7 +218,7 @@ server.registerTool("spawn", {
 		rosterEntry: roster_entry,
 		serverUrl: server_url,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("status", {
 	description: "Get lifecycle status of one or all runs. Use lifecycle view for compact polling. Without run_id, returns an object with runs (array of status objects) and count.",
@@ -228,11 +228,11 @@ server.registerTool("status", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ run_id, view, supervisor_id }) => {
-	return statusTool({
+	return passthroughResult(statusTool({
 		runId: run_id,
 		supervisorId: supervisor_id,
 		view
-	});
+	}));
 });
 server.registerTool("result", {
 	description: "Retrieve the complete final output of a run without transcript or event details. Waits by default; set wait=false to retrieve an already-completed run without blocking",
@@ -243,12 +243,12 @@ server.registerTool("result", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ run_id, wait, timeout, supervisor_id }) => {
-	return resultTool({
+	return passthroughResult(resultTool({
 		runId: run_id,
 		supervisorId: supervisor_id,
 		wait,
 		timeout
-	});
+	}));
 });
 server.registerTool("answer_permission", {
 	description: "Answer a pending permission request",
@@ -260,13 +260,13 @@ server.registerTool("answer_permission", {
 		message: z.string().optional().describe("Optional write-in response text. Required only when the selected option declares requiresMessage: true.")
 	}
 }, async ({ run_id, option_id, request_id, supervisor_id, message }) => {
-	return answerPermissionTool({
+	return passthroughResult(answerPermissionTool({
 		runId: run_id,
 		optionId: option_id,
 		requestId: request_id,
 		supervisorId: supervisor_id,
 		message
-	});
+	}));
 });
 /**
 * The message and peers tools publish the flat schema compiled from the
@@ -315,6 +315,19 @@ async function withProvider(run) {
 		return run(await messageProvider());
 	}
 }
+/**
+* The pass-through tools answer with the core tool's result object, which the
+* MCP result schema carries as free-form fields beside `content`. The schema
+* defaults `content` to an empty list, so sending it explicitly is what a
+* client already ends up with, and it keeps the handler's declared result
+* type honest without hiding the result fields.
+*/
+async function passthroughResult(result) {
+	return {
+		...await result,
+		content: []
+	};
+}
 /** A router tool error is a failure result on every surface; anything else is the transport's to report. */
 function toolFailure(error) {
 	if (!(error instanceof ToolError)) throw error;
@@ -380,12 +393,12 @@ server.registerTool("workflow_cancel", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ workflow_id, actor, reason, supervisor_id }) => {
-	return workflowCancelTool({
+	return passthroughResult(workflowCancelTool({
 		workflow_id,
 		actor,
 		reason,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("events", {
 	description: "Get event log for a run",
@@ -396,12 +409,12 @@ server.registerTool("events", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ run_id, types, limit, supervisor_id }) => {
-	return eventsTool({
+	return passthroughResult(eventsTool({
 		runId: run_id,
 		types,
 		limit,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("kill", {
 	description: "Terminate a run without shutting down the supervisor. Other runs and the supervisor itself keep running.",
@@ -410,10 +423,10 @@ server.registerTool("kill", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ run_id, supervisor_id }) => {
-	return killTool({
+	return passthroughResult(killTool({
 		runId: run_id,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("shutdown", {
 	description: "Shut down the supervisor",
@@ -422,10 +435,10 @@ server.registerTool("shutdown", {
 		force: z.boolean().optional().describe("Force shutdown instead of graceful")
 	}
 }, async ({ supervisor_id, force }) => {
-	return shutdownTool({
+	return passthroughResult(shutdownTool({
 		supervisorId: supervisor_id,
 		force
-	});
+	}));
 });
 server.registerTool("workflow_status", {
 	description: "Get lightweight status for a workflow instance",
@@ -434,10 +447,10 @@ server.registerTool("workflow_status", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ workflow_id, supervisor_id }) => {
-	return workflowStatusTool({
+	return passthroughResult(workflowStatusTool({
 		workflowId: workflow_id,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("workflow_wait", {
 	description: "Wait for a workflow to reach a terminal state or until timeout",
@@ -447,11 +460,11 @@ server.registerTool("workflow_wait", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ workflow_id, timeout, supervisor_id }) => {
-	return workflowWaitTool({
+	return passthroughResult(workflowWaitTool({
 		workflowId: workflow_id,
 		timeout,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("workflow_inspect", {
 	description: "Return the full instance detail for a workflow",
@@ -460,10 +473,10 @@ server.registerTool("workflow_inspect", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ workflow_id, supervisor_id }) => {
-	return workflowInspectTool({
+	return passthroughResult(workflowInspectTool({
 		workflowId: workflow_id,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("workflow_events", {
 	description: "Read log events from a workflow instance's event log",
@@ -474,12 +487,12 @@ server.registerTool("workflow_events", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ workflow_id, after_seq, limit, supervisor_id }) => {
-	return workflowEventsTool({
+	return passthroughResult(workflowEventsTool({
 		workflowId: workflow_id,
 		afterSeq: after_seq,
 		limit,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("workflow_complete", {
 	description: "Atomically complete a machine/external handoff activation",
@@ -497,10 +510,10 @@ server.registerTool("workflow_complete", {
 	}
 }, async (args) => {
 	const { supervisor_id, ...rest } = args;
-	return workflowCompleteTool({
+	return passthroughResult(workflowCompleteTool({
 		...rest,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("workflow_gate", {
 	description: "Record a gate decision on a parked awaiting_gate activation",
@@ -529,10 +542,10 @@ server.registerTool("workflow_gate", {
 	}
 }, async (args) => {
 	const { supervisor_id, ...rest } = args;
-	return workflowGateTool({
+	return passthroughResult(workflowGateTool({
 		...rest,
 		supervisorId: supervisor_id
-	});
+	}));
 });
 server.registerTool("workflow_controller_status", {
 	description: "Show workflow controller status. With controller_id, returns that controller's full status; without it, lists all controllers with summary state. Create, enable, and disable are CLI-only (avenor workflow controller ...).",
@@ -541,36 +554,54 @@ server.registerTool("workflow_controller_status", {
 		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
 	}
 }, async ({ controller_id, supervisor_id }) => {
-	return workflowControllerStatusTool({
+	return passthroughResult(workflowControllerStatusTool({
 		controllerId: controller_id,
 		supervisorId: supervisor_id
-	});
+	}));
 });
-if (import.meta.main) if (process.env.MCP_TRANSPORT !== "sse") {
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
-} else {
-	const port = Number(process.env.MCP_PORT ?? 3748);
-	const authToken = getMcpAuthToken();
+/**
+* Serve the MCP endpoint over HTTP with the transport's web-standard
+* implementation: Hono already hands out a Web `Request`, and the request
+* checks below answer before the transport sees a message.
+*/
+async function startHttpServer(options) {
+	const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: () => crypto.randomUUID() });
+	let boundPort = options.port ?? 0;
 	const app = new Hono();
-	const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => crypto.randomUUID() });
 	app.all("/mcp", (c) => {
 		const request = c.req.raw;
 		const originHeader = request.headers.get("origin");
 		const hostHeader = request.headers.get("host");
 		const token = parseBearerToken(request.headers.get("authorization"));
 		if (!isAllowedOrigin(originHeader)) return c.text("Forbidden origin", 403);
-		if (!isAllowedHost(hostHeader, port)) return c.text("Forbidden host", 403);
-		if (token !== authToken) return c.text("Unauthorized", 401, { "WWW-Authenticate": "Bearer" });
-		return transport.handleRequest(c.req.raw, c.res, c.req.raw.body);
+		if (!isAllowedHost(hostHeader, boundPort)) return c.text("Forbidden host", 403);
+		if (token !== options.authToken) return c.text("Unauthorized", 401, { "WWW-Authenticate": "Bearer" });
+		return transport.handleRequest(request);
 	});
 	await server.connect(transport);
-	Bun.serve({
+	const http = Bun.serve({
 		fetch: app.fetch,
-		port,
+		port: boundPort,
 		hostname: "127.0.0.1"
 	});
+	boundPort = http.port ?? boundPort;
+	return {
+		port: boundPort,
+		stop: async () => {
+			await server.close();
+			await http.stop(true);
+		}
+	};
+}
+if (import.meta.main) if (process.env.MCP_TRANSPORT !== "sse") {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+} else {
+	const { port } = await startHttpServer({
+		authToken: getMcpAuthToken(),
+		port: Number(process.env.MCP_PORT ?? 3748)
+	});
 	console.error(`avenor MCP server listening on :${port}`);
 }
 //#endregion
-export { getMcpAuthToken, isAllowedHost, isAllowedOrigin, parseBearerToken, server };
+export { getMcpAuthToken, isAllowedHost, isAllowedOrigin, parseBearerToken, server, startHttpServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougbots/avenor-mcp",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,11 +26,12 @@
   },
   "scripts": {
     "build": "tsdown",
+    "typecheck": "tsc --noEmit",
     "test": "bun test",
     "dev": "tsdown --watch"
   },
   "dependencies": {
-    "@dougbots/avenor-core": "^0.17.0",
+    "@dougbots/avenor-core": "^0.18.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "hono": "^4.12.19",
     "zod": "^4.4.3"