@stll/folio-cli 0.3.4 → 0.4.1

package/dist/mcp.js

@@ -1,22 +1,32 @@
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
 import { executeReadTool } from "./execute-read.js";
 import { executeWriteTool } from "./execute-write.js";
-import { failureEnvelope, successEnvelope } from "./output.js";
+import { failure, success } from "./mcp-kit/envelope.js";
+import { compactSchema, hoistRepeatedSchemas } from "./mcp-kit/schema.js";
+import { createToolSurface } from "./mcp-kit/surface.js";
 import { version } from "./package.js";
-import { FOLIO_FILE_TOOLS, findFileTool, toolAccess } from "./registry.js";
+import { FOLIO_FILE_TOOLS, toolAccess } from "./registry.js";
 import { checkWithinRoots } from "./roots.js";
 import { Result, panic } from "better-result";
+import { SUGGEST_CHANGES_OPERATION_TYPES, describeSuggestChangesCapabilities } from "@stll/folio-agents/tools";
+import { FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE } from "@stll/folio-core/server";
 import { FOLIO_DOCUMENT_OPERATION_BATCH_JSON_SCHEMA } from "@stll/folio-agents/operation-schema";
 import { ProtocolError, ProtocolErrorCode, Server } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 //#region src/mcp.ts
 /**
 * `folio mcp`: the file tool registry as a Model Context Protocol server over
-* stdio. The protocol owns stdout; diagnostics go to stderr. Every tool takes
-* the file envelope (`path`, `fileVersion`, and for writes `destination`,
-* `txId`, ...) beside its own arguments, every path must resolve inside an
-* allowed root, and results are the same `{ ok, data | error }` envelope the
-* command line prints.
+* stdio. The protocol owns stdout; diagnostics go to stderr.
+*
+* A model pays for `tools/list` on every turn, so the server lists only the
+* frequent tools, with compact schemas, and reaches the rest through
+* `list_capabilities` / `describe_capability` / `invoke_capability`
+* (`mcp-kit`). Every tool takes the file envelope (`path`, `fileVersion`, and
+* for writes `destination`, `txId`, ...) beside its own arguments; the listed
+* schemas show the part a call usually needs and `describe_capability` shows
+* all of it. Every path must resolve inside an allowed root. Results carry
+* what the next call needs (the new `fileVersion`, ids, counts); a failure is
+* `{ error: { code, message, hint, retryable } }`.
 */
 /** Limits on what one MCP tool call returns. */
 const MCP_READ_BOUNDS = {
@@ -26,20 +36,21 @@ const MCP_READ_BOUNDS = {
 };
 const ABOUT_URI = "folio://about";
 const OPERATIONS_SCHEMA_URI = "folio://schema/operations";
-const INSTRUCTIONS = "Tools read and change .docx files on disk. Start with get_document_outline or read_document to get block ids and the file's fileVersion; find_text returns exact range handles. Mutating tools require the fileVersion you read and refuse (stale_version) when the file changed; re-read and retry. Edits are tracked changes unless mode is direct. Without destination a change is written in place with a backup; with destination it goes to that new file. Results are { ok, data } or { ok: false, error: { code, message, hint } }.";
+const instructionsFor = (author) => "Reads and edits .docx files. read_document returns the fileVersion and a `[blockId] text` line per block; a write needs the latest fileVersion and returns the next. Block ids stay valid across edits, so chain calls without re-reading. Edits are tracked changes. One suggest_changes batch can do a whole review: replaceAll {find, replace} renames everywhere, tables included; addComment {comment, quote or blockId} comments alongside. A successful write is authoritative (fileVersion, author, applied counts): no verification read or shell check is needed. " + (author === void 0 ? "No author is configured, so writes are refused. " : `Every change and comment is recorded under the author ${JSON.stringify(author)}. `) + "Failures are { error: { code, message, hint, retryable } }.";
 const PATH_PROPERTY = {
 	type: "string",
 	description: "The .docx file, absolute or relative to the first allowed root."
 };
+const FILE_VERSION_PATTERN = "^[0-9a-f]{64}$";
 const envelopeProperties = (tool) => {
 	const access = toolAccess(tool);
 	const properties = {
 		path: PATH_PROPERTY,
 		fileVersion: {
 			type: "string",
-			pattern: "^[0-9a-f]{64}$",
+			pattern: FILE_VERSION_PATTERN,
 			description: {
-				write: "The file's fileVersion (SHA-256) from your latest read. Required: a change to a file that moved on is refused.",
+				write: "The file's fileVersion (SHA-256) from your latest read or write. Required: a change to a file that moved on is refused.",
 				readOrWrite: "The file's fileVersion (SHA-256) from your latest read; required with `destination`.",
 				read: "When given, refuse unless the file still has this fileVersion."
 			}[access]
@@ -57,13 +68,13 @@ const envelopeProperties = (tool) => {
 		},
 		expectedDestinationVersion: {
 			type: "string",
-			pattern: "^[0-9a-f]{64}$",
+			pattern: FILE_VERSION_PATTERN,
 			description: "The fileVersion of the existing file `destination` replaces."
 		},
 		txId: {
 			type: "string",
 			pattern: "^[\\w.-]{1,128}$",
-			description: "Idempotency key: repeating a committed call returns its original receipt."
+			description: "Idempotency key: repeating a committed call returns its original result."
 		}
 	});
 	if (access === "write") Object.assign(properties, { allowRepack: {
@@ -77,7 +88,12 @@ const envelopeProperties = (tool) => {
 	} });
 	return properties;
 };
-/** The tool's MCP input schema: its own arguments plus the file envelope. */
+/** Arguments only the MCP surface takes, beside the registry's. */
+const MCP_ONLY_PROPERTIES = { read_document: { formatting: {
+	type: "boolean",
+	description: "Return each block's fields (kind, displayLabel, headingLevel, listLevel, blockTextHash, blockIdSource, tableCell) instead of `[id] text` lines."
+} } };
+/** The tool's full MCP input schema: its own arguments plus the file envelope. */
 const mcpInputSchema = (tool) => {
 	const envelope = envelopeProperties(tool);
 	for (const key of Object.keys(envelope)) if (key in tool.argsSchema.properties) panic(`${tool.name} declares ${key}, which the file envelope also uses`);
@@ -86,7 +102,8 @@ const mcpInputSchema = (tool) => {
 		type: "object",
 		properties: {
 			...envelope,
-			...tool.argsSchema.properties
+			...tool.argsSchema.properties,
+			...MCP_ONLY_PROPERTIES[tool.name]
 		},
 		required: [
 			"path",
@@ -96,39 +113,127 @@ const mcpInputSchema = (tool) => {
 		additionalProperties: false
 	};
 };
-const isJsonValue = (value) => {
-	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
-	if (typeof value === "number") return Number.isFinite(value);
-	if (Array.isArray(value)) return value.every(isJsonValue);
-	return typeof value === "object" && Object.values(value).every(isJsonValue);
-};
-/** The registry schemas are JSON by construction; a value that is not is a registry bug. */
-const toJsonObject = (properties) => {
-	const object = {};
-	for (const [key, value] of Object.entries(properties)) object[key] = isJsonValue(value) ? value : panic(`Schema property ${key} is not JSON`);
-	return object;
+/** Switches that widen what a write may do: they count only as JSON `true`. */
+const EXACT_PROPERTIES = ["overwrite", "allowRepack"];
+const STRING = { type: "string" };
+const BOOLEAN = { type: "boolean" };
+/**
+* The tools listed on every turn, with the schema they are listed with. Each
+* accepts its full schema too; `describe_capability` shows it.
+*/
+const DIRECT_TOOLS = {
+	read_document: {
+		summary: "Read blocks as `[id] text` lines (a table row as `| [id] cell | [id] cell |`), with the fileVersion writes need. When `nextCursor` is set, pass it as `cursor` for the next page.",
+		properties: {
+			path: STRING,
+			cursor: STRING,
+			maxBlocks: { type: "integer" },
+			formatting: BOOLEAN
+		},
+		required: ["path"]
+	},
+	find_text: {
+		summary: "Find text. Each match has its blockId, a `range` to pass to replaceRange or commentOnRange, and context.",
+		properties: {
+			path: STRING,
+			query: STRING,
+			matchCase: BOOLEAN,
+			wholeWord: BOOLEAN
+		},
+		required: ["path", "query"]
+	},
+	suggest_changes: {
+		summary: "Apply edits as tracked changes in one batch that lands whole or not at all; returns the new fileVersion. Operations: replaceAll {find, replace, matchCase?, wholeWord?} (every match); replaceInBlock {blockId, find, replace}; replaceRange {range, replace}; replaceBlock {blockId, text}; insertAfterBlock / insertBeforeBlock {blockId, text}; deleteBlock {blockId}; addComment {comment, quote or blockId}; commentOnRange {range, comment}. Others: describe_capability.",
+		properties: {
+			path: STRING,
+			fileVersion: STRING,
+			operations: {
+				type: "array",
+				items: {
+					type: "object",
+					properties: { type: STRING },
+					required: ["type"]
+				}
+			}
+		},
+		required: [
+			"path",
+			"fileVersion",
+			"operations"
+		]
+	},
+	add_comment: {
+		summary: "Comment on a block; `quote` anchors it to exact text in the block. Returns the new fileVersion.",
+		properties: {
+			path: STRING,
+			fileVersion: STRING,
+			blockId: STRING,
+			text: STRING,
+			quote: STRING
+		},
+		required: [
+			"path",
+			"fileVersion",
+			"blockId",
+			"text"
+		]
+	},
+	read_changes: {
+		summary: "List pending tracked changes.",
+		properties: { path: STRING },
+		required: ["path"]
+	},
+	read_comments: {
+		summary: "List comment threads.",
+		properties: {
+			path: STRING,
+			filter: {
+				type: "string",
+				enum: [
+					"all",
+					"open",
+					"resolved"
+				]
+			}
+		},
+		required: ["path"]
+	}
 };
-const toMcpInputSchema = ({ properties, required }) => ({
-	type: "object",
-	properties: toJsonObject(properties),
-	required: [...required],
-	additionalProperties: false
-});
-const listMcpTools = () => FOLIO_FILE_TOOLS.map((tool) => ({
-	name: tool.name,
-	description: tool.description,
-	inputSchema: toMcpInputSchema(mcpInputSchema(tool)),
-	annotations: {
-		readOnlyHint: toolAccess(tool) === "read",
-		destructiveHint: toolAccess(tool) !== "read",
-		openWorldHint: false
+/** One-line summaries for the tools reached through the capability tools. */
+const LAZY_SUMMARIES = {
+	get_document_outline: {
+		summary: "Heading outline with section handles.",
+		domain: "read"
+	},
+	read_section: {
+		summary: "Read one section by its outline handle.",
+		domain: "read"
+	},
+	list_stories: {
+		summary: "List header, footer and note stories.",
+		domain: "read"
+	},
+	read_story: {
+		summary: "Read one story by its handle.",
+		domain: "read"
+	},
+	reply_comment: {
+		summary: "Reply to a comment thread.",
+		domain: "comments"
+	},
+	resolve_comment: {
+		summary: "Resolve or reopen a comment thread.",
+		domain: "comments"
+	},
+	resolve_changes: {
+		summary: "Accept or reject tracked changes.",
+		domain: "changes"
+	},
+	compare_documents: {
+		summary: "Diff two .docx files, or write their redline to a destination.",
+		domain: "compare"
 	}
-}));
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const invalidInput = (message) => cliError({
-	code: FOLIO_CLI_ERROR_CODES.invalidInput,
-	message
-});
+};
 const ENVELOPE_KEYS = /* @__PURE__ */ new Set([
 	"path",
 	"fileVersion",
@@ -137,13 +242,17 @@ const ENVELOPE_KEYS = /* @__PURE__ */ new Set([
 	"expectedDestinationVersion",
 	"txId",
 	"allowRepack",
-	"mode"
+	"mode",
+	"formatting"
 ]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const invalidInput = (message) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidInput,
+	message
+});
 const optionalString = (value, name) => value === void 0 || typeof value === "string" ? Result.ok(value) : Result.err(invalidInput(`${name} must be a string.`));
 const toRevisionDate = (date) => date.toISOString().replace(/\.\d{3}Z$/u, "Z");
-const runTool = async (tool, rawArgs, context) => {
-	if (rawArgs !== void 0 && !isRecord(rawArgs)) return Result.err(invalidInput("Tool arguments must be an object."));
-	const input = rawArgs ?? {};
+const runTool = async (tool, input, context) => {
 	const args = {};
 	for (const [key, value] of Object.entries(input)) if (!ENVELOPE_KEYS.has(key)) args[key] = value;
 	const rawPath = input["path"];
@@ -212,24 +321,340 @@ const runTool = async (tool, rawArgs, context) => {
 		mode: input["mode"] === "direct" ? "direct" : "tracked-changes"
 	});
 };
-const toCallToolResult = (result) => {
-	const envelope = result.isOk() ? successEnvelope(result.value) : failureEnvelope(result.error);
+const arrayOf = (value) => Array.isArray(value) ? value : [];
+const recordOf = (value) => isRecord(value) ? value : {};
+/**
+* A number or bullet worth showing. An unnumbered heading's label is its
+* style id (`Heading1`, `Title`), which says nothing the `(hN)` mark does
+* not; every other label (`iii.`, `Article 1`, `•`) is shown.
+*/
+const isNumberLabel = (label, heading) => typeof label === "string" && !(heading && /^\p{L}{3,}\d*$/u.test(label));
+/** One block as the line a model reads: `[id] (h2) 2.1 text`. */
+const blockLine = (block) => {
+	const row = recordOf(block);
+	const label = row["displayLabel"];
+	const isHeading = typeof row["headingLevel"] === "number";
+	const heading = isHeading ? `(h${String(row["headingLevel"])}) ` : "";
+	const number = isNumberLabel(label, isHeading) ? `${label} ` : "";
+	return `[${String(row["blockId"])}] ${heading}${number}${String(row["text"] ?? "")}`;
+};
+/**
+* Blocks as lines, a table row on one line: `| [id] cell | [id] cell |`,
+* a cell's paragraphs side by side. Empty cells hold no block and show none.
+*/
+const blockLines = (blocks) => {
+	const lines = [];
+	let row;
+	const flush = () => {
+		if (row !== void 0) lines.push(`| ${row.cells.map((cell) => cell.join(" ")).join(" | ")} |`);
+		row = void 0;
+	};
+	for (const block of blocks) {
+		const location = recordOf(recordOf(block)["tableCell"]);
+		if (typeof location["table"] !== "number") {
+			flush();
+			lines.push(blockLine(block));
+			continue;
+		}
+		const key = `${location["table"]}:${String(location["row"])}`;
+		if (row?.key !== key) {
+			flush();
+			row = {
+				key,
+				cells: [],
+				cell: void 0
+			};
+		}
+		if (row.cell !== location["cell"] || row.cells.length === 0) {
+			row.cells.push([]);
+			row.cell = location["cell"];
+		}
+		row.cells.at(-1)?.push(blockLine(block));
+	}
+	flush();
+	return lines.join("\n");
+};
+/** A main-story range without the fields the server fills back in. */
+const compactRange = (range) => {
+	const { type, story, ...rest } = recordOf(range);
+	return type === "textRange" && story === "main" ? rest : range;
+};
+const compactMatch = (match) => {
+	const row = recordOf(match);
+	if (isRecord(row["range"])) return {
+		range: compactRange(row["range"]),
+		context: row["context"]
+	};
+	const { blockTextHash: _hash, type: _type, ...rest } = row;
+	return rest;
+};
+const CHANGE_LINE_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"type",
+	"blockId",
+	"text",
+	"author",
+	"date"
+]);
+/** One tracked change as a line: `12 insertion [blockId] "text" author`, then any other fields. */
+const changeLine = (change) => {
+	const row = recordOf(change);
+	const extra = Object.entries(row).filter(([key]) => !CHANGE_LINE_KEYS.has(key)).map(([key, value]) => `${key}=${JSON.stringify(value)}`);
+	return [
+		String(row["id"]),
+		String(row["type"]),
+		...typeof row["blockId"] === "string" ? [`[${row["blockId"]}]`] : [],
+		JSON.stringify(row["text"] ?? ""),
+		...typeof row["author"] === "string" ? [row["author"]] : [],
+		...extra
+	].join(" ");
+};
+const commentIdsOf = (receipts) => arrayOf(receipts).flatMap((receipt) => arrayOf(recordOf(receipt)["affected"]).flatMap((affected) => {
+	const entry = recordOf(affected);
+	return entry["type"] === "comment" ? [String(entry["commentId"])] : [];
+}));
+/** A read's result, cut to what the next call needs. */
+const compactRead = ({ tool, input }, data) => {
+	const { fileVersion } = data;
+	const result = data["result"];
+	switch (tool.name) {
+		case "read_document": {
+			const page = recordOf(result);
+			const blocks = arrayOf(page["blocks"]);
+			return {
+				fileVersion,
+				blocks: input["formatting"] === true ? blocks : blockLines(blocks),
+				...page["nextCursor"] !== void 0 && {
+					nextCursor: page["nextCursor"],
+					totalBlocks: page["totalBlocks"]
+				}
+			};
+		}
+		case "find_text": {
+			const found = recordOf(result);
+			return {
+				fileVersion,
+				matches: arrayOf(found["matches"]).map(compactMatch),
+				...found["truncated"] === true && {
+					truncated: true,
+					totalMatches: found["totalMatches"]
+				}
+			};
+		}
+		case "read_changes": return {
+			fileVersion,
+			changes: arrayOf(result).map(changeLine).join("\n")
+		};
+		case "compare_documents": return {
+			fileVersion,
+			revised: data["revised"],
+			diff: recordOf(result)["text"]
+		};
+		default: return isRecord(result) ? {
+			fileVersion,
+			...result
+		} : {
+			fileVersion,
+			result
+		};
+	}
+};
+/** A write's receipt, cut to the new version and what the change produced. */
+const compactWrite = ({ tool, input }, receipt) => {
+	const result = recordOf(receipt["result"]);
+	const base = {
+		fileVersion: receipt["fileVersion"],
+		author: receipt["author"],
+		...input["destination"] !== void 0 && { path: receipt["path"] },
+		...receipt["status"] === "replayed" && { replayed: true },
+		...receipt["rebased"] !== void 0 && { rebased: receipt["rebased"] }
+	};
+	switch (tool.name) {
+		case "suggest_changes": {
+			const normalizations = arrayOf(result["normalizations"]);
+			const replaced = arrayOf(result["replaced"]);
+			const commentIds = commentIdsOf(result["receipts"]);
+			return {
+				...base,
+				applied: arrayOf(result["applied"]).length,
+				...replaced.length > 0 && { replaced },
+				...commentIds.length > 0 && { commentIds },
+				...normalizations.length > 0 && { normalizations }
+			};
+		}
+		case "add_comment":
+		case "reply_comment": return {
+			...base,
+			commentId: commentIdsOf(result["receipts"]).at(0)
+		};
+		case "resolve_changes": return {
+			...base,
+			resolved: result["resolved"],
+			remaining: result["remaining"]
+		};
+		case "compare_documents": return {
+			...base,
+			...result
+		};
+		default: return base;
+	}
+};
+const RETRYABLE_CODES = /* @__PURE__ */ new Set([
+	FOLIO_CLI_ERROR_CODES.staleVersion,
+	FOLIO_CLI_ERROR_CODES.staleTarget,
+	FOLIO_CLI_ERROR_CODES.locked
+]);
+/** Refusal details, without the parts that only restate the message. */
+const compactDetails = (details) => {
+	if (!isRecord(details) || !Array.isArray(details["skipped"])) return details;
+	return { skipped: details["skipped"] };
+};
+const toOutcome = (options, result) => {
+	if (result.isErr()) {
+		const { code, message, hint, details } = result.error;
+		return failure({
+			code,
+			message,
+			hint,
+			retryable: RETRYABLE_CODES.has(code),
+			details: compactDetails(details)
+		});
+	}
+	const data = recordOf(result.value);
+	return success("txId" in data ? compactWrite(options, data) : compactRead(options, data));
+};
+/** Fill in a main-story range's `type` and `story`, which find_text leaves out. */
+const withFullRanges = (operations) => Array.isArray(operations) ? operations.map((operation) => {
+	if (!isRecord(operation) || !isRecord(operation["range"])) return operation;
 	return {
-		content: [{
-			type: "text",
-			text: JSON.stringify(envelope)
-		}],
-		isError: !envelope.ok
+		...operation,
+		range: {
+			type: "textRange",
+			story: "main",
+			...operation["range"]
+		}
 	};
+}) : operations;
+/** Operation keys the model never writes. */
+const HIDDEN_OPERATION_KEYS = /* @__PURE__ */ new Set(["type", "suggestionId"]);
+/**
+* The fields each operation type accepts, one line per type. The described
+* schema lists every field once for all types, without their descriptions.
+*/
+const OPERATION_FIELDS = [
+	"replaceAll: id, find, replace, matchCase, wholeWord, severity, area",
+	"addComment: id, comment, blockId, quote, severity, area",
+	...SUGGEST_CHANGES_OPERATION_TYPES.map((type) => `${type}: ${FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE[type].filter((key) => !HIDDEN_OPERATION_KEYS.has(key)).join(", ")}`)
+].join("\n");
+/** What the compact `describe_capability` says about suggest_changes. */
+const SUGGEST_CHANGES_BRIEF = [
+	"Fields (* required):",
+	"replaceAll {find*, replace*, matchCase, wholeWord}: every match in the body and tables; run formatting is kept",
+	"replaceInBlock {blockId*, find*, replace*}: find must occur once in the block",
+	"replaceRange {range*, replace*}: range from find_text",
+	"replaceBlock {blockId*, text*, preserveFormatting}",
+	"insertAfterBlock | insertBeforeBlock {blockId*, text*, styleId}",
+	"deleteBlock {blockId*}",
+	"addComment {comment*, blockId | quote}: a quote alone anchors to the one block containing it",
+	"commentOnRange {range*, comment*}",
+	"formatRange {range*, formatting* {bold, italic, underline}}",
+	"Edits take an optional comment. mode \"direct\" edits without tracking. Split, merge and table operations: detail \"full\"."
+].join("\n");
+const SUGGEST_CHANGES_EXAMPLE = {
+	path: "contract.docx",
+	fileVersion: "<from read_document>",
+	operations: [{
+		type: "replaceAll",
+		find: "Supplier",
+		replace: "Provider",
+		matchCase: true,
+		wholeWord: true
+	}, {
+		type: "addComment",
+		quote: "total liability",
+		comment: "Is this cap acceptable?"
+	}]
+};
+const guideOf = (tool) => tool.name === "suggest_changes" ? `${describeSuggestChangesCapabilities()}\nFields by operation type:\n${OPERATION_FIELDS}` : tool.description;
+const toKitTool = (tool) => {
+	const direct = DIRECT_TOOLS[tool.name];
+	const lazy = LAZY_SUMMARIES[tool.name];
+	const summary = direct?.summary ?? lazy?.summary ?? panic(`${tool.name} has no MCP summary`);
+	const access = toolAccess(tool);
+	return {
+		name: tool.name,
+		summary,
+		guide: guideOf(tool),
+		...tool.name === "suggest_changes" && {
+			brief: SUGGEST_CHANGES_BRIEF,
+			example: SUGGEST_CHANGES_EXAMPLE
+		},
+		access: access === "read" ? "read" : "write",
+		destructive: access !== "read",
+		...lazy !== void 0 && { domain: lazy.domain },
+		inputSchema: mcpInputSchema(tool),
+		describedSchema: hoistRepeatedSchemas(compactSchema(mcpInputSchema(tool), { describedDepth: 1 })),
+		...direct !== void 0 && { direct: { inputSchema: {
+			type: "object",
+			properties: direct.properties,
+			required: [...direct.required]
+		} } },
+		exactProperties: EXACT_PROPERTIES,
+		run: async (args, context) => {
+			const input = tool.name === "suggest_changes" ? {
+				...args,
+				operations: withFullRanges(args["operations"])
+			} : args;
+			const result = await Result.tryPromise({
+				try: () => runTool(tool, input, context),
+				catch: (error) => cliError({
+					code: FOLIO_CLI_ERROR_CODES.internal,
+					message: error instanceof Error ? error.message : String(error)
+				})
+			});
+			return toOutcome({
+				tool,
+				input
+			}, result.isOk() ? result.value : result);
+		}
+	};
+};
+const surface = createToolSurface({ tools: FOLIO_FILE_TOOLS.map(toKitTool) });
+const isJsonValue = (value) => {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJsonValue);
+	return typeof value === "object" && Object.values(value).every(isJsonValue);
 };
+/** The schemas are JSON by construction; a value that is not is a registry bug. */
+const toJsonObject = (properties) => {
+	const object = {};
+	for (const [key, value] of Object.entries(properties)) object[key] = isJsonValue(value) ? value : panic(`Schema property ${key} is not JSON`);
+	return object;
+};
+const toMcpInputSchema = (schema) => {
+	const required = arrayOf(schema["required"]).filter((key) => typeof key === "string");
+	return {
+		type: "object",
+		properties: toJsonObject(recordOf(schema["properties"])),
+		...required.length > 0 && { required }
+	};
+};
+/** What `tools/list` returns. */
+const listMcpTools = () => surface.listTools().map(({ name, description, inputSchema, annotations }) => ({
+	name,
+	description,
+	inputSchema: toMcpInputSchema(inputSchema),
+	annotations
+}));
 const aboutText = (roots) => [
 	`# folio ${version}`,
 	"",
 	`Allowed roots: ${roots.join(", ")}`,
 	"",
 	"- fileVersion is the SHA-256 of the file's bytes; changes require the one you read.",
-	"- Block ids are the paragraph's w14:paraId (blockIdSource: package) or derived from text and",
-	"  position (synthetic), valid only for the fileVersion they were read at.",
+	"- Block ids are the paragraph's w14:paraId. A paragraph without one is given one derived from",
+	"  the file's bytes, which the first change writes into the file, so ids survive edits.",
 	"- Offsets in range handles are UTF-16 code units into the block text read_document returns.",
 	"- A change writes atomically in place or to destination (a plain .docx, never a dotfile or inside",
 	"  .folio); replacing an existing file needs overwrite plus expectedDestinationVersion. Whatever is",
@@ -266,21 +691,10 @@ const createFolioMcpServer = (options) => {
 			tools: {},
 			resources: {}
 		},
-		instructions: INSTRUCTIONS
+		instructions: instructionsFor(options.author)
 	});
 	server.setRequestHandler("tools/list", () => ({ tools: listMcpTools() }));
-	server.setRequestHandler("tools/call", async (request) => {
-		const tool = findFileTool(request.params.name);
-		if (tool === void 0) return toCallToolResult(Result.err(invalidInput(`Unknown tool ${JSON.stringify(request.params.name)}.`)));
-		const result = await Result.tryPromise({
-			try: () => runTool(tool, request.params.arguments, context),
-			catch: (error) => cliError({
-				code: FOLIO_CLI_ERROR_CODES.internal,
-				message: error instanceof Error ? error.message : String(error)
-			})
-		});
-		return toCallToolResult(result.isOk() ? result.value : result);
-	});
+	server.setRequestHandler("tools/call", (request) => surface.callTool(request.params.name, request.params.arguments, context));
 	server.setRequestHandler("resources/list", () => ({ resources: [{
 		uri: ABOUT_URI,
 		name: "about",
@@ -307,4 +721,4 @@ const serveFolioMcp = async ({ input, output, ...options }) => {
 	await closed;
 };
 //#endregion
-export { MCP_READ_BOUNDS, createFolioMcpServer, listMcpTools, mcpInputSchema, serveFolioMcp };
+export { MCP_READ_BOUNDS, blockLines, createFolioMcpServer, listMcpTools, mcpInputSchema, serveFolioMcp };

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.3.4";
+var version = "0.4.1";
 //#endregion
 export { version };