@dougbots/avenor-mcp 0.1.0

package/README.md

@@ -0,0 +1,185 @@
+# @dougbots/avenor-mcp
+
+MCP server that makes [avenor](https://github.com/dougbots/avenor) agent runs available as tools inside any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.).
+
+## When you need this
+
+You have `avenor` installed and you want Claude (or another MCP host) to spawn and manage agent runs — kicking off a Codex or Gemini session, checking its status, answering permission prompts, tailing event logs, and resuming completed runs with a follow-up.
+
+This package is the MCP layer. It depends on `@dougbots/avenor-core` for all the actual wiring (supervisor lifecycle, binary discovery, socket protocol). You don't need to know the internals to use it.
+
+## Prerequisites
+
+- **Node 20+** (or Bun — the server runs on Bun but is shipped as ESM)
+- **`avenor` binary** on your `PATH`, or set `AVENOR_BIN=/path/to/avenor`
+
+If the binary isn't found at startup, the MCP server will fail to connect.
+
+## Install
+
+```bash
+npm install @dougbots/avenor-mcp
+```
+
+Or run it on-demand with `npx` (see configuration below).
+
+## Configuration
+
+### stdio transport (default)
+
+Add to your MCP host config. For **Claude Code**, edit `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "avenor": {
+      "command": "npx",
+      "args": ["@dougbots/avenor-mcp"],
+      "env": {
+        "AVENOR_BIN": "/opt/homebrew/bin/avenor"
+      }
+    }
+  }
+}
+```
+
+For **Claude Desktop**, use `~/.config/Claude/claude_desktop_config.json` with the same shape.
+
+Skip `AVENOR_BIN` if `avenor` is already on your `PATH`. On a fresh session, the supervisor auto-starts the `avenor` daemon the first time you call a tool.
+
+### SSE transport
+
+When you need the MCP server running as a long-lived HTTP service (multiple clients, remote access via tunneling, etc.), use SSE mode. Set `MCP_TRANSPORT=sse` and provide an auth token:
+
+```bash
+MCP_TRANSPORT=sse \
+MCP_AUTH_TOKEN="my-secret" \
+MCP_PORT=3748 \
+npx @dougbots/avenor-mcp
+```
+
+Then in your MCP host config:
+
+```json
+{
+  "mcpServers": {
+    "avenor": {
+      "url": "http://127.0.0.1:3748/mcp",
+      "headers": {
+        "Authorization": "Bearer my-secret"
+      }
+    }
+  }
+}
+```
+
+SSE mode restricts incoming requests to `localhost` / `127.0.0.1` / `[::1]` origins. The auth token is required — the server returns `401` without it.
+
+| Env variable | Default | Notes |
+|---|---|---|
+| `MCP_TRANSPORT` | (unset → stdio) | Set to `sse` for HTTP |
+| `MCP_PORT` | `3748` | Only used in SSE mode |
+| `MCP_AUTH_TOKEN` | — | **Required** in SSE mode |
+| `AVENOR_BIN` | — | Path to the `avenor` binary (falls back to `PATH`) |
+
+## Tools
+
+All six tools register under the `avenor_` prefix to avoid collisions with other MCP servers.
+
+### `avenor_spawn`
+
+Start a new agent run.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `agent` | yes | Agent to invoke: `codex`, `claude`, `gemini`, `butler` |
+| `repo_dir` | yes | Working directory for the agent |
+| `prompt` | no | Prompt text (mutually exclusive with `prompt_file`) |
+| `prompt_file` | no | Path to a prompt file |
+| `label` | no | Human-readable label for this run |
+| `timeout` | no | Duration string (`5m`, `1h`, `90s`) |
+| `model` | no | Model override for the agent |
+| `supervisor_id` | no | Supervisor ID for multi-supervisor setups |
+
+Returns `{ run_id, label, supervisor_id }`. The `run_id` is what you pass to the other tools.
+
+### `avenor_status`
+
+Get the status of one run, or list all runs.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `run_id` | no | Run ID or label to query. Omit to list all runs. |
+| `supervisor_id` | no | Supervisor ID for multi-supervisor setups |
+
+Returns a status object (or array) with `status` being one of `running`, `done`, `failed`, `timeout`, or `killed`. When a run is blocked on a permission request, the response includes a `pending_permission` field with the available options.
+
+### `avenor_answer_permission`
+
+Respond to a permission prompt that paused a run.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `run_id` | yes | Run ID or label |
+| `option_id` | yes | The option to select (from the `pending_permission` shown by `avenor_status`) |
+| `request_id` | no | Specific permission request ID. Auto-detected from the pending request if omitted. |
+| `supervisor_id` | no | Supervisor ID for multi-supervisor setups |
+
+Returns `{ ok: true }` on success. Throws if no permission request is pending for the given run.
+
+### `avenor_follow_up`
+
+Resume a completed run with a new message. The agent picks up from the same session, so it retains context from the original run.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `run_id` | yes | Run ID or label of the *completed* run to resume |
+| `message` | yes | Follow-up prompt |
+| `label` | no | Label for the follow-up run (defaults to `<original-label>-followup`) |
+| `supervisor_id` | no | Supervisor ID for multi-supervisor setups |
+
+Returns `{ run_id, label }` for the new follow-up run. Throws if the original run has no persisted session.
+
+### `avenor_events`
+
+Fetch the event log for a run. Useful for inspecting what an agent did.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `run_id` | yes | Run ID or label |
+| `types` | no | Filter by event types (array of strings) |
+| `limit` | no | Max events to return (default `50`, max `1000`) |
+| `supervisor_id` | no | Supervisor ID for multi-supervisor setups |
+
+Returns an array of event objects (`{ type, ts, ... }`) in chronological order.
+
+### `avenor_shutdown`
+
+Stop the avenor supervisor and clean up sentinel files.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `supervisor_id` | no | Supervisor ID for multi-supervisor setups |
+| `force` | no | Force shutdown instead of graceful (`false` by default) |
+
+Returns `{ ok: true, cleaned_up: [...] }`. Use this when you're done with avenor in your session or when the supervisor crashes and needs to be restarted.
+
+## Typical workflow
+
+1. **Spawn a run:** `avenor_spawn(agent: "codex", repo_dir: "/path/to/project", prompt: "audit the API routes for auth gaps")`
+2. **Check status:** `avenor_status(run_id: "<id>")` — repeat until status is `done` or an action is needed.
+3. **If permission requested:** run `avenor_answer_permission` with the option you want.
+4. **After completion:** `avenor_events(run_id: "<id>")` to see what happened.
+5. **Optional follow-up:** `avenor_follow_up(run_id: "<id>", message: "now write tests for that")`
+6. **Clean up:** `avenor_shutdown()` when you're finished.
+
+## Package structure
+
+```
+@dougbots/avenor-mcp
+├── @dougbots/avenor-core  (workspace dep — supervisor, tool implementations)
+├── @modelcontextprotocol/sdk  (MCP server + transports)
+└── hono  (HTTP framework for SSE transport)
+```
+
+The server is a single file (`src/mcp.ts`), compiled to `dist/index.js` by tsdown. The `avenor-mcp` bin entry runs it directly.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+//#region src/mcp.d.ts
+declare function parseBearerToken(authorizationHeader: string | null | undefined): string | null;
+declare function isAllowedOrigin(originHeader: string | null | undefined): boolean;
+declare function isAllowedHost(hostHeader: string | null | undefined, port: number): boolean;
+declare function getMcpAuthToken(): string;
+//#endregion
+export { getMcpAuthToken, isAllowedHost, isAllowedOrigin, parseBearerToken };

package/dist/index.js

@@ -0,0 +1,171 @@
+#!/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 { Hono } from "hono";
+import { z } from "zod";
+import { answerPermissionTool, eventsTool, followUpTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+//#region src/mcp.ts
+const LOCALHOST_ORIGINS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+function parseBearerToken(authorizationHeader) {
+	if (!authorizationHeader) return null;
+	return authorizationHeader.match(/^Bearer\s+(.+)$/i)?.[1]?.trim() || null;
+}
+function isAllowedOrigin(originHeader) {
+	if (!originHeader) return true;
+	try {
+		const origin = new URL(originHeader);
+		return origin.protocol === "http:" && LOCALHOST_ORIGINS.has(origin.hostname);
+	} catch {
+		return false;
+	}
+}
+function isAllowedHost(hostHeader, port) {
+	if (!hostHeader) return false;
+	const [host, hostPort] = hostHeader.startsWith("[") ? (() => {
+		const end = hostHeader.indexOf("]");
+		if (end === -1) return [hostHeader, void 0];
+		const host = hostHeader.slice(0, end + 1);
+		const portPart = hostHeader.slice(end + 1);
+		return [host, portPart.startsWith(":") ? portPart.slice(1) : void 0];
+	})() : hostHeader.split(":");
+	if (!LOCALHOST_ORIGINS.has(host)) return false;
+	return hostPort === String(port);
+}
+function getMcpAuthToken() {
+	const token = process.env.MCP_AUTH_TOKEN?.trim();
+	if (!token) throw new Error("MCP_TRANSPORT=sse requires MCP_AUTH_TOKEN to be set");
+	return token;
+}
+const server = new McpServer({
+	name: "avenor",
+	version: "0.1.0"
+});
+server.registerTool("avenor_spawn", {
+	description: "Spawn a new agent run",
+	inputSchema: {
+		agent: z.string().describe("Agent name (codex, claude, gemini, butler)"),
+		repo_dir: z.string().describe("Working directory for the agent"),
+		prompt: z.string().optional().describe("Prompt text"),
+		prompt_file: z.string().optional().describe("Path to a prompt file"),
+		label: z.string().optional().describe("Human-readable label for this run"),
+		timeout: z.string().optional().describe("Timeout duration (e.g. 5m, 1h)"),
+		model: z.string().optional().describe("Model override"),
+		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
+	}
+}, async ({ repo_dir, agent, prompt, prompt_file, label, timeout, model, supervisor_id }) => {
+	return spawnTool({
+		agent,
+		dir: repo_dir,
+		prompt,
+		promptFile: prompt_file,
+		label,
+		timeout,
+		model,
+		supervisorId: supervisor_id
+	});
+});
+server.registerTool("avenor_status", {
+	description: "Get status of one or all runs",
+	inputSchema: {
+		run_id: z.string().optional().describe("Run ID or label to query"),
+		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
+	}
+}, async ({ run_id, supervisor_id }) => {
+	return statusTool({
+		runId: run_id,
+		supervisorId: supervisor_id
+	});
+});
+server.registerTool("avenor_answer_permission", {
+	description: "Answer a pending permission request",
+	inputSchema: {
+		run_id: z.string().describe("Run ID or label"),
+		option_id: z.string().describe("Option ID to select"),
+		request_id: z.string().optional().describe("Permission request ID (auto-detected if omitted)"),
+		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
+	}
+}, async ({ run_id, option_id, request_id, supervisor_id }) => {
+	return answerPermissionTool({
+		runId: run_id,
+		optionId: option_id,
+		requestId: request_id,
+		supervisorId: supervisor_id
+	});
+});
+server.registerTool("avenor_follow_up", {
+	description: "Resume a completed run with a follow-up message",
+	inputSchema: {
+		run_id: z.string().describe("Run ID or label to follow up on"),
+		message: z.string().describe("Follow-up message"),
+		label: z.string().optional().describe("Label for the follow-up run"),
+		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
+	}
+}, async ({ run_id, message, label, supervisor_id }) => {
+	return followUpTool({
+		runId: run_id,
+		message,
+		label,
+		supervisorId: supervisor_id
+	});
+});
+server.registerTool("avenor_events", {
+	description: "Get event log for a run",
+	inputSchema: {
+		run_id: z.string().describe("Run ID or label"),
+		types: z.array(z.string()).optional().describe("Filter by event types"),
+		limit: z.number().optional().describe("Max events to return (default 50)"),
+		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode")
+	}
+}, async ({ run_id, types, limit, supervisor_id }) => {
+	return eventsTool({
+		runId: run_id,
+		types,
+		limit,
+		supervisorId: supervisor_id
+	});
+});
+server.registerTool("avenor_shutdown", {
+	description: "Shut down the supervisor",
+	inputSchema: {
+		supervisor_id: z.string().optional().describe("Supervisor ID for multi-supervisor mode"),
+		force: z.boolean().optional().describe("Force shutdown instead of graceful")
+	}
+}, async ({ supervisor_id, force }) => {
+	return shutdownTool({
+		supervisorId: supervisor_id,
+		force
+	});
+});
+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();
+	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);
+	});
+	await server.connect(transport);
+	Bun.serve({
+		fetch: app.fetch,
+		port,
+		hostname: "127.0.0.1"
+	});
+	console.error(`avenor MCP server listening on :${port}`);
+}
+//#endregion
+export { getMcpAuthToken, isAllowedHost, isAllowedOrigin, parseBearerToken };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dougbots/avenor-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "avenor-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "bun test",
+    "dev": "tsdown --watch"
+  },
+  "dependencies": {
+    "@dougbots/avenor-core": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "hono": "^4.12.19",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.12",
+    "@types/node": "^25.8.0",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "unrun": "^0.3.0"
+  }
+}