@bike4mind/cli 2.0.0 → 3.0.0

package/dist/serve-BaHzVbcm.mjs

@@ -0,0 +1,1511 @@
+#!/usr/bin/env node
+import { A as BRIEFCASE_CATALOG_QUERIES, At as ttsBase64ResponseSchema, B as ImageModels, C as AGENT_QUEST_ID, L as DEFAULT_TTS_PROVIDER, M as BriefcasePromptIdSchema, Mt as ttsResponseTooLargeSchema, Ot as supportedVoiceGenerationVendor, St as replacePromptVariables, T as AGENT_QUEST_MCP_URI, V as ImagePromptResolutionSchema, Y as PROMPT_TEXT_MAX, _ as logger, g as parseApiUrl, h as NotAuthenticatedError, jt as ttsRequestSchema, k as ArtifactTypeSchema, nt as VisibilitySchema, ot as buildPromptContext, t as ConfigStore, u as requireApiUrl, ut as generatedAudioResponseSchema, w as AGENT_QUEST_MANIFEST, xt as questReplyText, yt as joinReplySlots, z as GENERATED_IMAGE_EXTENSION_RE } from "./ConfigStore-51UaP9pJ.mjs";
+import { a as ApiClient, i as parseRetryAfterSeconds, o as isProviderKeyFailure, r as createClient, t as B4mApiError } from "./dist-BsG2Hlp-.mjs";
+import { z as z$1 } from "zod";
+import { isAxiosError } from "axios";
+import { createHash, randomUUID } from "node:crypto";
+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";
+import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+//#region src/mcp/b4mApiClient.ts
+const NOTEBOOK_ID_PATTERN = /^[a-f0-9]{24}$/i;
+const STOP_REPLY_TIMEOUT_MS = 1e4;
+/**
+* An empty or dot-segment id collapses `/api/sessions/{id}` to `/api/sessions`, whose DELETE wipes every
+* notebook the caller owns, so write paths refuse anything that is not an ObjectId before any request.
+*/
+function writableNotebookId(notebookId) {
+	if (!NOTEBOOK_ID_PATTERN.test(notebookId)) throw new Error(`Invalid notebook id: ${JSON.stringify(notebookId)}`);
+	return notebookId;
+}
+/**
+* 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.
+*
+* Operations with a public contract go through `@bike4mind/sdk` (`this.sdk`), whose fetch is the
+* ApiClient's, so auth and refresh are shared. The axios `this.client` calls are routes with no public
+* contract, plus four that do have one but whose v1 shape would change the MCP output: the session and
+* project lists (v1 pages by cursor, the tools by page number) and getFile/getProject (the tools return the
+* whole document; v1 is a narrower snake_case resource).
+*/
+var B4mApiClient = class {
+	constructor(baseURL, configStore, apiKey) {
+		this.baseURL = baseURL;
+		this.client = new ApiClient(baseURL, configStore, apiKey);
+		this.sdk = createClient({
+			baseUrl: baseURL,
+			fetch: this.client.fetch
+		});
+	}
+	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.sdk.call("getSession", { params: { id: notebookId } });
+	}
+	async createNotebook(args) {
+		return this.sdk.call("createSession", { body: {
+			name: args.name,
+			...args.projectId ? { projectId: args.projectId } : {},
+			...args.dataLakeId ? { dataLakeId: args.dataLakeId } : {}
+		} });
+	}
+	async renameNotebook(notebookId, name) {
+		return this.sdk.call("updateSession", {
+			params: { id: writableNotebookId(notebookId) },
+			body: { name }
+		});
+	}
+	/** Returns the new (cloned) notebook. */
+	async cloneNotebook(notebookId) {
+		return this.sdk.call("cloneSession", {
+			params: { id: writableNotebookId(notebookId) },
+			body: {}
+		});
+	}
+	async deleteNotebook(notebookId) {
+		return this.sdk.call("deleteSession", {
+			params: { id: writableNotebookId(notebookId) },
+			redirect: "manual"
+		});
+	}
+	/** GET /api/v1/data-lakes is cursor-paginated (`{ data, next_cursor }` body), so `toList` does not apply. */
+	async listDataLakes(args) {
+		const result = await this.sdk.call("listDataLakes", { query: {
+			limit: args.limit,
+			...args.cursor ? { cursor: args.cursor } : {}
+		} });
+		return {
+			data: result.data ?? [],
+			nextCursor: result.next_cursor ?? null
+		};
+	}
+	async sendChat(args) {
+		const body = {
+			...args.notebookId ? { sessionId: args.notebookId } : { newConversation: true },
+			message: args.message,
+			...args.model ? { model: args.model } : {},
+			...args.systemPrompt ? { systemPrompt: args.systemPrompt } : {},
+			wait: false
+		};
+		return this.sdk.call("sendChatMessage", { body });
+	}
+	async getQuest(questId) {
+		return await this.sdk.call("getQuest", { params: { id: questId } });
+	}
+	/** Stop one generating turn. A server that predates `questId` stops the notebook's latest turn. */
+	async stopReply(notebookId, questId) {
+		return this.client.post(`/api/sessions/${writableNotebookId(notebookId)}/chat/stop-reply`, { questId }, { timeout: STOP_REPLY_TIMEOUT_MS });
+	}
+	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. The SDK requests base64 and rebuilds an old server's raw-bytes answer. */
+	async generateSoundEffect(args) {
+		const body = {
+			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 } : {}
+		};
+		return generatedAudioResponseSchema.parse(await this.sdk.soundEffects(body));
+	}
+	async synthesizeSpeech(args) {
+		const result = await this.sdk.tts(args);
+		if (result.kind === "audio") return {
+			kind: "audio",
+			data: ttsBase64ResponseSchema.parse(result.data)
+		};
+		const oversized = ttsResponseTooLargeSchema.parse(result.data);
+		const fallbackFrom = supportedVoiceGenerationVendor.safeParse(result.fallbackFrom);
+		return {
+			kind: "saved-too-large",
+			data: {
+				...oversized,
+				fabFileId: result.data.fabFileId
+			},
+			...fallbackFrom.success ? { fallbackFrom: fallbackFrom.data } : {}
+		};
+	}
+	async generateImage(args) {
+		const body = {
+			prompt: args.prompt,
+			model: args.model,
+			...args.size ? { size: args.size } : {},
+			...args.notebookId ? { sessionId: args.notebookId } : {},
+			...args.projectId ? { projectId: args.projectId } : {},
+			...args.promptResolution ? { prompt_resolution: args.promptResolution } : {}
+		};
+		return await this.sdk.call("generateImage", { body });
+	}
+	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)}`);
+	}
+	async createProject(args) {
+		const project = await this.sdk.call("createProject", { body: {
+			name: args.name,
+			description: args.description,
+			...args.sessionIds?.length ? { session_ids: args.sessionIds } : {},
+			...args.fileIds?.length ? { file_ids: args.fileIds } : {}
+		} });
+		return {
+			id: project.id,
+			name: project.name,
+			description: project.description,
+			sessionIds: project.session_ids,
+			fileIds: project.file_ids,
+			createdAt: project.created_at ?? void 0,
+			updatedAt: project.updated_at ?? void 0
+		};
+	}
+	/**
+	* 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" } });
+	}
+	/**
+	* The caller's own most recent publication of an artifact, or null. The route is
+	* owner-scoped for `sourceArtifactId`, so another user's page never matches.
+	*/
+	async findPublishedArtifact(artifactId) {
+		return (await this.client.get("/api/publish/artifacts", { params: {
+			sourceArtifactId: artifactId,
+			limit: 1
+		} })).artifacts?.[0] ?? null;
+	}
+	/** POST /api/publish/artifact/upload-url: opens a publish draft and mints one upload URL per file. */
+	async requestPublishUpload(request) {
+		return this.client.post("/api/publish/artifact/upload-url", request);
+	}
+	/**
+	* PUT one draft file to the URL upload-url minted. Plain fetch, never the app
+	* client: that client injects auth headers, which break an S3 presigned
+	* signature. Self-host mints a relative proxy URL, so resolve against baseURL.
+	*/
+	async uploadPublishDraftFile(uploadUrl, body, mimeType) {
+		const res = await fetch(new URL(uploadUrl, this.baseURL), {
+			method: "PUT",
+			headers: { "Content-Type": mimeType },
+			body
+		});
+		if (!res.ok) throw new Error(`publish upload failed (${res.status})`);
+	}
+	/** POST /api/publish/artifact/finalize: validates the uploaded draft and makes it live. */
+	async finalizePublish(draftId) {
+		return this.client.post("/api/publish/artifact/finalize", { draftId });
+	}
+	/**
+	* POST /api/briefcase/catalog: a key -> prompts map, one entry per query key.
+	*
+	* The route runs csrfProtection, which exempts API-key requests but rejects a
+	* login (JWT bearer) request that carries no Origin - and Node sends none. CSRF
+	* defends browsers, so a non-browser client naming the backend's own origin is
+	* the intended pass, not a bypass.
+	*/
+	async getBriefcaseCatalog(queries) {
+		return (await this.client.post("/api/briefcase/catalog", { queries }, { headers: { Origin: new URL(this.baseURL).origin } })).catalog;
+	}
+	async getBriefcasePrompt(promptId) {
+		return (await this.client.get(`/api/briefcase/prompts/${encodeURIComponent(promptId)}`)).prompt;
+	}
+};
+/**
+* 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 (error instanceof NotAuthenticatedError) return "not authenticated: no credential configured (set B4M_API_KEY or run `b4m login`)";
+	const failure = httpFailure(error);
+	if (!failure) return error instanceof Error ? error.message : String(error);
+	const { status, data } = failure;
+	if (status === 401) {
+		const providerKeyMessage = providerKeyFailureMessage(data);
+		if (providerKeyMessage) return providerKeyMessage;
+		return "authentication failed (run `b4m login` or set B4M_API_KEY)";
+	}
+	if (status === 403) {
+		if (data?.code === "FEATURE_DISABLED") return "feature disabled on this Bike4Mind instance (ask an admin to enable it)";
+		if (apiErrorCode(error) === "slug_owned_by_other") return extractServerMessage(data) ?? "this publish slug belongs to another publisher";
+		const serverMessage = extractServerMessage(data);
+		if (serverMessage && /CSRF|request origin/i.test(serverMessage)) return serverMessage;
+		if (serverMessage && /own user scope/i.test(serverMessage)) return `${serverMessage} (publish_artifact only publishes artifacts you own)`;
+		const base = "API key forbidden: check the key's scopes and account access";
+		return scope ? `${base} (recommended scope: ${scope})` : base;
+	}
+	if (status === 404 && error instanceof B4mApiError && !extractServerMessage(data)) return `the Bike4Mind server at ${baseURL} does not have this API route; it likely predates this CLI (upgrade the server or use an older CLI)`;
+	if (status === 429) {
+		const retryAfterSeconds = apiErrorRetryAfterSeconds(error);
+		const base = extractServerMessage(data) || "rate limit exceeded";
+		return retryAfterSeconds !== void 0 ? `${base} (retry after ${retryAfterSeconds}s)` : base;
+	}
+	if (isAxiosError(error)) {
+		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(data);
+	if (serverMsg) return serverMsg;
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Status and body of an HTTP failure from either transport: a `B4mApiError` from the SDK calls or an
+* AxiosError from the axios ones (with no status when the request never got a response). Undefined for
+* anything else.
+*/
+function httpFailure(error) {
+	if (error instanceof B4mApiError) return {
+		status: error.status,
+		data: error.body
+	};
+	if (isAxiosError(error)) return {
+		status: error.response?.status,
+		data: error.response?.data
+	};
+}
+/** The machine-readable `code` a route put on its error body, when it set one. */
+function apiErrorCode(error) {
+	const data = httpFailure(error)?.data;
+	if (!data || typeof data !== "object") return void 0;
+	const code = data.code;
+	return typeof code === "string" ? code : void 0;
+}
+/** The HTTP status of a failed API call from either transport. */
+function apiErrorStatus(error) {
+	return httpFailure(error)?.status;
+}
+/** The Retry-After of a failed API call from either transport, in seconds. */
+function apiErrorRetryAfterSeconds(error) {
+	if (error instanceof B4mApiError) return error.retryAfterSeconds;
+	return isAxiosError(error) ? parseRetryAfterSeconds(error.response?.headers?.["retry-after"]) : void 0;
+}
+/** 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;
+	}
+}
+function providerKeyFailureMessage(data) {
+	if (!isProviderKeyFailure(data)) return void 0;
+	return `${extractServerMessage(data) ?? "the AI provider could not be used"} (configure or fix the provider API key in Bike4Mind; this is not a Bike4Mind login problem)`;
+}
+//#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 or grounded in a data lake (dataLakeId, see list_lakes). Defaults the name to \"New Notebook\" when omitted.",
+		scope: "notebooks:write"
+	},
+	{
+		name: "rename_notebook",
+		title: "Rename notebook",
+		description: "Rename a notebook.",
+		scope: "notebooks:write"
+	},
+	{
+		name: "clone_notebook",
+		title: "Clone notebook",
+		description: "Clone a notebook into a new one; returns the new notebook.",
+		scope: "notebooks:write"
+	},
+	{
+		name: "delete_notebook",
+		title: "Delete notebook",
+		description: "Permanently delete a notebook and the files its owner uploaded to it; this cannot be undone through the API. Requires confirm: true. On a conflict (409) nothing was deleted, so retry.",
+		scope: "notebooks:write"
+	},
+	{
+		name: "list_projects",
+		title: "List projects",
+		description: "List the Bike4Mind projects the caller can access, including ones shared with them.",
+		scope: "projects:read"
+	},
+	{
+		name: "get_project",
+		title: "Get project",
+		description: "Fetch a single project by id.",
+		scope: "projects:read"
+	},
+	{
+		name: "create_project",
+		title: "Create project",
+		description: "Create a new project. Pass the returned id as projectId to create_notebook to create notebooks inside it.",
+		scope: "projects:write"
+	},
+	{
+		name: "send_message",
+		title: "Send message",
+		description: "Send a chat message and wait for the assistant reply, reporting progress while it is generated; returns the cited sources (citables) the answer was grounded in. Fails on an errored or stopped turn, and stops the turn when the call is cancelled.",
+		scope: "ai:chat"
+	},
+	{
+		name: "search_knowledge_base",
+		title: "Search knowledge base",
+		description: "Semantic search across the caller's notebooks.",
+		scope: "notebooks:read"
+	},
+	{
+		name: "list_lakes",
+		title: "List data lakes",
+		description: "List the data lakes the caller can reach. Pass a lake's id as dataLakeId to create_notebook to ground a notebook in it.",
+		scope: "datalake: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"
+	},
+	{
+		name: "text_to_speech",
+		title: "Text to speech",
+		description: "Synthesize speech from text. Returns a saved audio file with a signed download URL when available, otherwise audio inline.",
+		scope: "ai:generate"
+	},
+	{
+		name: "generate_image",
+		title: "Generate image",
+		description: "Generate an image from a text prompt and wait for the render. Returns the quest and notebook ids plus each image's file name and download URL. Image names are not file ids and do not work with get_file.",
+		scope: "ai:generate"
+	},
+	{
+		name: "publish_artifact",
+		title: "Publish artifact",
+		description: "Publish an artifact you own to a shareable /p/... link and return its absolute URL. Republishing an artifact updates its existing page and keeps that page's visibility unless you pass one; a first publish defaults to public.",
+		scope: "files:write"
+	}
+];
+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 notebookId = (description) => z$1.string().regex(NOTEBOOK_ID_PATTERN, "notebookId must be a 24-character hex ObjectId").describe(description);
+const getNotebookShape = { notebookId: notebookId("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"),
+	dataLakeId: z$1.string().optional().describe("Data lake id or slug to ground the notebook in (see list_lakes); seeds the lake's retrieval defaults")
+};
+const renameNotebookShape = {
+	notebookId: notebookId("The notebook (session) id"),
+	name: z$1.string().min(1).describe("The new name")
+};
+const cloneNotebookShape = { notebookId: notebookId("The notebook (session) id to clone") };
+const deleteNotebookShape = {
+	notebookId: notebookId("The notebook (session) id to delete"),
+	confirm: z$1.literal(true).describe("Must be true; the delete is permanent")
+};
+const listProjectsShape = {
+	search: z$1.string().optional().describe("Filter projects by name"),
+	limit: z$1.number().int().min(1).max(100).default(25).describe("Maximum projects 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 getProjectShape = { projectId: z$1.string().describe("The project id") };
+const createProjectShape = {
+	name: z$1.string().min(1).describe("Name for the new project; must be unique among your projects"),
+	description: z$1.string().min(1).describe("Short description of the project"),
+	sessionIds: z$1.array(z$1.string()).optional().describe("Notebook (session) ids to add to the project"),
+	fileIds: z$1.array(z$1.string()).optional().describe("File ids to add to the project")
+};
+const sendMessageShape = {
+	message: z$1.string().describe("The message to send"),
+	notebookId: z$1.string().optional().describe("Notebook to send to; omit to start a new notebook (its id is returned as notebookId, pass it back to continue the thread)"),
+	model: z$1.string().optional().describe("Model id to use; defaults to the instance default"),
+	systemPrompt: z$1.string().max(PROMPT_TEXT_MAX).optional().describe("Caller-supplied system-prompt text for this message only; refines but never overrides other guidance")
+};
+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 listLakesShape = {
+	limit: z$1.number().int().min(1).max(100).default(25).describe("Maximum lakes to return"),
+	cursor: z$1.string().optional().describe("Pass back nextCursor from the previous page")
+};
+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")
+};
+const generateImageShape = {
+	prompt: z$1.string().min(1).describe("Text description of the image to generate"),
+	model: z$1.string().default(ImageModels.GPT_IMAGE_2).describe("Image model id, e.g. gpt-image-2"),
+	size: z$1.string().optional().describe("Image size as 'widthxheight', e.g. 1024x1024; omit for the model default"),
+	notebookId: z$1.string().optional().describe("Notebook to add the image to; omit to create a new one"),
+	projectId: z$1.string().optional().describe("Project for the new notebook when notebookId is omitted"),
+	promptResolution: ImagePromptResolutionSchema.optional().describe("'auto' (default) rewrites the prompt against the notebook history; 'literal' sends it as written")
+};
+const publishVisibilitySchema = VisibilitySchema.extract(["public", "private"]);
+const publishArtifactShape = {
+	artifactId: z$1.string().min(1).describe("The artifact id"),
+	visibility: publishVisibilitySchema.optional().describe("Who can open the link: 'public' (anyone) or 'private' (only you); omit to keep an existing page's visibility (a first publish is public)"),
+	title: z$1.string().min(1).max(200).optional().describe("Page title; defaults to the artifact's title")
+};
+const textToSpeechShape = {
+	...ttsRequestSchema.omit({ encoding: true }).shape,
+	text: ttsRequestSchema.shape.text.describe("Text to speak"),
+	provider: ttsRequestSchema.shape.provider.describe(`Speech provider; defaults to ${DEFAULT_TTS_PROVIDER}`),
+	preview: ttsRequestSchema.shape.preview.describe("Skip saving a copy to the file browser")
+};
+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
+	};
+}
+function projectSummary(p) {
+	return {
+		id: p.id,
+		name: p.name,
+		createdAt: p.createdAt
+	};
+}
+function lakeSummary(l) {
+	return {
+		id: l.id,
+		name: l.name,
+		slug: l.slug,
+		description: l.description ?? void 0,
+		builtIn: l.built_in,
+		status: l.status,
+		fileCount: l.file_count
+	};
+}
+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 renameNotebook(client, args) {
+	return notebookSummary(await client.renameNotebook(args.notebookId, args.name));
+}
+async function cloneNotebook(client, args) {
+	return notebookSummary(await client.cloneNotebook(args.notebookId));
+}
+async function deleteNotebook(client, args) {
+	if (args.confirm !== true) throw new Error("delete_notebook requires confirm: true");
+	const { newLastNotebookId } = await client.deleteNotebook(args.notebookId);
+	return {
+		deleted: true,
+		notebookId: args.notebookId,
+		newLastNotebookId
+	};
+}
+async function listProjects(client, args) {
+	const { data, hasMore } = await client.listProjects(args);
+	return {
+		projects: data.map(projectSummary),
+		hasMore
+	};
+}
+async function getProject(client, args) {
+	return client.getProject(args.projectId);
+}
+async function createProject(client, args) {
+	return projectSummary(await client.createProject(args));
+}
+/**
+* Queue a chat turn and poll its quest to completion. A failed (`type: 'error'`) or stopped turn
+* throws, so the tool reports `isError`; a cancelled call makes a best-effort stop of its quest.
+*/
+async function sendMessage(client, args, { intervalMs = CHAT_POLL_INTERVAL_MS, timeoutMs = CHAT_POLL_TIMEOUT_MS, ...poll } = {}) {
+	const ack = await client.sendChat(args);
+	const questId = ack.id;
+	const sessionId = args.notebookId ?? ack.sessionId;
+	const ref = questRef(questId, sessionId);
+	let quest;
+	try {
+		quest = await pollQuest(client, {
+			questId,
+			ref,
+			task: "chat completion",
+			scope: "ai:chat",
+			isFinished: isSettled
+		}, {
+			...poll,
+			timeoutMs,
+			interval: (elapsedMs) => chatPollInterval(elapsedMs, intervalMs)
+		});
+	} catch (err) {
+		if (poll.signal?.aborted && sessionId) await client.stopReply(sessionId, questId).catch((stopErr) => logger.warn(`mcp: stopping the cancelled turn failed (${ref}): ${stopErr instanceof Error ? stopErr.message : String(stopErr)}`));
+		throw err;
+	}
+	const reply = replyText(quest);
+	if (quest.status === "stopped") throw new Error(`chat completion was stopped (${ref})${reply ? `: ${reply}` : ""}`);
+	if (quest.type === "error") {
+		const code = quest.errorCode ? `${quest.errorCode}: ` : "";
+		throw new Error(`${code}${reply || "chat completion failed"} (${ref})`);
+	}
+	const notebookId = sessionId ?? quest.sessionId;
+	const citables = (quest.promptMeta?.citables ?? []).map((c) => ({
+		id: c.id,
+		type: c.type,
+		title: c.title,
+		url: c.url,
+		description: c.description
+	}));
+	return {
+		notebookId,
+		questId,
+		reply,
+		model: ack.model,
+		citables
+	};
+}
+async function searchKnowledgeBase(client, args) {
+	return { results: await client.searchKnowledgeBase(args) };
+}
+async function listLakes(client, args) {
+	const { data, nextCursor } = await client.listDataLakes(args);
+	return {
+		lakes: data.map(lakeSummary),
+		nextCursor
+	};
+}
+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) {
+	return generatedAudioResult(await client.generateSoundEffect(args), { provider: args.provider });
+}
+const IMAGE_POLL_INTERVAL_MS = 2e3;
+const IMAGE_POLL_TIMEOUT_MS = 3e5;
+const CHAT_POLL_INTERVAL_MS = 2e3;
+const CHAT_POLL_FAST_WINDOW_MS = 3e4;
+const CHAT_POLL_SLOW_INTERVAL_MS = 5e3;
+const CHAT_POLL_TIMEOUT_MS = 9e5;
+const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const chatPollInterval = (elapsedMs, intervalMs) => elapsedMs < CHAT_POLL_FAST_WINDOW_MS ? intervalMs : Math.max(intervalMs, CHAT_POLL_SLOW_INTERVAL_MS);
+const isSettled = (q) => q.status === "done" || q.status === "stopped" || q.type === "error";
+const isImageSettled = (q) => isSettled(q) || !q.status && !!q.images?.length;
+const replyText = (q) => questReplyText(q, joinReplySlots) ?? "";
+const questRef = (questId, notebookId) => `quest ${questId}${notebookId ? `, notebook ${notebookId}` : ""}`;
+const isRateLimited = (err) => apiErrorStatus(err) === 429;
+const isPermanentApiError = (err) => {
+	const status = apiErrorStatus(err);
+	return status === 401 || status === 403 || status === 404;
+};
+/** Poll a queued quest until `isFinished`, the timeout, a permanent poll failure, or an abort. */
+async function pollQuest(client, { questId, ref, task, scope, isFinished }, { interval, timeoutMs, sleep = defaultSleep, signal, onProgress, baseURL = "" }) {
+	const started = Date.now();
+	let failures = 0;
+	let retryAfterMs = 0;
+	for (;;) {
+		signal?.throwIfAborted();
+		let quest;
+		try {
+			quest = await client.getQuest(questId);
+			failures = 0;
+			if (isFinished(quest)) return quest;
+		} catch (err) {
+			if (isRateLimited(err)) retryAfterMs = (apiErrorRetryAfterSeconds(err) ?? 0) * 1e3;
+			else {
+				failures += 1;
+				if (isPermanentApiError(err) || failures >= MAX_CONSECUTIVE_POLL_FAILURES) throw new Error(`${mapApiError(err, baseURL, scope)} (${ref}; the ${task} may still complete)`);
+			}
+		}
+		const elapsed = Date.now() - started;
+		if (elapsed >= timeoutMs) throw new Error(`${task} did not finish within ${Math.round(timeoutMs / 1e3)}s (${ref})`);
+		signal?.throwIfAborted();
+		try {
+			await onProgress?.(elapsed, quest);
+		} catch (err) {
+			logger.warn(`mcp: progress notification failed (${ref}): ${err instanceof Error ? err.message : String(err)}`);
+		}
+		const intervalMs = interval(elapsed);
+		await sleep(Math.min(Math.max(intervalMs, retryAfterMs), Math.max(timeoutMs - elapsed, intervalMs)));
+		retryAfterMs = 0;
+	}
+}
+/**
+* Queue an image render and poll its quest to completion. A failed render still
+* resolves `status: 'done'`, so `type: 'error'` (reason in `reply`) is the failure signal.
+* Generated images are not FabFiles, so there is no file id: the quest id is the handle,
+* and each image is its generated-file name plus the URL the quest poll resolves for it
+* (`fileUrl` is a short-lived presigned URL, valid for about an hour).
+*/
+async function generateImage(client, args, { intervalMs = IMAGE_POLL_INTERVAL_MS, timeoutMs = IMAGE_POLL_TIMEOUT_MS, ...poll } = {}) {
+	const ack = await client.generateImage(args);
+	const questId = ack.quest.id;
+	const ref = questRef(questId, ack.quest.sessionId);
+	const quest = await pollQuest(client, {
+		questId,
+		ref,
+		task: "image generation",
+		scope: "ai:generate",
+		isFinished: isImageSettled
+	}, {
+		...poll,
+		timeoutMs,
+		interval: () => intervalMs
+	});
+	if (quest.status === "stopped") throw new Error(`image generation was stopped (${ref})`);
+	if (quest.type === "error") {
+		const code = quest.errorCode ? `${quest.errorCode}: ` : "";
+		throw new Error(`${code}${quest.reply || "image generation failed"} (${ref})`);
+	}
+	const urls = new Map((quest.files ?? []).map((f) => [f.name, f.url]));
+	const images = (quest.images ?? []).filter((name) => GENERATED_IMAGE_EXTENSION_RE.test(name)).map((name) => ({
+		fileName: name,
+		fileUrl: urls.get(name)
+	}));
+	if (images.length === 0) throw new Error(`${quest.reply || "image generation finished without producing an image"} (${ref})`);
+	return {
+		notebookId: quest.sessionId ?? ack.quest.sessionId,
+		questId,
+		model: args.model,
+		enhancedPrompt: ack.enhancedPrompt,
+		images
+	};
+}
+const PUBLISH_INDEX_PATH = "index.html";
+const PUBLISH_INDEX_MIME = "text/html";
+const PUBLISH_TITLE_MAX = 200;
+const PUBLISH_FALLBACK_TITLE = "Shared artifact";
+const PUBLISH_DEFAULT_VISIBILITY = "public";
+const SLUG_TITLE_MAX = 48;
+const SLUG_ARTIFACT_HASH_LENGTH = 8;
+const SLUG_DISCRIMINATOR_LENGTH = 6;
+function slugify(text) {
+	return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, SLUG_TITLE_MAX).replace(/-+$/, "");
+}
+/**
+* Stable per artifact, so republishing updates the same page in place. Artifact
+* ids all share an `artifact_` prefix, so the suffix hashes the whole id rather
+* than taking a prefix of it.
+*/
+function artifactSlug(title, artifactId) {
+	const hash = createHash("sha256").update(artifactId).digest("hex").slice(0, SLUG_ARTIFACT_HASH_LENGTH);
+	return `${slugify(title) || "artifact"}-${hash}`;
+}
+/** The artifact-content doc carries the body as `content`; anything else has none to publish. */
+function artifactContentText(content) {
+	if (!content || typeof content !== "object") return void 0;
+	const text = content.content;
+	return typeof text === "string" && text.trim() ? text : void 0;
+}
+/**
+* Open the draft, retrying once under a discriminated slug when the derived slug
+* already belongs to another publisher (the same fallback the web Share flow uses).
+*/
+async function openPublishDraft(client, request) {
+	try {
+		return await client.requestPublishUpload(request);
+	} catch (err) {
+		if (apiErrorCode(err) !== "slug_owned_by_other") throw err;
+		const discriminator = randomUUID().replace(/-/g, "").slice(0, SLUG_DISCRIMINATOR_LENGTH);
+		return client.requestPublishUpload({
+			...request,
+			slug: `${request.slug}-${discriminator}`
+		});
+	}
+}
+/**
+* Publish an artifact: upload its RAW content and let finalize render it
+* (source.artifactType), so the page matches an in-app publish byte for byte with
+* no CLI-side renderer. An artifact the caller already published (from the app or
+* here) is republished in place at its existing tier/scope/slug, as the in-app
+* update flow does; otherwise it becomes a new user-tier page.
+*/
+async function publishArtifact(client, args) {
+	const { artifact, content } = await client.getArtifact(args.artifactId);
+	const body = artifactContentText(content);
+	if (!body) throw new Error(`artifact ${artifact.id} has no content to publish`);
+	const artifactType = ArtifactTypeSchema.safeParse(artifact.type);
+	if (!artifactType.success) throw new Error(`artifact ${artifact.id} has an unsupported type (${String(artifact.type)})`);
+	if (typeof artifact.userId !== "string") throw new Error(`artifact ${artifact.id} has no owner to publish under`);
+	const storedTitle = typeof artifact.title === "string" ? artifact.title : "";
+	const title = (args.title ?? storedTitle).trim().slice(0, PUBLISH_TITLE_MAX) || PUBLISH_FALLBACK_TITLE;
+	const existing = await client.findPublishedArtifact(artifact.id);
+	const request = {
+		tier: existing?.tier ?? "user",
+		scopeId: existing?.scopeId ?? artifact.userId,
+		slug: existing?.slug ?? artifactSlug(title, artifact.id),
+		title,
+		visibility: args.visibility ?? existing?.visibility ?? PUBLISH_DEFAULT_VISIBILITY,
+		...existing?.description !== void 0 && { description: existing.description },
+		...existing?.commentPolicy !== void 0 && { commentPolicy: existing.commentPolicy },
+		source: {
+			kind: "bundle",
+			artifactId: artifact.id,
+			artifactType: artifactType.data
+		},
+		files: [{
+			path: PUBLISH_INDEX_PATH,
+			size: Buffer.byteLength(body),
+			mimeType: PUBLISH_INDEX_MIME
+		}]
+	};
+	const draft = existing ? await client.requestPublishUpload(request) : await openPublishDraft(client, request);
+	const upload = draft.uploadUrls.find((u) => u.path === PUBLISH_INDEX_PATH);
+	if (!upload) throw new Error(`publish draft ${draft.draftId} returned no upload URL for ${PUBLISH_INDEX_PATH}`);
+	await client.uploadPublishDraftFile(upload.url, body, PUBLISH_INDEX_MIME);
+	const published = await client.finalizePublish(draft.draftId);
+	return {
+		publicId: published.publicId,
+		url: new URL(published.url, client.baseURL).toString(),
+		visibility: published.visibility
+	};
+}
+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 generated-audio response as an MCP result, shared by every audio tool.
+* Oversized audio is reported by its signed URL; a saved copy with a usable URL is
+* reported as a file (like get_file) with no inline bytes. Otherwise the audio rides
+* inline as an `audio` block so a billed result is never lost, with any saved copy
+* still named by id and a skipped save explained. The route forwards the signed URL
+* it minted at upload, so no getFile re-fetch is needed (that fails closed until
+* the async moderation scan runs).
+*/
+function generatedAudioResult(response, endpointMetadata) {
+	const metadata = {
+		...endpointMetadata,
+		contentType: response.contentType
+	};
+	const saveSkippedReason = response.saveSkippedReason ? { saveSkippedReason: response.saveSkippedReason } : {};
+	const file = response.fabFileId ? {
+		id: response.fabFileId,
+		...response.fileName ? { fileName: response.fileName } : {},
+		...response.fileUrl ? { fileUrl: response.fileUrl } : {}
+	} : void 0;
+	if (response.delivery === "url") return toResult({
+		...metadata,
+		byteLength: response.bytes,
+		url: response.url,
+		saved: response.saved === true,
+		...response.saved && file ? { file } : {},
+		...saveSkippedReason
+	});
+	const byteLength = Buffer.from(response.audio, "base64").length;
+	if (response.saved && file && file.fileUrl) return toResult({
+		...metadata,
+		byteLength,
+		saved: true,
+		file
+	});
+	return inlineAudioResult(response.saved && file ? {
+		...metadata,
+		byteLength,
+		saved: true,
+		file
+	} : {
+		...metadata,
+		byteLength,
+		saved: false,
+		...saveSkippedReason
+	}, response.audio, response.contentType);
+}
+/**
+* Metadata as JSON text plus the audio as an MCP `audio` block. The base64 stays
+* out of structuredContent so a potentially large payload is not duplicated.
+*/
+function inlineAudioResult(meta, audioBase64, mimeType) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(meta, null, 2)
+		}, {
+			type: "audio",
+			data: audioBase64,
+			mimeType
+		}],
+		structuredContent: meta
+	};
+}
+async function textToSpeech(client, args) {
+	const response = await client.synthesizeSpeech(args);
+	if (response.kind === "saved-too-large") {
+		const { provider, fabFileId, fileUrl } = response.data;
+		return toResult({
+			saved: true,
+			provider,
+			...response.fallbackFrom ? { fallbackFrom: response.fallbackFrom } : {},
+			file: {
+				id: fabFileId,
+				...fileUrl ? { fileUrl } : {}
+			}
+		});
+	}
+	const result = response.data;
+	return generatedAudioResult(result, {
+		provider: result.provider ?? args.provider ?? "openai",
+		...result.fallbackFrom ? { fallbackFrom: result.fallbackFrom } : {},
+		format: result.format
+	});
+}
+/**
+* Turn a quest poll's progress callback into MCP `notifications/progress`, or nothing when the
+* client sent no progressToken. Progress also lets a client that resets its request timeout on
+* progress wait out a slow quest.
+*/
+function progressReporter({ _meta, sendNotification }, describe) {
+	const progressToken = _meta?.progressToken;
+	if (progressToken === void 0) return void 0;
+	return (elapsedMs, quest) => sendNotification({
+		method: "notifications/progress",
+		params: {
+			progressToken,
+			progress: Math.floor(elapsedMs / 1e3),
+			message: describe(quest)
+		}
+	});
+}
+function chatProgress(quest) {
+	if (quest?.status !== "running") return "waiting for the reply to start";
+	const characters = replyText(quest).length;
+	return characters > 0 ? `generating reply (${characters} characters so far)` : "generating reply";
+}
+/**
+* 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("rename_notebook", {
+		title: meta("rename_notebook").title,
+		description: meta("rename_notebook").description,
+		inputSchema: renameNotebookShape
+	}, (args) => run("notebooks:write", () => renameNotebook(client, args)));
+	server.registerTool("clone_notebook", {
+		title: meta("clone_notebook").title,
+		description: meta("clone_notebook").description,
+		inputSchema: cloneNotebookShape
+	}, (args) => run("notebooks:write", () => cloneNotebook(client, args)));
+	server.registerTool("delete_notebook", {
+		title: meta("delete_notebook").title,
+		description: meta("delete_notebook").description,
+		inputSchema: deleteNotebookShape
+	}, (args) => run("notebooks:write", () => deleteNotebook(client, args)));
+	server.registerTool("list_projects", {
+		title: meta("list_projects").title,
+		description: meta("list_projects").description,
+		inputSchema: listProjectsShape
+	}, (args) => run("projects:read", () => listProjects(client, args)));
+	server.registerTool("get_project", {
+		title: meta("get_project").title,
+		description: meta("get_project").description,
+		inputSchema: getProjectShape
+	}, (args) => run("projects:read", () => getProject(client, args)));
+	server.registerTool("create_project", {
+		title: meta("create_project").title,
+		description: meta("create_project").description,
+		inputSchema: createProjectShape
+	}, (args) => run("projects:write", () => createProject(client, args)));
+	server.registerTool("send_message", {
+		title: meta("send_message").title,
+		description: meta("send_message").description,
+		inputSchema: sendMessageShape
+	}, (args, extra) => run("ai:chat", () => sendMessage(client, args, {
+		signal: extra.signal,
+		baseURL,
+		onProgress: progressReporter(extra, chatProgress)
+	})));
+	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_lakes", {
+		title: meta("list_lakes").title,
+		description: meta("list_lakes").description,
+		inputSchema: listLakesShape
+	}, (args) => run("datalake:read", () => listLakes(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 await generateSoundEffect(client, args);
+		} catch (err) {
+			return errorResult(mapApiError(err, baseURL, "ai:generate"));
+		}
+	});
+	server.registerTool("text_to_speech", {
+		title: meta("text_to_speech").title,
+		description: meta("text_to_speech").description,
+		inputSchema: textToSpeechShape
+	}, async (args) => {
+		try {
+			return await textToSpeech(client, args);
+		} catch (err) {
+			return errorResult(mapApiError(err, baseURL, "ai:generate"));
+		}
+	});
+	server.registerTool("generate_image", {
+		title: meta("generate_image").title,
+		description: meta("generate_image").description,
+		inputSchema: generateImageShape
+	}, (args, extra) => run("ai:generate", () => generateImage(client, args, {
+		signal: extra.signal,
+		baseURL,
+		onProgress: progressReporter(extra, () => "rendering image")
+	})));
+	server.registerTool("publish_artifact", {
+		title: meta("publish_artifact").title,
+		description: meta("publish_artifact").description,
+		inputSchema: publishArtifactShape
+	}, (args) => run("files:write", () => publishArtifact(client, args)));
+}
+//#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/prompts.ts
+/**
+* The `{{placeholder}}` keys a client supplies as prompt arguments. The clock keys
+* (currentDate, currentTime, ...) are not arguments: they are filled at get time,
+* exactly as the web launcher does at click time.
+*/
+const PROMPT_ARGUMENTS = [
+	{
+		name: "userName",
+		description: "Your name, substituted for {{userName}}"
+	},
+	{
+		name: "userEmail",
+		description: "Your email, substituted for {{userEmail}}"
+	},
+	{
+		name: "userRole",
+		description: "Your role, substituted for {{userRole}}"
+	},
+	{
+		name: "organization",
+		description: "Your organization, substituted for {{organization}}"
+	}
+];
+const PROMPT_ARGUMENT_NAMES = new Set(PROMPT_ARGUMENTS.map((arg) => arg.name));
+/** Flatten the catalog in category order; a prompt listed under two keys appears once. */
+function flattenCatalog(catalog) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const { key } of BRIEFCASE_CATALOG_QUERIES) for (const prompt of catalog[key] ?? []) if (!byId.has(prompt.id)) byId.set(prompt.id, prompt);
+	return [...byId.values()];
+}
+/**
+* List the caller's Briefcase catalog as MCP prompts, named by prompt id (display
+* names are not unique). Degrades to an empty list on failure, like the resource
+* lists: EnableBriefcase is off by default, so a hard error would fail every
+* client's startup listing on most instances.
+*/
+async function listPrompts(client) {
+	try {
+		return { prompts: flattenCatalog(await client.getBriefcaseCatalog(BRIEFCASE_CATALOG_QUERIES)).map((prompt) => ({
+			name: prompt.id,
+			title: prompt.name,
+			description: prompt.description,
+			arguments: PROMPT_ARGUMENTS.map((arg) => ({
+				...arg,
+				required: false
+			}))
+		})) };
+	} catch (err) {
+		logger.error(`mcp: listing briefcase prompts failed: ${mapApiError(err, client.baseURL)}`);
+		return { prompts: [] };
+	}
+}
+function toPromptContext(args, now) {
+	const supplied = Object.entries(args ?? {}).filter(([name, value]) => PROMPT_ARGUMENT_NAMES.has(name) && value !== "");
+	return {
+		...buildPromptContext(null, null, now),
+		...Object.fromEntries(supplied)
+	};
+}
+/** Resolve one prompt's template against the supplied arguments plus the clock. */
+async function getPrompt(client, name, args, now) {
+	const notFound = new McpError(ErrorCode.InvalidParams, `Prompt ${name} not found`);
+	const id = BriefcasePromptIdSchema.safeParse(name);
+	if (!id.success) throw notFound;
+	let prompt;
+	try {
+		prompt = await client.getBriefcasePrompt(id.data);
+	} catch (err) {
+		if (isAxiosError(err) && err.response?.status === 404) throw notFound;
+		throw new Error(mapApiError(err, client.baseURL));
+	}
+	if (!prompt.promptText) throw new Error(`Prompt ${name} has no text`);
+	const text = replacePromptVariables(prompt.promptText, toPromptContext(args, now));
+	return {
+		description: prompt.description ?? prompt.name,
+		messages: [{
+			role: "user",
+			content: {
+				type: "text",
+				text
+			}
+		}]
+	};
+}
+/**
+* Expose the Briefcase prompt catalog as MCP prompts. Wired on the low-level
+* server rather than through `registerPrompt`: the catalog is per-caller server
+* data that changes at runtime, so it is fetched on every prompts/list instead
+* of being frozen at build time. Requires the `prompts` capability to be declared
+* on the server (see buildMcpServer). Claims prompts/list and prompts/get on the
+* low-level server, so do not also call McpServer.registerPrompt on this server
+* (a claimed method makes it throw "already exists" at startup).
+*/
+function registerPrompts(server, client, now = () => /* @__PURE__ */ new Date()) {
+	server.server.setRequestHandler(ListPromptsRequestSchema, () => listPrompts(client));
+	server.server.setRequestHandler(GetPromptRequestSchema, (request) => getPrompt(client, request.params.name, request.params.arguments, now()));
+}
+//#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, the credential-free `b4m://agent-quest` manifest, and
+* the Briefcase prompt catalog as MCP prompts. Tool listing never touches the
+* network - only tool/resource *calls* and prompt listing/gets 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: {},
+		prompts: {}
+	} });
+	registerTools(server, client);
+	registerResources(server, client);
+	registerPrompts(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 };