@bike4mind/cli 0.18.4 → 0.20.0

package/dist/serve-CuF0I5en.mjs

@@ -0,0 +1,772 @@
+#!/usr/bin/env node
+import { c as requireApiUrl, d as AGENT_QUEST_MANIFEST, f as AGENT_QUEST_MCP_URI, n as logger, s as parseApiUrl, t as ConfigStore, u as AGENT_QUEST_ID } from "./ConfigStore-DD3DcC3-.mjs";
+import { t as ApiClient } from "./ApiClient-B_CQrUiF.mjs";
+import { z as z$1 } from "zod";
+import { isAxiosError } from "axios";
+import { Writable } from "node:stream";
+import { createServer } from "node:http";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+//#region src/mcp/b4mApiClient.ts
+/**
+* Typed wrapper over {@link ApiClient} exposing exactly the Bike4Mind REST
+* endpoints the MCP tools call. All routes are `baseApi()` routes that accept
+* either an OAuth JWT or an instance API key, so a caller supplies whichever it
+* has via the underlying ApiClient.
+*/
+var B4mApiClient = class {
+	constructor(baseURL, configStore, apiKey) {
+		this.baseURL = baseURL;
+		this.client = new ApiClient(baseURL, configStore, apiKey);
+	}
+	toList(result) {
+		if (Array.isArray(result)) return {
+			data: result,
+			hasMore: false
+		};
+		return {
+			data: result.data ?? [],
+			hasMore: result.hasMore ?? false
+		};
+	}
+	async listNotebooks(args) {
+		const result = await this.client.get("/api/sessions", { params: {
+			...args.search ? { search: args.search } : {},
+			pagination: {
+				page: args.page ?? 1,
+				limit: args.limit
+			}
+		} });
+		return this.toList(result);
+	}
+	async getNotebook(notebookId) {
+		return this.client.get(`/api/sessions/${encodeURIComponent(notebookId)}`);
+	}
+	async createNotebook(args) {
+		return this.client.post("/api/sessions/create", {
+			...args.name ? { name: args.name } : {},
+			...args.projectId ? { projectId: args.projectId } : {}
+		});
+	}
+	async sendChat(args) {
+		return this.client.post("/api/chat", {
+			...args.notebookId ? { sessionId: args.notebookId } : {},
+			message: args.message,
+			...args.model ? { model: args.model } : {},
+			wait: true
+		});
+	}
+	async getQuest(questId) {
+		return this.client.get(`/api/quests/${encodeURIComponent(questId)}`);
+	}
+	async searchKnowledgeBase(args) {
+		return (await this.client.post("/api/sessions/semantic-search", {
+			query: args.query,
+			topK: args.limit,
+			...args.minSimilarity !== void 0 ? { minSimilarity: args.minSimilarity } : {}
+		})).scores ?? [];
+	}
+	async listFiles(args) {
+		const result = await this.client.get("/api/files/search", { params: {
+			...args.search ? { search: args.search } : {},
+			pagination: {
+				page: args.page ?? 1,
+				limit: args.limit
+			}
+		} });
+		return this.toList(result);
+	}
+	async getFile(fileId) {
+		return this.client.get(`/api/files/${encodeURIComponent(fileId)}`);
+	}
+	/**
+	* Generate a sound effect. Unlike the JSON routes, this one streams raw audio
+	* bytes, so it goes through the axios instance directly to read the response
+	* headers (content type + the persisted-FabFile side channel). On failure the
+	* error body arrives as bytes; {@link decodeArrayBufferErrorBody} restores the
+	* JSON shape so {@link mapApiError} can surface the server's message.
+	*/
+	async generateSoundEffect(args) {
+		try {
+			const response = await this.client.getAxiosInstance().post("/api/ai/sound-effects", {
+				provider: args.provider,
+				text: args.text,
+				...args.durationSeconds !== void 0 ? { durationSeconds: args.durationSeconds } : {},
+				...args.promptInfluence !== void 0 ? { promptInfluence: args.promptInfluence } : {},
+				...args.format ? { format: args.format } : {}
+			}, { responseType: "arraybuffer" });
+			const headerString = (value) => typeof value === "string" ? value : void 0;
+			const saved = String(response.headers["x-b4m-audio-saved"] ?? "") === "true";
+			return {
+				audio: Buffer.from(response.data),
+				contentType: String(response.headers["content-type"] ?? "application/octet-stream"),
+				saved,
+				fabFileId: saved ? headerString(response.headers["x-b4m-audio-fab-file-id"]) : void 0,
+				fileName: saved ? headerString(response.headers["x-b4m-audio-file-name"]) : void 0,
+				fileUrl: saved ? headerString(response.headers["x-b4m-audio-file-url"]) : void 0
+			};
+		} catch (error) {
+			throw decodeArrayBufferErrorBody(error);
+		}
+	}
+	async listProjects(args) {
+		const result = await this.client.get("/api/projects", { params: {
+			...args.search ? { search: args.search } : {},
+			pagination: {
+				page: args.page ?? 1,
+				limit: args.limit
+			}
+		} });
+		return this.toList(result);
+	}
+	async getProject(projectId) {
+		return this.client.get(`/api/projects/${encodeURIComponent(projectId)}`);
+	}
+	/**
+	* GET /api/artifacts takes flat `limit`/`offset` params (not the nested
+	* `pagination` object the session/file/project routes use) and hard-caps
+	* `limit` at 100 via a strict zod parse, so callers must not exceed it.
+	*/
+	async listArtifacts(args) {
+		const result = await this.client.get("/api/artifacts", { params: {
+			...args.search ? { search: args.search } : {},
+			limit: args.limit,
+			offset: args.offset ?? 0
+		} });
+		return {
+			data: result.artifacts ?? [],
+			hasMore: result.pagination?.hasMore ?? false
+		};
+	}
+	async getArtifact(artifactId) {
+		return this.client.get(`/api/artifacts/${encodeURIComponent(artifactId)}`, { params: { includeContent: "true" } });
+	}
+};
+/**
+* Turn an API failure into an actionable, transport-agnostic message. `scope` is
+* the recommended API-key scope for the failing tool. A 403 can come from a
+* missing scope OR from a route-level authorization check (CASL forbidden,
+* suspended account), so the message stays broad rather than asserting a scope
+* gap that may not be the cause.
+*/
+function mapApiError(error, baseURL, scope) {
+	if (isAxiosError(error)) {
+		const status = error.response?.status;
+		if (status === 401) return "authentication failed (run `b4m login` or set B4M_API_KEY)";
+		if (status === 403) {
+			const base = "API key forbidden: check the key's scopes and account access";
+			return scope ? `${base} (recommended scope: ${scope})` : base;
+		}
+		if (status === 429) {
+			const retryAfterSeconds = parseRetryAfterSeconds(error.response?.headers?.["retry-after"]);
+			const base = extractServerMessage(error.response?.data) || "rate limit exceeded";
+			return retryAfterSeconds !== void 0 ? `${base} (retry after ${retryAfterSeconds}s)` : base;
+		}
+		if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT" || /timeout/i.test(error.message)) return `request to Bike4Mind at ${baseURL} timed out`;
+		if (error.code === "ECONNREFUSED" || error.message.includes("ECONNREFUSED")) return `cannot reach Bike4Mind at ${baseURL}`;
+		const serverMsg = extractServerMessage(error.response?.data);
+		if (serverMsg) return serverMsg;
+		return error.message;
+	}
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* A request made with `responseType: 'arraybuffer'` also decodes its error body
+* as bytes, so a JSON `{ error }` payload reaches us as a Buffer that
+* {@link mapApiError} can't read. Decode it back to a parsed object in place so
+* the server's message survives; leave a non-JSON body untouched.
+*/
+function decodeArrayBufferErrorBody(error) {
+	if (!isAxiosError(error) || !error.response) return error;
+	const { data } = error.response;
+	if (typeof data === "string") {
+		try {
+			error.response.data = JSON.parse(data);
+		} catch {}
+		return error;
+	}
+	const bytes = Buffer.isBuffer(data) ? data : data instanceof ArrayBuffer ? Buffer.from(data) : ArrayBuffer.isView(data) ? Buffer.from(data.buffer, data.byteOffset, data.byteLength) : void 0;
+	if (!bytes) return error;
+	try {
+		error.response.data = JSON.parse(bytes.toString("utf8"));
+	} catch {}
+	return error;
+}
+/**
+* Normalize a Retry-After header (RFC 7231: either delta-seconds or an HTTP-date)
+* to a whole, non-negative number of seconds. Returns undefined when the header is
+* absent or parses as neither, so callers can omit the retry hint entirely.
+*/
+function parseRetryAfterSeconds(value) {
+	if (value === void 0 || value === null) return void 0;
+	const raw = String(value).trim();
+	if (/^\d+$/.test(raw)) return Number(raw);
+	const dateMs = Date.parse(raw);
+	if (Number.isNaN(dateMs)) return void 0;
+	return Math.max(0, Math.ceil((dateMs - Date.now()) / 1e3));
+}
+/** Pull a human-readable message out of a JSON error body (`error` or `message` field). */
+function extractServerMessage(data) {
+	if (data && typeof data === "object") {
+		const record = data;
+		if (typeof record.error === "string") return record.error;
+		if (typeof record.message === "string") return record.message;
+	}
+}
+//#endregion
+//#region src/mcp/tools.ts
+const TOOL_META = [
+	{
+		name: "list_notebooks",
+		title: "List notebooks",
+		description: "List the caller's Bike4Mind notebooks (sessions).",
+		scope: "notebooks:read"
+	},
+	{
+		name: "get_notebook",
+		title: "Get notebook",
+		description: "Fetch a single notebook by id.",
+		scope: "notebooks:read"
+	},
+	{
+		name: "create_notebook",
+		title: "Create notebook",
+		description: "Create a new notebook, optionally inside a project. Defaults the name to \"New Notebook\" when omitted.",
+		scope: "notebooks:write"
+	},
+	{
+		name: "send_message",
+		title: "Send message",
+		description: "Send a chat message and wait for the assistant reply.",
+		scope: "ai:chat"
+	},
+	{
+		name: "search_knowledge_base",
+		title: "Search knowledge base",
+		description: "Semantic search across the caller's notebooks.",
+		scope: "notebooks:read"
+	},
+	{
+		name: "list_files",
+		title: "List files",
+		description: "Search the caller's files.",
+		scope: "files:read"
+	},
+	{
+		name: "get_file",
+		title: "Get file",
+		description: "Fetch a file's metadata and a signed download URL.",
+		scope: "files:read"
+	},
+	{
+		name: "generate_sound_effect",
+		title: "Generate sound effect",
+		description: "Generate a sound effect from a text description. Returns the saved audio file (with a signed download URL) when the caller keeps generated audio, otherwise the audio inline.",
+		scope: "ai:generate"
+	}
+];
+TOOL_META.map((t) => t.name);
+const listNotebooksShape = {
+	search: z$1.string().optional().describe("Filter notebooks by name/content"),
+	limit: z$1.number().int().min(1).max(100).default(25).describe("Maximum notebooks to return"),
+	page: z$1.number().int().min(1).default(1).describe("1-based page number; request the next page when hasMore is true")
+};
+const getNotebookShape = { notebookId: z$1.string().describe("The notebook (session) id") };
+const createNotebookShape = {
+	name: z$1.string().optional().describe("Name for the new notebook"),
+	projectId: z$1.string().optional().describe("Project to create the notebook in")
+};
+const sendMessageShape = {
+	message: z$1.string().describe("The message to send"),
+	notebookId: z$1.string().optional().describe("Notebook to send to; defaults to the most recent"),
+	model: z$1.string().optional().describe("Model id to use; defaults to the instance default")
+};
+const searchKnowledgeBaseShape = {
+	query: z$1.string().describe("The search query"),
+	limit: z$1.number().int().min(1).max(100).default(10).describe("Maximum results to return"),
+	minSimilarity: z$1.number().min(0).max(1).optional().describe("Minimum cosine similarity threshold")
+};
+const listFilesShape = {
+	search: z$1.string().optional().describe("Filter files by name/content"),
+	limit: z$1.number().int().min(1).max(100).default(25).describe("Maximum files to return"),
+	page: z$1.number().int().min(1).default(1).describe("1-based page number; request the next page when hasMore is true")
+};
+const getFileShape = { fileId: z$1.string().describe("The file id") };
+const generateSoundEffectShape = {
+	text: z$1.string().min(1).max(1e3).describe("Text description of the sound effect to generate"),
+	provider: z$1.enum(["elevenlabs"]).default("elevenlabs").describe("Sound-generation provider"),
+	durationSeconds: z$1.number().min(.5).max(30).optional().describe("Length of the sound in seconds (0.5-30); omit to let the provider choose"),
+	promptInfluence: z$1.number().min(0).max(1).optional().describe("How strictly to follow the prompt (0 = loose, 1 = strict)"),
+	format: z$1.string().optional().describe("Provider output encoding token, e.g. mp3_44100_128")
+};
+function notebookSummary(n) {
+	return {
+		id: n.id,
+		name: n.name,
+		model: n.lastUsedModel ?? void 0,
+		createdAt: n.createdAt ?? n.firstCreated,
+		updatedAt: n.updatedAt ?? n.lastUpdated
+	};
+}
+async function listNotebooks(client, args) {
+	const { data, hasMore } = await client.listNotebooks(args);
+	return {
+		notebooks: data.map(notebookSummary),
+		hasMore
+	};
+}
+async function getNotebook(client, args) {
+	return client.getNotebook(args.notebookId);
+}
+async function createNotebook(client, args) {
+	return client.createNotebook({
+		...args,
+		name: args.name ?? "New Notebook"
+	});
+}
+async function sendMessage(client, args) {
+	const res = await client.sendChat(args);
+	const questId = res.id;
+	let notebookId = args.notebookId;
+	if (!notebookId) try {
+		notebookId = (await client.getQuest(questId)).sessionId;
+	} catch {
+		notebookId = void 0;
+	}
+	const reply = res.responses && res.responses.length > 0 ? res.responses.join("\n\n") : res.response ?? "";
+	return {
+		notebookId,
+		questId,
+		reply,
+		model: res.model
+	};
+}
+async function searchKnowledgeBase(client, args) {
+	return { results: await client.searchKnowledgeBase(args) };
+}
+async function listFiles(client, args) {
+	const { data, hasMore } = await client.listFiles(args);
+	return {
+		files: data,
+		hasMore
+	};
+}
+async function getFile(client, args) {
+	return client.getFile(args.fileId);
+}
+async function generateSoundEffect(client, args) {
+	const { audio, contentType, saved, fabFileId, fileName, fileUrl } = await client.generateSoundEffect(args);
+	const base = {
+		provider: args.provider,
+		contentType,
+		byteLength: audio.length
+	};
+	if (saved && fabFileId && fileUrl) return {
+		...base,
+		saved: true,
+		file: {
+			id: fabFileId,
+			fileName,
+			fileUrl
+		}
+	};
+	return {
+		...base,
+		saved: false,
+		audioBase64: audio.toString("base64")
+	};
+}
+function toResult(value) {
+	const structuredContent = value && typeof value === "object" && !Array.isArray(value) ? value : { result: value };
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(value, null, 2)
+		}],
+		structuredContent
+	};
+}
+function errorResult(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+/**
+* Render a {@link SoundEffectOutcome} as an MCP result. A persisted file becomes
+* a JSON metadata result (carrying the signed URL), exactly like get_file. When
+* the audio was not persisted, it is returned inline as an `audio` content block
+* so the bytes are not lost; the base64 is kept out of structuredContent to avoid
+* duplicating a potentially large payload.
+*/
+function soundEffectResult(outcome) {
+	if (outcome.saved) return toResult({
+		saved: true,
+		provider: outcome.provider,
+		contentType: outcome.contentType,
+		byteLength: outcome.byteLength,
+		file: outcome.file
+	});
+	const { audioBase64, ...meta } = outcome;
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(meta, null, 2)
+		}, {
+			type: "audio",
+			data: audioBase64,
+			mimeType: outcome.contentType
+		}],
+		structuredContent: meta
+	};
+}
+/**
+* Register the Bike4Mind MCP tools on `server`. Each handler is wrapped so an
+* API failure becomes a structured `isError` result carrying a friendly message
+* (see {@link mapApiError}) rather than throwing across the transport.
+*/
+function registerTools(server, client) {
+	const baseURL = client.baseURL;
+	const meta = (name) => TOOL_META.find((t) => t.name === name);
+	const run = async (scope, fn) => {
+		try {
+			return toResult(await fn());
+		} catch (err) {
+			return errorResult(mapApiError(err, baseURL, scope));
+		}
+	};
+	server.registerTool("list_notebooks", {
+		title: meta("list_notebooks").title,
+		description: meta("list_notebooks").description,
+		inputSchema: listNotebooksShape
+	}, (args) => run("notebooks:read", () => listNotebooks(client, args)));
+	server.registerTool("get_notebook", {
+		title: meta("get_notebook").title,
+		description: meta("get_notebook").description,
+		inputSchema: getNotebookShape
+	}, (args) => run("notebooks:read", () => getNotebook(client, args)));
+	server.registerTool("create_notebook", {
+		title: meta("create_notebook").title,
+		description: meta("create_notebook").description,
+		inputSchema: createNotebookShape
+	}, (args) => run("notebooks:write", () => createNotebook(client, args)));
+	server.registerTool("send_message", {
+		title: meta("send_message").title,
+		description: meta("send_message").description,
+		inputSchema: sendMessageShape
+	}, (args) => run("ai:chat", () => sendMessage(client, args)));
+	server.registerTool("search_knowledge_base", {
+		title: meta("search_knowledge_base").title,
+		description: meta("search_knowledge_base").description,
+		inputSchema: searchKnowledgeBaseShape
+	}, (args) => run("notebooks:read", () => searchKnowledgeBase(client, args)));
+	server.registerTool("list_files", {
+		title: meta("list_files").title,
+		description: meta("list_files").description,
+		inputSchema: listFilesShape
+	}, (args) => run("files:read", () => listFiles(client, args)));
+	server.registerTool("get_file", {
+		title: meta("get_file").title,
+		description: meta("get_file").description,
+		inputSchema: getFileShape
+	}, (args) => run("files:read", () => getFile(client, args)));
+	server.registerTool("generate_sound_effect", {
+		title: meta("generate_sound_effect").title,
+		description: meta("generate_sound_effect").description,
+		inputSchema: generateSoundEffectShape
+	}, async (args) => {
+		try {
+			return soundEffectResult(await generateSoundEffect(client, args));
+		} catch (err) {
+			return errorResult(mapApiError(err, baseURL, "ai:generate"));
+		}
+	});
+}
+//#endregion
+//#region src/mcp/resources.ts
+const LIST_LIMIT = 100;
+/**
+* Decode a URI-template variable, tolerating an id that was never encoded.
+*
+* The SDK reaches a read callback via `new URL(uri)` -> `uriTemplate.match(url.toString())`,
+* and `URL.toString()` percent-encodes, so an id we listed with `encodeURIComponent`
+* arrives already encoded and must be decoded back before it hits a REST path. A
+* hand-crafted uri with a malformed escape (e.g. `%zz`) would make `decodeURIComponent`
+* throw a bare `URIError` past `mapApiError`; fall back to the raw value instead.
+*/
+function safeDecode(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+/**
+* Register one `b4m://<name>/{id}` JSON resource.
+*
+* `list` degrades to an empty array on failure rather than throwing: the SDK's
+* resources/list handler awaits every registered template's list callback in one
+* unguarded loop, so a throw here would also blank every sibling template. `read`
+* still throws - a single read failure has no fan-out.
+*/
+function registerJsonResource(server, client, spec) {
+	server.registerResource(spec.name, new ResourceTemplate(`b4m://${spec.name}/{id}`, { list: async () => {
+		try {
+			return { resources: (await spec.list()).map((item) => {
+				const label = spec.label(item) ?? spec.id(item);
+				return {
+					uri: `b4m://${spec.name}/${encodeURIComponent(spec.id(item))}`,
+					name: label,
+					title: label,
+					mimeType: "application/json"
+				};
+			}) };
+		} catch (err) {
+			logger.error(`mcp: listing ${spec.name} resources failed: ${mapApiError(err, client.baseURL, spec.scope)}`);
+			return { resources: [] };
+		}
+	} }), {
+		title: spec.title,
+		description: spec.description,
+		mimeType: "application/json"
+	}, async (uri, variables) => {
+		const id = safeDecode(String(variables.id));
+		try {
+			const record = await spec.read(id);
+			return { contents: [{
+				uri: uri.href,
+				mimeType: "application/json",
+				text: JSON.stringify(record, null, 2)
+			}] };
+		} catch (err) {
+			throw new Error(mapApiError(err, client.baseURL, spec.scope));
+		}
+	});
+}
+/**
+* Register `b4m://agent-quest`: the machine-readable invitation to The Open Door.
+*
+* A fixed URI rather than a `ResourceTemplate` - there is exactly one manifest, so
+* there is nothing to list or address by id. It is also the only resource here that
+* needs no API call and no credentials: the document is a constant in
+* @bike4mind/common, shared with the public HTTP route that serves it
+* (apps/client/pages/api/agent-quest/manifest.ts). That means an agent can read the
+* invitation before it has an API key - which is the point, since the quest is how
+* it earns one.
+*/
+function registerAgentQuest(server) {
+	server.registerResource(AGENT_QUEST_ID, AGENT_QUEST_MCP_URI, {
+		title: AGENT_QUEST_MANIFEST.title,
+		description: AGENT_QUEST_MANIFEST.summary,
+		mimeType: "application/json"
+	}, (uri) => ({ contents: [{
+		uri: uri.href,
+		mimeType: "application/json",
+		text: JSON.stringify(AGENT_QUEST_MANIFEST, null, 2)
+	}] }));
+}
+/**
+* Register the Bike4Mind MCP resources: the four templates below, each served as
+* application/json and backed by its REST list/read pair, plus the credential-free
+* `b4m://agent-quest` manifest.
+*/
+function registerResources(server, client) {
+	registerAgentQuest(server);
+	registerJsonResource(server, client, {
+		name: "notebook",
+		title: "Notebook",
+		description: "A Bike4Mind notebook (session)",
+		scope: "notebooks:read",
+		list: async () => (await client.listNotebooks({ limit: LIST_LIMIT })).data,
+		id: (n) => n.id,
+		label: (n) => n.name,
+		read: (id) => client.getNotebook(id)
+	});
+	registerJsonResource(server, client, {
+		name: "file",
+		title: "File",
+		description: "A Bike4Mind file: metadata plus a signed download URL",
+		scope: "files:read",
+		list: async () => (await client.listFiles({ limit: LIST_LIMIT })).data,
+		id: (f) => f.id,
+		label: (f) => f.fileName,
+		read: (id) => client.getFile(id)
+	});
+	registerJsonResource(server, client, {
+		name: "project",
+		title: "Project",
+		description: "A Bike4Mind project",
+		scope: "projects:read",
+		list: async () => (await client.listProjects({ limit: LIST_LIMIT })).data,
+		id: (p) => p.id,
+		label: (p) => p.name,
+		read: (id) => client.getProject(id)
+	});
+	registerJsonResource(server, client, {
+		name: "artifact",
+		title: "Artifact",
+		description: "A Bike4Mind artifact: metadata plus its current content",
+		list: async () => (await client.listArtifacts({ limit: LIST_LIMIT })).data,
+		id: (a) => a.id,
+		label: (a) => a.title,
+		read: (id) => client.getArtifact(id)
+	});
+}
+//#endregion
+//#region src/mcp/server.ts
+/**
+* Build a fully-configured Bike4Mind MCP server: the tools, the four resource
+* templates (`b4m://notebook/{id}`, `b4m://file/{id}`, `b4m://project/{id}`,
+* `b4m://artifact/{id}`) backed by a {@link B4mApiClient} bound to the given
+* endpoint and credentials, and the credential-free `b4m://agent-quest` manifest.
+* Tool listing never touches the network - only tool/resource *calls* hit the API -
+* so a server built with an unreachable endpoint still advertises its full
+* capability set.
+*/
+function buildMcpServer(options) {
+	const client = new B4mApiClient(options.baseURL, options.configStore, options.apiKey);
+	const server = new McpServer({
+		name: "bike4mind",
+		version: options.version
+	}, { capabilities: {
+		tools: {},
+		resources: {}
+	} });
+	registerTools(server, client);
+	registerResources(server, client);
+	return server;
+}
+//#endregion
+//#region src/mcp/serve.ts
+/**
+* `b4m mcp serve` - expose Bike4Mind as an MCP server.
+*
+* Two transports: stdio (default, for Claude Desktop and other local clients)
+* and stateless streamable HTTP (`--http`). Auth precedence is
+* `--api-key` > `B4M_API_KEY` > the stored OAuth JWT; the endpoint is
+* `B4M_API_URL` > `--api-url` > the CLI's configured backend.
+*
+* Transport contract for stdio: stdout carries the JSON-RPC frame stream and
+* NOTHING else, so all diagnostics are forced to stderr before ANY other work
+* runs (mirrors the acp command's captureStdout - see src/commands/acpCommand.ts).
+*
+* HTTP mode is deliberately loopback-only (binds 127.0.0.1) with no per-request
+* auth of its own - it trusts anything that can reach the socket, so it must not
+* be exposed on a routable interface. DNS-rebinding protection is on as defense
+* in depth against a browser being tricked into posting to the local port.
+*/
+const HTTP_PATH = "/mcp";
+/**
+* Capture the real stdout for the JSON-RPC frame stream, then redirect
+* everything else - `console.*` and any stray `process.stdout.write` deep in the
+* stack - to stderr. A single unrelated byte on stdout corrupts a frame, so the
+* whole channel is closed rather than trusting no dependency ever prints.
+*/
+function captureStdout() {
+	const writeToRealStdout = process.stdout.write.bind(process.stdout);
+	const toStderr = (...args) => {
+		process.stderr.write(args.map(String).join(" ") + "\n");
+	};
+	console.log = toStderr;
+	console.info = toStderr;
+	console.debug = toStderr;
+	process.stdout.write = process.stderr.write.bind(process.stderr);
+	return writeToRealStdout;
+}
+function resolveBaseURL(options, configStore) {
+	const explicit = process.env.B4M_API_URL ?? options.apiUrl;
+	if (explicit) {
+		const parsed = parseApiUrl(explicit);
+		if ("error" in parsed) throw new Error(`Invalid API URL: ${parsed.error}`);
+		return Promise.resolve(parsed.url);
+	}
+	return configStore.getApiConfig().then((apiConfig) => requireApiUrl(apiConfig));
+}
+async function serveStdio(buildOptions, writeFrame) {
+	const server = buildMcpServer(buildOptions);
+	const stdout = new Writable({ write(chunk, _encoding, callback) {
+		if (writeFrame(chunk)) {
+			callback();
+			return;
+		}
+		process.stdout.once("drain", () => callback());
+	} });
+	const transport = new StdioServerTransport(process.stdin, stdout);
+	await server.connect(transport);
+	await new Promise((resolve) => {
+		process.stdin.once("end", resolve);
+		process.stdin.once("close", resolve);
+	});
+}
+async function handleHttpRequest(req, res, buildOptions, port) {
+	const server = buildMcpServer(buildOptions);
+	const transport = new StreamableHTTPServerTransport({
+		sessionIdGenerator: void 0,
+		enableJsonResponse: true,
+		enableDnsRebindingProtection: true,
+		allowedHosts: [`127.0.0.1:${port}`, `localhost:${port}`],
+		allowedOrigins: [`http://127.0.0.1:${port}`, `http://localhost:${port}`]
+	});
+	let released = false;
+	const release = () => {
+		if (released) return;
+		released = true;
+		transport.close();
+		server.close();
+	};
+	res.on("finish", release);
+	res.on("close", release);
+	await server.connect(transport);
+	await transport.handleRequest(req, res);
+}
+async function serveHttp(buildOptions, port) {
+	const httpServer = createServer((req, res) => {
+		if (new URL(req.url ?? "/", `http://localhost:${port}`).pathname !== HTTP_PATH) {
+			res.writeHead(404, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: `Not found. The MCP endpoint is ${HTTP_PATH}.` }));
+			return;
+		}
+		handleHttpRequest(req, res, buildOptions, port).catch((err) => {
+			logger.error("MCP HTTP request failed", err);
+			if (!res.headersSent) {
+				res.writeHead(500, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({
+					jsonrpc: "2.0",
+					error: {
+						code: -32603,
+						message: "Internal server error"
+					},
+					id: null
+				}));
+			}
+		});
+	});
+	await new Promise((resolve, reject) => {
+		httpServer.once("error", reject);
+		httpServer.listen(port, "127.0.0.1", () => resolve());
+	});
+	process.stderr.write(`Bike4Mind MCP server listening on http://127.0.0.1:${port}${HTTP_PATH}\n`);
+	await new Promise((resolve) => {
+		const shutdown = () => httpServer.close(() => resolve());
+		process.once("SIGINT", shutdown);
+		process.once("SIGTERM", shutdown);
+	});
+}
+async function handleMcpServeCommand(options) {
+	const writeFrame = options.http ? void 0 : captureStdout();
+	const configStore = new ConfigStore();
+	const buildOptions = {
+		baseURL: await resolveBaseURL(options, configStore),
+		apiKey: options.apiKey ?? process.env.B4M_API_KEY,
+		configStore,
+		version: options.version
+	};
+	if (writeFrame) await serveStdio(buildOptions, writeFrame);
+	else await serveHttp(buildOptions, options.port ?? 7e3);
+}
+//#endregion
+export { handleMcpServeCommand };