@stll/folio-cli 0.3.4 → 0.4.1

package/dist/mcp-kit/surface.js

@@ -0,0 +1,312 @@
+import { KIT_ERROR_CODES, closestNames, didYouMean, failure, success, toCallResult, validationError } from "./envelope.js";
+import { readToolInput } from "./input.js";
+import { compactSchema } from "./schema.js";
+//#region src/mcp-kit/surface.ts
+/**
+* A tool surface with lazy discovery. The frequent tools are listed directly
+* with compact schemas; the rest stay out of `tools/list` and are reached
+* through three capability tools, so a turn pays only for what is listed:
+*
+* - `list_capabilities` pages the unlisted tools: id, summary, access.
+* - `describe_capability` returns one tool's parameter outline, short
+*   guidance and an example; with `detail: "full"`, its full input schema and
+*   guidance (listed tools included, whose listed schema is the compact one).
+* - `invoke_capability` runs one by id with `input` checked against that
+*   full schema; `validate_only` checks without running.
+*
+* Every tool is also callable by its own name. Calls are read through
+* `readToolInput` and answered with `toCallResult`'s one envelope.
+*/
+const CAPABILITY_TOOL_NAMES = {
+	list: "list_capabilities",
+	describe: "describe_capability",
+	invoke: "invoke_capability"
+};
+const DEFAULT_LIST_LIMIT = 50;
+const MAX_LIST_LIMIT = 100;
+const LIST_SCHEMA = {
+	type: "object",
+	properties: {
+		domain: { type: "string" },
+		access: {
+			type: "string",
+			enum: [
+				"all",
+				"read",
+				"write"
+			]
+		},
+		cursor: { type: "string" },
+		limit: {
+			type: "integer",
+			minimum: 1,
+			maximum: MAX_LIST_LIMIT
+		}
+	}
+};
+const DESCRIBE_SCHEMA = {
+	type: "object",
+	properties: {
+		capability: { type: "string" },
+		detail: {
+			type: "string",
+			enum: ["compact", "full"]
+		}
+	},
+	required: ["capability"]
+};
+const INVOKE_SCHEMA = {
+	type: "object",
+	properties: {
+		capability: { type: "string" },
+		input: { type: "object" },
+		validate_only: { type: "boolean" }
+	},
+	required: ["capability"]
+};
+const READ_ONLY = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	openWorldHint: false
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Takes only the fields it reads, so a tool of any context type fits. */
+const destructiveOf = (tool) => tool.destructive ?? tool.access === "write";
+const listedSchema = (schema) => ({
+	...compactSchema(schema),
+	type: "object"
+});
+/** One property as a short type: `string`, `object[]`, `"a" | "b"`. */
+const typeOutline = (schema) => {
+	if (!isRecord(schema)) return "any";
+	if (Array.isArray(schema["enum"])) return schema["enum"].map((value) => JSON.stringify(value)).join(" | ");
+	const type = schema["type"];
+	if (type === "array") return `${typeOutline(schema["items"])}[]`;
+	if (typeof type === "string") return type;
+	if (Array.isArray(type)) return type.join(" | ");
+	const variants = schema["oneOf"] ?? schema["anyOf"];
+	if (Array.isArray(variants)) return [...new Set(variants.map(typeOutline))].join(" | ");
+	return "any";
+};
+/** Each parameter's type, required ones marked: what a compact description shows. */
+const parameterOutline = (schema) => {
+	const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+	const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+	return Object.fromEntries(Object.entries(properties).map(([key, property]) => [key, `${typeOutline(property)}${required.has(key) ? " (required)" : ""}`]));
+};
+/**
+* Ordinal (code unit) order: the one order both the listing and its cursor
+* use, so a page never skips or repeats an id whatever its case or symbols.
+*/
+const compareIds = (a, b) => {
+	if (a === b) return 0;
+	return a < b ? -1 : 1;
+};
+const encodeCursor = (id) => Buffer.from(id, "utf8").toString("base64url");
+const decodeCursor = (cursor) => {
+	const decoded = Buffer.from(cursor, "base64url").toString("utf8");
+	return decoded.length > 0 && encodeCursor(decoded) === cursor ? decoded : null;
+};
+const hasJsonType = (value, type) => {
+	if (type === "object") return isRecord(value);
+	if (type === "integer") return Number.isInteger(value);
+	return typeof value === type;
+};
+/**
+* The capability tools' own arguments, read strictly: a misspelt flag or a
+* string where a boolean belongs would otherwise change what runs.
+*/
+const readMetaArgs = (tool, schema, value) => {
+	if (value !== void 0 && !isRecord(value)) return {
+		ok: false,
+		outcome: validationError(`${tool} takes a JSON object.`, [])
+	};
+	const args = {};
+	const issues = [];
+	for (const [key, entry] of Object.entries(value ?? {})) {
+		const property = Object.hasOwn(schema.properties, key) ? schema.properties[key] : void 0;
+		if (property === void 0) {
+			issues.push({
+				path: key,
+				message: `Unknown parameter: ${key}`
+			});
+			continue;
+		}
+		if (entry === null) continue;
+		if (!hasJsonType(entry, property.type) || property.enum !== void 0 && !property.enum.includes(String(entry))) {
+			issues.push({
+				path: key,
+				message: `Expected ${property.enum === void 0 ? `a JSON ${property.type}` : property.enum.join(" | ")}.`
+			});
+			continue;
+		}
+		args[key] = entry;
+	}
+	for (const key of schema.required ?? []) if (args[key] === void 0 && !issues.some(({ path }) => path === key)) issues.push({
+		path: key,
+		message: `Missing parameter: ${key}`
+	});
+	return issues.length > 0 ? {
+		ok: false,
+		outcome: validationError(`${tool} arguments need clarification.`, issues, `Accepted parameters: ${Object.keys(schema.properties).join(", ")}.`)
+	} : {
+		ok: true,
+		args
+	};
+};
+/** Build a surface over `tools`. Names must be unique and not a capability tool's. */
+const createToolSurface = ({ tools }) => {
+	const byName = /* @__PURE__ */ new Map();
+	const reserved = new Set(Object.values(CAPABILITY_TOOL_NAMES));
+	for (const tool of tools) {
+		if (byName.has(tool.name) || reserved.has(tool.name)) throw new Error(`Tool name ${tool.name} is taken.`);
+		byName.set(tool.name, tool);
+	}
+	const lazy = tools.filter((tool) => tool.direct === void 0).toSorted((a, b) => compareIds(a.name, b.name));
+	const names = [...byName.keys()];
+	const unknownCapability = (id) => failure({
+		code: KIT_ERROR_CODES.notFound,
+		message: `No capability with id "${id}".`,
+		hint: `${didYouMean(closestNames(id, names))}Call ${CAPABILITY_TOOL_NAMES.list} to browse the ids.`
+	});
+	const run = async (tool, value, context, validateOnly = false) => {
+		const read = readToolInput({
+			schema: tool.inputSchema,
+			value,
+			access: tool.access,
+			exactProperties: tool.exactProperties
+		});
+		if (!read.ok) return toCallResult(validationError(read.message, read.issues, read.hint));
+		if (validateOnly) return toCallResult(success({
+			valid: true,
+			input: read.value
+		}), read.notes);
+		let outcome;
+		try {
+			outcome = await tool.run(read.value, context);
+		} catch (error) {
+			outcome = failure({
+				code: KIT_ERROR_CODES.internal,
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+		return toCallResult(outcome, read.notes);
+	};
+	const listCapabilities = (value) => {
+		const read = readMetaArgs(CAPABILITY_TOOL_NAMES.list, LIST_SCHEMA, value);
+		if (!read.ok) return read.outcome;
+		const { domain, access = "all", cursor, limit = DEFAULT_LIST_LIMIT } = read.args;
+		if (typeof limit !== "number" || limit < 1 || limit > MAX_LIST_LIMIT) return validationError("limit is out of range.", [{
+			path: "limit",
+			message: `Expected 1 to ${MAX_LIST_LIMIT}.`
+		}]);
+		const after = typeof cursor === "string" ? decodeCursor(cursor) : void 0;
+		if (after === null) return validationError("cursor is not a nextCursor from list_capabilities.", [{
+			path: "cursor",
+			message: "Unrecognised cursor."
+		}]);
+		const matching = lazy.filter((tool) => (domain === void 0 || tool.domain === domain) && (access === "all" || tool.access === access) && (after === void 0 || compareIds(tool.name, after) > 0));
+		const page = matching.slice(0, limit);
+		const last = page.at(-1);
+		return success({
+			items: page.map((tool) => ({
+				id: tool.name,
+				summary: tool.summary,
+				access: tool.access,
+				...destructiveOf(tool) && { destructive: true }
+			})),
+			nextCursor: last !== void 0 && matching.length > page.length ? encodeCursor(last.name) : null
+		});
+	};
+	const describeCapability = (value) => {
+		const read = readMetaArgs(CAPABILITY_TOOL_NAMES.describe, DESCRIBE_SCHEMA, value);
+		if (!read.ok) return read.outcome;
+		const id = String(read.args["capability"]);
+		const tool = byName.get(id);
+		if (tool === void 0) return unknownCapability(id);
+		if (read.args["detail"] === "full") return success({
+			id: tool.name,
+			description: tool.guide === void 0 ? tool.summary : `${tool.summary}\n${tool.guide}`,
+			access: tool.access,
+			destructive: destructiveOf(tool),
+			inputSchema: tool.describedSchema ?? tool.inputSchema
+		});
+		return success({
+			id: tool.name,
+			description: tool.brief === void 0 ? tool.summary : `${tool.summary}\n${tool.brief}`,
+			access: tool.access,
+			destructive: destructiveOf(tool),
+			parameters: parameterOutline(tool.inputSchema),
+			...tool.example !== void 0 && { example: tool.example },
+			more: "detail: \"full\" returns the full input schema."
+		});
+	};
+	const invokeCapability = async (value, context) => {
+		const read = readMetaArgs(CAPABILITY_TOOL_NAMES.invoke, INVOKE_SCHEMA, value);
+		if (!read.ok) return toCallResult(read.outcome);
+		const id = String(read.args["capability"]);
+		const tool = byName.get(id);
+		if (tool === void 0) return toCallResult(unknownCapability(id));
+		return await run(tool, read.args["input"] ?? {}, context, read.args["validate_only"] === true);
+	};
+	const listTools = () => {
+		const listed = tools.flatMap((tool) => tool.direct === void 0 ? [] : [{
+			name: tool.name,
+			description: tool.summary,
+			inputSchema: listedSchema(tool.direct.inputSchema),
+			annotations: {
+				readOnlyHint: tool.access === "read",
+				destructiveHint: destructiveOf(tool),
+				openWorldHint: false
+			}
+		}]);
+		if (lazy.length === 0) return listed;
+		return [
+			...listed,
+			{
+				name: CAPABILITY_TOOL_NAMES.list,
+				description: `List tools not shown here (${lazy.map(({ name }) => name).join(", ")}).`,
+				inputSchema: listedSchema(LIST_SCHEMA),
+				annotations: READ_ONLY
+			},
+			{
+				name: CAPABILITY_TOOL_NAMES.describe,
+				description: "Parameters, guidance and an example for any tool, by id; detail: \"full\" for the whole schema.",
+				inputSchema: listedSchema(DESCRIBE_SCHEMA),
+				annotations: READ_ONLY
+			},
+			{
+				name: CAPABILITY_TOOL_NAMES.invoke,
+				description: "Run a tool by id with its arguments as `input`.",
+				inputSchema: listedSchema(INVOKE_SCHEMA),
+				annotations: {
+					readOnlyHint: false,
+					destructiveHint: lazy.some(destructiveOf),
+					openWorldHint: false
+				}
+			}
+		];
+	};
+	const callTool = async (name, args, context) => {
+		switch (name) {
+			case CAPABILITY_TOOL_NAMES.list: return toCallResult(listCapabilities(args));
+			case CAPABILITY_TOOL_NAMES.describe: return toCallResult(describeCapability(args));
+			case CAPABILITY_TOOL_NAMES.invoke: return await invokeCapability(args, context);
+			default: {
+				const tool = byName.get(name);
+				if (tool !== void 0) return await run(tool, args, context);
+				return toCallResult(failure({
+					code: KIT_ERROR_CODES.unknownTool,
+					message: `Unknown tool "${name}".`,
+					hint: `${didYouMean(closestNames(name, names))}Call ${CAPABILITY_TOOL_NAMES.list} to browse the rest.`
+				}));
+			}
+		}
+	};
+	return {
+		listTools,
+		callTool
+	};
+};
+//#endregion
+export { CAPABILITY_TOOL_NAMES, createToolSurface };

package/dist/mcp-kit/types.d.ts

@@ -0,0 +1,98 @@
+//#region src/mcp-kit/types.d.ts
+/**
+ * The shapes a tool surface is built from. Nothing here knows about a
+ * transport, a schema library, or the product serving the tools: a tool is a
+ * name, a JSON Schema, and an async function, and every answer is either a
+ * JSON payload or one error shape.
+ */
+/** A JSON Schema object, as plain JSON. */
+type JsonSchema = {
+  readonly [keyword: string]: unknown;
+};
+/** Whether a call only reads or may change state. */
+type ToolAccess = "read" | "write";
+/** One problem with one input value. */
+type ToolInputIssue = {
+  readonly path: string;
+  readonly message: string;
+};
+/**
+ * The one error shape every tool answers with. `code` is machine-readable,
+ * `hint` says what to do next, and `retryable` says whether the same call
+ * can succeed once the caller has done it (re-read, waited).
+ */
+type ToolError = {
+  readonly code: string;
+  readonly message: string;
+  readonly hint?: string;
+  readonly retryable: boolean;
+  readonly issues?: readonly ToolInputIssue[];
+  readonly details?: unknown;
+};
+type ToolOutcome = {
+  readonly ok: true;
+  readonly value: unknown;
+} | {
+  readonly ok: false;
+  readonly error: ToolError;
+};
+type ToolDefinition<Context> = {
+  readonly name: string;
+  /** One short sentence. A direct tool sends it on every turn, so every word costs. */
+  readonly summary: string;
+  /** Longer guidance, sent only by `describe_capability` with `detail: "full"`. */
+  readonly guide?: string;
+  /** Short guidance for the default, compact `describe_capability`. */
+  readonly brief?: string;
+  /** One example call's arguments, shown by the compact `describe_capability`. */
+  readonly example?: unknown;
+  readonly access: ToolAccess;
+  /** Whether a call can destroy or replace state. Defaults to `access === "write"`. */
+  readonly destructive?: boolean;
+  /** Groups lazy tools for `list_capabilities`' `domain` filter. */
+  readonly domain?: string;
+  /** Every argument the tool accepts: what calls are checked against. */
+  readonly inputSchema: JsonSchema;
+  /**
+   * What `describe_capability` returns as the input schema when a leaner
+   * rendering of `inputSchema` serves better (see `compactSchema`).
+   */
+  readonly describedSchema?: JsonSchema;
+  /**
+   * Present for a tool listed on every turn, with the compact schema it is
+   * listed with. A tool without it is reached through the capability tools.
+   */
+  readonly direct?: {
+    readonly inputSchema: JsonSchema;
+  };
+  /**
+   * Properties read exactly as sent, never leniently: switches that widen
+   * what a call may do (overwrite, repack) must be JSON `true` to count.
+   */
+  readonly exactProperties?: readonly string[];
+  readonly run: (args: Record<string, unknown>, context: Context) => Promise<ToolOutcome>;
+};
+/** A tool as `tools/list` advertises it. */
+type ListedTool = {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    [keyword: string]: unknown;
+  };
+  annotations: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    openWorldHint: boolean;
+  };
+};
+/** A `tools/call` answer: a JSON payload or `{ error }`, as text. */
+type ToolCallResult = {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  isError: boolean;
+};
+//#endregion
+export { JsonSchema, ListedTool, ToolAccess, ToolCallResult, ToolDefinition, ToolError, ToolInputIssue, ToolOutcome };

package/dist/mcp-kit/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp.d.ts

@@ -13,8 +13,14 @@ type FolioMcpServerOptions = {
   bounds?: FolioReadBounds;
   now?: () => Date;
 };
-/** The tool's MCP input schema: its own arguments plus the file envelope. */
+/** The tool's full MCP input schema: its own arguments plus the file envelope. */
 declare const mcpInputSchema: (tool: FolioFileToolSpec) => JsonObjectSchema;
+/**
+ * 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.
+ */
+declare const blockLines: (blocks: readonly unknown[]) => string;
+/** What `tools/list` returns. */
 declare const listMcpTools: () => Tool[];
 /** A low-level MCP server exposing the file tools; connect it to a transport. */
 declare const createFolioMcpServer: (options: FolioMcpServerOptions) => Server;
@@ -25,4 +31,4 @@ type ServeOptions = FolioMcpServerOptions & {
 /** Serve the file tools over stdio until the client disconnects. */
 declare const serveFolioMcp: ({ input, output, ...options }: ServeOptions) => Promise<void>;
 //#endregion
-export { FolioMcpServerOptions, MCP_READ_BOUNDS, createFolioMcpServer, listMcpTools, mcpInputSchema, serveFolioMcp };
+export { FolioMcpServerOptions, MCP_READ_BOUNDS, blockLines, createFolioMcpServer, listMcpTools, mcpInputSchema, serveFolioMcp };