@haddowg/json-api-mcp 0.0.0-stage → 1.2.0

package/dist/generate-CiLuqQJ0.mjs

@@ -0,0 +1,1474 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { isPolymorphic, resolvePaginator } from "@haddowg/json-api-client";
+//#region src/openapi.ts
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"patch",
+	"put",
+	"delete"
+];
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Follow a local `#/...` reference. `undefined` for anything else or a dangling one. */
+function resolvePointer(doc, ref) {
+	if (!ref.startsWith("#/")) return;
+	let node = doc;
+	for (const raw of ref.slice(2).split("/")) {
+		const segment = decodeURIComponent(raw).replace(/~1/g, "/").replace(/~0/g, "~");
+		if (!isObject(node) || !Object.hasOwn(node, segment)) return;
+		node = node[segment];
+	}
+	return node;
+}
+/** Follow `$ref`s until a node that isn't one. A cycle or dangling ref gives `undefined`. */
+function deref(doc, value) {
+	let node = value;
+	const seen = /* @__PURE__ */ new Set();
+	while (isObject(node) && typeof node["$ref"] === "string") {
+		const ref = node["$ref"];
+		if (seen.has(ref)) return;
+		seen.add(ref);
+		node = resolvePointer(doc, ref);
+	}
+	return node;
+}
+/** An operation's parameters, path-level ones included, with refs followed. */
+function operationParameters(doc, item, op) {
+	const out = /* @__PURE__ */ new Map();
+	for (const raw of [...item.parameters ?? [], ...op.parameters ?? []]) {
+		const param = deref(doc, raw);
+		if (param !== void 0 && typeof param.name === "string") out.set(`${param.in}:${param.name}`, param);
+	}
+	return [...out.values()];
+}
+//#endregion
+//#region src/outputs.ts
+/**
+* Each tool's output schema, generated from the descriptor and the document's resource schemas.
+* Output schemas aren't held to the portable subset inputs are: the model only reads them.
+*/
+const DROPPED = /* @__PURE__ */ new Set([
+	"example",
+	"examples",
+	"x-enum-varnames"
+]);
+/** A document schema with refs inlined, examples dropped and any cycle cut to `{}`. */
+function outputSchema(doc, value, stack = []) {
+	if (!isObject(value)) return value === false ? { not: {} } : {};
+	if (typeof value["$ref"] === "string") {
+		const ref = value["$ref"];
+		if (stack.includes(ref)) return {};
+		const { $ref: _ref, ...siblings } = value;
+		return {
+			...outputSchema(doc, resolvePointer(doc, ref), [...stack, ref]),
+			...outputSchema(doc, siblings, stack)
+		};
+	}
+	const out = {};
+	for (const [key, member] of Object.entries(value)) {
+		if (DROPPED.has(key)) continue;
+		if (key === "properties" && isObject(member)) {
+			const props = {};
+			for (const [name, prop] of Object.entries(member)) props[name] = outputSchema(doc, prop, stack);
+			out[key] = props;
+		} else if ((key === "items" || key === "additionalProperties" || key === "not") && isObject(member)) out[key] = outputSchema(doc, member, stack);
+		else if ((key === "allOf" || key === "anyOf" || key === "oneOf") && Array.isArray(member)) out[key] = member.map((m) => outputSchema(doc, m, stack));
+		else out[key] = member;
+	}
+	return out;
+}
+/** Index the document's resource object schemas by their type, preferring `<Type>Resource`. */
+function resourceSchemas(doc) {
+	const out = /* @__PURE__ */ new Map();
+	const entries = Object.entries(doc.components?.schemas ?? {});
+	const ordered = [...entries.filter(([name]) => name.endsWith("Resource")), ...entries.filter(([name]) => !name.endsWith("Resource"))];
+	for (const [, schema] of ordered) {
+		const props = isObject(schema["properties"]) ? schema["properties"] : void 0;
+		const typeConst = isObject(props?.["type"]) ? props["type"]["const"] : void 0;
+		const describesFields = props?.["attributes"] !== void 0 || props?.["relationships"] !== void 0;
+		if (typeof typeConst === "string" && describesFields && !out.has(typeConst)) out.set(typeConst, schema);
+	}
+	return out;
+}
+/** Every type an `include` path can reach from the primary types, the primary types included. */
+function reachableTypes(descriptor, primary, paths) {
+	const out = new Set(primary);
+	for (const path of paths) {
+		let current = [...primary];
+		for (const segment of path.split(".")) {
+			const next = [];
+			for (const type of current) for (const related of descriptor[type]?.relations[segment]?.types ?? []) {
+				out.add(related);
+				next.push(related);
+			}
+			current = next;
+		}
+	}
+	return out;
+}
+/** The include paths no more than `depth` relationships deep; all of them when `depth` is null. */
+function capIncludePaths(paths, depth) {
+	return depth === null ? [...paths] : paths.filter((path) => path.split(".").length <= depth);
+}
+/** The include paths an operation's `include` parameter lists. */
+function includePaths(doc, op) {
+	for (const raw of op.parameters ?? []) {
+		const param = deref(doc, raw);
+		if (param?.name === "include") {
+			const items = deref(doc, param.schema?.["items"]);
+			return Array.isArray(items?.["enum"]) ? items["enum"] : [];
+		}
+	}
+	return [];
+}
+const ref = (type) => ({ $ref: `#/$defs/${type}` });
+/** One type's flattened resource schema: id, type, attributes and relations, all optional but id and type. */
+function flatResource(doc, descriptor, schemas, type, expanded) {
+	const resource = schemas.get(type);
+	const attributes = outputSchema(doc, (isObject(resource?.["properties"]) ? resource["properties"] : {})["attributes"]);
+	const properties = {
+		id: { type: "string" },
+		type: {
+			type: "string",
+			const: type
+		}
+	};
+	if (isObject(attributes["properties"])) Object.assign(properties, attributes["properties"]);
+	for (const [name, relation] of Object.entries(descriptor[type]?.relations ?? {})) {
+		if (relation.writeOnly === true) continue;
+		const polymorphic = isPolymorphic(relation);
+		const identifier = polymorphic ? {
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					enum: [...relation.types]
+				},
+				id: { type: "string" }
+			},
+			required: ["type", "id"]
+		} : { type: "string" };
+		const full = relation.types.filter((t) => expanded.has(t)).map(ref);
+		const member = full.length === 0 ? identifier : { anyOf: [identifier, ...full] };
+		const target = relation.types.join(" or ");
+		properties[name] = relation.cardinality === "many" ? {
+			type: "array",
+			items: member,
+			description: `The related ${target} resources: ${polymorphic ? "type and id" : "ids"}, or the resources themselves when included.`
+		} : {
+			anyOf: [...full.length === 0 ? [identifier] : [identifier, ...full], { type: "null" }],
+			description: `The related ${target}: ${polymorphic ? "its type and id" : "its id"}, or the resource itself when included.`
+		};
+	}
+	const schema = {
+		type: "object",
+		properties,
+		required: ["id", "type"]
+	};
+	if (typeof resource?.["description"] === "string") schema["description"] = resource["description"];
+	return schema;
+}
+function defsFor(doc, descriptor, schemas, types) {
+	const defs = {};
+	for (const type of types) defs[type] = flatResource(doc, descriptor, schemas, type, types);
+	return defs;
+}
+/** The `meta` schema a success response declares, else a free-form object. */
+function responseMeta(ctx) {
+	for (const [status, raw] of Object.entries(ctx.operation.responses ?? {})) {
+		if (!status.startsWith("2")) continue;
+		const response = deref(ctx.doc, raw);
+		const schema = deref(ctx.doc, response?.content?.["application/vnd.api+json"]?.schema);
+		const meta = isObject(schema?.["properties"]) ? schema["properties"]["meta"] : void 0;
+		if (meta !== void 0) return outputSchema(ctx.doc, meta);
+	}
+	return { type: "object" };
+}
+const LINKS = {
+	type: "object",
+	description: "Pagination links. Pass one to this tool as `pageLink` to fetch that page; a missing link means there is no such page.",
+	properties: {
+		first: { type: "string" },
+		prev: { type: "string" },
+		next: { type: "string" },
+		last: { type: "string" }
+	}
+};
+/** A collection: `{ items, links, meta }`. */
+function collectionOutput(ctx, types) {
+	const reachable = reachableTypes(ctx.descriptor, types, ctx.includes);
+	return {
+		type: "object",
+		properties: {
+			items: {
+				type: "array",
+				items: types.length === 1 ? ref(types[0]) : { anyOf: types.map(ref) }
+			},
+			links: LINKS,
+			meta: {
+				...responseMeta(ctx),
+				description: "The document meta, such as page totals."
+			}
+		},
+		required: ["items", "links"],
+		$defs: defsFor(ctx.doc, ctx.descriptor, ctx.schemas, reachable)
+	};
+}
+/** One resource, flattened, at the root. */
+function resourceOutput(ctx, type) {
+	const reachable = reachableTypes(ctx.descriptor, [type], ctx.includes);
+	const defs = defsFor(ctx.doc, ctx.descriptor, ctx.schemas, reachable);
+	return {
+		...defs[type],
+		$defs: defs
+	};
+}
+/** A single read: `{ item }`, and for a to-one related read null when nothing is related. */
+function itemOutput(ctx, types, nullable) {
+	const reachable = reachableTypes(ctx.descriptor, types, ctx.includes);
+	return {
+		type: "object",
+		properties: { item: nullable ? {
+			anyOf: [...types.map(ref), { type: "null" }],
+			description: "The related resource, or null when there is none."
+		} : types.length === 1 ? {
+			...ref(types[0]),
+			description: "The resource."
+		} : {
+			anyOf: types.map(ref),
+			description: "The resource."
+		} },
+		required: ["item"],
+		$defs: defsFor(ctx.doc, ctx.descriptor, ctx.schemas, reachable)
+	};
+}
+/** A meta-only result: the document's `meta`. */
+function metaOutput(ctx) {
+	return {
+		...responseMeta(ctx),
+		type: "object"
+	};
+}
+/** A JSON:API result whose primary type the descriptor doesn't name. */
+const LOOSE_OUTPUT = { type: "object" };
+/** The URL an action answered with (generator contract 17): `{ url, type, expiresAt? }`. */
+function locationOutput(mediaType) {
+	return {
+		type: "object",
+		description: "The URL the action produced, such as a short-lived download link. The tool does not fetch it.",
+		properties: {
+			url: {
+				type: "string",
+				format: "uri-reference",
+				description: "The URL."
+			},
+			type: {
+				type: "string",
+				description: `The media type the URL serves. The action declares \`${mediaType}\`.`
+			},
+			expiresAt: {
+				type: "string",
+				format: "date-time",
+				description: "When the URL stops working. Absent when it does not expire."
+			}
+		},
+		required: ["url", "type"],
+		additionalProperties: false
+	};
+}
+/** An action's usual output or the URL it may answer with instead, sharing the root `$defs`. */
+function orLocation(schema, mediaType) {
+	const { $defs, ...rest } = schema;
+	return {
+		type: "object",
+		anyOf: [rest, locationOutput(mediaType)],
+		...$defs === void 0 ? {} : { $defs }
+	};
+}
+//#endregion
+//#region src/portable.ts
+/**
+* Convert document schemas into tool input schemas every major model API accepts: OpenAI's strict
+* function calling and Anthropic's strict tool use. That means no `oneOf`, `allOf`, `if`, `then`
+* or `$ref`, every object closed with `additionalProperties: false` and listing all its
+* properties as required, an optional property made nullable instead, and no numeric, length or
+* pattern keywords. Constraints that can't stay as keywords move into the description, and a
+* value with no portable shape, such as a free-form object, is taken as JSON text.
+*
+* Each schema comes with a {@link Decoder} that turns the arguments a model sends back into the
+* value the API expects: a `null` the conversion added is dropped, and JSON text is parsed.
+*/
+/** The string formats both APIs accept. */
+const PORTABLE_FORMATS = /* @__PURE__ */ new Set([
+	"date-time",
+	"time",
+	"date",
+	"duration",
+	"email",
+	"hostname",
+	"ipv4",
+	"ipv6",
+	"uuid"
+]);
+/** Objects may nest this deep before a value is taken as JSON text instead. */
+const MAX_DEPTH = 6;
+const VALUE = { kind: "value" };
+/** Add `null` to a portable schema's allowed values. */
+function nullable(schema) {
+	const out = { ...schema };
+	if (Array.isArray(out["anyOf"])) {
+		const branches = out["anyOf"];
+		if (!branches.some((b) => b["type"] === "null")) out["anyOf"] = [...branches, { type: "null" }];
+		return out;
+	}
+	const type = out["type"];
+	if (typeof type === "string" && type !== "null") out["type"] = [type, "null"];
+	else if (Array.isArray(type) && !type.includes("null")) out["type"] = [...type, "null"];
+	if (Array.isArray(out["enum"]) && !out["enum"].includes(null)) out["enum"] = [...out["enum"], null];
+	return out;
+}
+/** Whether a portable schema already allows `null`. */
+function allowsNull(schema) {
+	const type = schema["type"];
+	if (type === "null" || Array.isArray(type) && type.includes("null")) return true;
+	return Array.isArray(schema["anyOf"]) && schema["anyOf"].some(allowsNull);
+}
+/** A closed object schema listing every property as required, as strict mode wants. */
+function closedObject(properties, description) {
+	const schema = {
+		type: "object",
+		properties,
+		required: Object.keys(properties),
+		additionalProperties: false
+	};
+	if (description !== void 0 && description !== "") schema["description"] = description;
+	return schema;
+}
+const jsonText = (description) => ({
+	schema: {
+		type: "string",
+		description: joinText(description, "Send the value as JSON text.")
+	},
+	decoder: { kind: "json" }
+});
+function joinText(...parts) {
+	return parts.filter((part) => part !== void 0 && part.trim() !== "").map((part) => part.trim()).join(" ");
+}
+/** The non-null `type` keys a schema names. */
+function typeKeys(schema) {
+	const raw = schema["type"];
+	const list = typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw : [];
+	return {
+		types: list.filter((t) => t !== "null"),
+		nullable: list.includes("null")
+	};
+}
+function inferType(values) {
+	const types = new Set(values.filter((v) => v !== null).map((v) => typeof v === "number" ? Number.isInteger(v) ? "integer" : "number" : typeof v));
+	if (types.size === 1) return [...types][0];
+	if (types.size === 2 && types.has("integer") && types.has("number")) return "number";
+}
+/** A range as a sentence, such as `Between 1 and 200 characters.` */
+function bounds(min, max, unit) {
+	const suffix = unit === "" ? "" : ` ${unit}`;
+	if (min !== void 0 && max !== void 0) return `Between ${min} and ${max}${suffix}.`;
+	if (min !== void 0) return `At least ${min}${suffix}.`;
+	if (max !== void 0) return `At most ${max}${suffix}.`;
+}
+/** The constraints a schema states that can't stay as keywords, as sentences. */
+function constraintNote(schema) {
+	const num = (key) => typeof schema[key] === "number" ? schema[key] : void 0;
+	const notes = [
+		bounds(num("minLength"), num("maxLength"), "characters"),
+		bounds(num("minimum"), num("maximum"), ""),
+		num("exclusiveMinimum") === void 0 ? void 0 : `Greater than ${num("exclusiveMinimum")}.`,
+		num("exclusiveMaximum") === void 0 ? void 0 : `Less than ${num("exclusiveMaximum")}.`,
+		num("multipleOf") === void 0 ? void 0 : `A multiple of ${num("multipleOf")}.`,
+		bounds(num("minItems"), num("maxItems"), "items"),
+		typeof schema["pattern"] === "string" ? `Matches the pattern \`${schema["pattern"]}\`.` : void 0,
+		typeof schema["format"] === "string" && !PORTABLE_FORMATS.has(schema["format"]) ? `Format: ${schema["format"]}.` : void 0,
+		schema["default"] === void 0 ? void 0 : `Defaults to ${JSON.stringify(schema["default"])}.`
+	].filter((note) => note !== void 0);
+	return notes.length === 0 ? void 0 : notes.join(" ");
+}
+/** Merge an `allOf` into one schema: the members' keywords, then the outer node's own. */
+function mergeAllOf(doc, node, stack) {
+	const members = node["allOf"];
+	const merged = {};
+	const properties = {};
+	const required = /* @__PURE__ */ new Set();
+	for (const member of members) {
+		const resolved = follow(doc, member, stack);
+		if (resolved === void 0) return;
+		const inner = Array.isArray(resolved.node["allOf"]) ? mergeAllOf(doc, resolved.node, resolved.stack) : resolved.node;
+		if (inner === void 0) return;
+		Object.assign(properties, isObject(inner["properties"]) ? inner["properties"] : {});
+		for (const key of Array.isArray(inner["required"]) ? inner["required"] : []) required.add(key);
+		Object.assign(merged, inner);
+	}
+	const { allOf: _allOf, ...own } = node;
+	Object.assign(merged, own);
+	if (Object.keys(properties).length > 0) merged["properties"] = {
+		...properties,
+		...isObject(own["properties"]) ? own["properties"] : {}
+	};
+	if (required.size > 0 || Array.isArray(own["required"])) merged["required"] = [...required, ...Array.isArray(own["required"]) ? own["required"] : []];
+	return merged;
+}
+/**
+* Follow a node's `$ref`s, keeping the outermost description. `undefined` on a cycle, which the
+* caller then takes as JSON text.
+*/
+function follow(doc, value, stack) {
+	let node = value;
+	let description;
+	let path = stack;
+	while (isObject(node) && typeof node["$ref"] === "string") {
+		const ref = node["$ref"];
+		if (description === void 0 && typeof node["description"] === "string") description = node["description"];
+		if (path.includes(ref)) return;
+		path = [...path, ref];
+		node = resolvePointer(doc, ref);
+	}
+	if (node === true) return {
+		node: {},
+		stack: path
+	};
+	if (!isObject(node)) return;
+	return {
+		node: description === void 0 ? node : {
+			...node,
+			description
+		},
+		stack: path
+	};
+}
+const isNull = (b) => isObject(b) && b["type"] === "null";
+/** Convert one document schema into a portable input schema and its decoder. */
+function toPortable(doc, raw, stack = [], depth = 0) {
+	const outerDescription = isObject(raw) && typeof raw["description"] === "string" ? raw["description"] : void 0;
+	const followed = follow(doc, raw, stack);
+	if (followed === void 0) return jsonText(outerDescription);
+	let node = followed.node;
+	const path = followed.stack;
+	if (Array.isArray(node["allOf"])) {
+		const merged = mergeAllOf(doc, node, path);
+		if (merged === void 0) return jsonText(outerDescription);
+		node = merged;
+	}
+	const description = typeof node["description"] === "string" ? node["description"] : void 0;
+	const branches = node["oneOf"] ?? node["anyOf"];
+	if (Array.isArray(branches)) {
+		const { oneOf: _oneOf, anyOf: _anyOf, ...rest } = node;
+		const others = branches.filter((b) => !isNull(b));
+		const withNull = others.length < branches.length;
+		if (others.length === 1) {
+			const resolved = follow(doc, others[0], path);
+			if (resolved === void 0) return jsonText(description);
+			const single = toPortable(doc, {
+				...resolved.node,
+				...rest
+			}, resolved.stack, depth);
+			return withNull ? {
+				...single,
+				schema: nullable(single.schema)
+			} : single;
+		}
+		if (depth >= MAX_DEPTH) return jsonText(description);
+		const converted = others.map((b) => toPortable(doc, b, path, depth + 1).schema);
+		const schema = { anyOf: withNull ? [...converted, { type: "null" }] : converted };
+		const text = joinText(description, constraintNote(node));
+		if (text !== "") schema["description"] = text;
+		return {
+			schema,
+			decoder: VALUE
+		};
+	}
+	let { types, nullable: isNullable } = typeKeys(node);
+	const enumValues = Array.isArray(node["enum"]) ? node["enum"] : node["const"] !== void 0 ? [node["const"]] : void 0;
+	if (enumValues !== void 0 && enumValues.includes(null)) isNullable = true;
+	if (types.length === 0) {
+		const inferred = enumValues !== void 0 ? inferType(enumValues) : isObject(node["properties"]) ? "object" : node["items"] !== void 0 ? "array" : void 0;
+		if (inferred === void 0) return jsonText(description);
+		types = [inferred];
+	}
+	if (types.length > 1) {
+		const schema = { anyOf: [...types.map((type) => ({ type })), ...isNullable ? [{ type: "null" }] : []] };
+		if (description !== void 0) schema["description"] = description;
+		return {
+			schema,
+			decoder: VALUE
+		};
+	}
+	const type = types[0];
+	const text = joinText(description, constraintNote(node));
+	let result;
+	if (type === "object") {
+		const props = isObject(node["properties"]) ? node["properties"] : {};
+		const writable = Object.entries(props).filter(([, prop]) => !(isObject(prop) && prop["readOnly"] === true));
+		if (writable.length === 0 || depth >= MAX_DEPTH) return jsonText(text);
+		const required = new Set(Array.isArray(node["required"]) ? node["required"] : []);
+		const properties = {};
+		const decoders = {};
+		for (const [key, prop] of writable) {
+			const converted = toPortable(doc, prop, path, depth + 1);
+			const addNull = !required.has(key) && !allowsNull(converted.schema);
+			properties[key] = addNull ? nullable(converted.schema) : converted.schema;
+			decoders[key] = {
+				decoder: converted.decoder,
+				nullMeansOmit: addNull
+			};
+		}
+		result = {
+			schema: closedObject(properties, text),
+			decoder: {
+				kind: "object",
+				props: decoders
+			}
+		};
+	} else if (type === "array") {
+		if (node["items"] === void 0 || node["items"] === true || depth >= MAX_DEPTH) return jsonText(text);
+		const items = toPortable(doc, node["items"], path, depth + 1);
+		result = {
+			schema: {
+				type: "array",
+				items: items.schema
+			},
+			decoder: {
+				kind: "array",
+				items: items.decoder
+			}
+		};
+		if (text !== "") result.schema["description"] = text;
+	} else {
+		const schema = { type };
+		if (text !== "") schema["description"] = text;
+		if (enumValues !== void 0) schema["enum"] = enumValues.filter((v) => v !== null);
+		if (type === "string" && typeof node["format"] === "string" && PORTABLE_FORMATS.has(node["format"])) schema["format"] = node["format"];
+		result = {
+			schema,
+			decoder: VALUE
+		};
+	}
+	return isNullable ? {
+		...result,
+		schema: nullable(result.schema)
+	} : result;
+}
+//#endregion
+//#region src/inputs.ts
+/**
+* Each tool's input schema, and the plan the call handler follows to turn a model's arguments
+* back into a client call. Every schema is portable (see ./portable.ts): a parameter the API
+* doesn't require is nullable, and `null` at the top level means "not given".
+*/
+/** The include description, for a tool capped at `depth` relationships or uncapped. */
+function includeDescription(depth) {
+	return `Relationship paths to include in the result (JSON:API compound documents). An included relation comes back as the related resource in place of its id.${depth === null ? "" : depth === 1 ? " Only direct relationships can be included, so relations of an included resource come back as ids." : ` Paths reach at most ${depth} relationships deep, and relations below that come back as ids.`} Leave null to include nothing.`;
+}
+const FIELDS_DESCRIPTION = "Sparse fieldsets (JSON:API): per resource type, the attribute and relationship names to return. A relationship only has a value in the result when it is also included. Leave a type null for its default fields.";
+const WITH_COUNT_DESCRIPTION = "Set true to have the total number of results counted and returned in meta. Counting can be slow on a large collection, so leave it null unless the total is needed.";
+const PAGE_LINK_DESCRIPTION = "A pagination link (first, prev, next or last) copied from the links of an earlier result of this same tool, to fetch that page. When given, every other argument is ignored.";
+const nullableString = (description) => nullable({
+	type: "string",
+	description
+});
+const idSchema = (description) => ({
+	type: "string",
+	description
+});
+/** The `filter[...]` parameters as one closed object, each member nullable. */
+function filterInput(doc, params) {
+	const properties = {};
+	const props = {};
+	for (const param of params) {
+		const match = /^filter\[(.+)\]$/.exec(param.name);
+		if (param.in !== "query" || match === null) continue;
+		const converted = toPortable(doc, param.schema ?? {}, [], 1);
+		const schema = { ...converted.schema };
+		if (typeof param.description === "string" && schema["description"] === void 0) schema["description"] = param.description;
+		else if (typeof param.description === "string") schema["description"] = `${param.description} ${String(schema["description"])}`;
+		const addNull = !allowsNull(schema);
+		properties[match[1]] = addNull ? nullable(schema) : schema;
+		props[match[1]] = {
+			decoder: converted.decoder,
+			nullMeansOmit: true
+		};
+	}
+	if (Object.keys(properties).length === 0) return;
+	return {
+		schema: nullable(closedObject(properties, "Filters to apply. Leave a filter null to not apply it, or the whole object null for none.")),
+		decoder: {
+			kind: "object",
+			props
+		}
+	};
+}
+/** The page parameter's size bound and default for the strategy that answers by default. */
+function pageBounds(doc, params, kind, sizeKey) {
+	let schema = deref(doc, params.find((p) => p.in === "query" && p.name === "page")?.schema);
+	const branches = schema?.["oneOf"] ?? schema?.["anyOf"];
+	if (Array.isArray(branches)) schema = branches.map((b) => deref(doc, b)).find((b) => isObject(b?.["x-paginator"]) && b["x-paginator"]["strategy"] === kind);
+	const size = isObject(schema?.["properties"]) ? schema["properties"][sizeKey] : void 0;
+	if (!isObject(size)) return {};
+	const out = {};
+	if (typeof size["maximum"] === "number") out.max = size["maximum"];
+	if (typeof size["default"] === "number") out.default = size["default"];
+	return out;
+}
+/** A read tool's query arguments, read from the operation's own parameters. */
+function queryInput(ctx, paginator, collection) {
+	const { doc, params, defaultPageSize, includeDepth } = ctx;
+	const properties = {};
+	const plan = {
+		sort: false,
+		include: false,
+		fields: [],
+		paginated: false
+	};
+	if (collection) {
+		const filter = filterInput(doc, params);
+		if (filter !== void 0) {
+			properties["filter"] = filter.schema;
+			plan.filter = filter.decoder;
+		}
+		const sortItems = deref(doc, params.find((p) => p.in === "query" && p.name === "sort")?.schema?.["items"]);
+		const tokens = Array.isArray(sortItems?.["enum"]) ? sortItems["enum"] : [];
+		if (tokens.length > 0) {
+			properties["sort"] = nullable({
+				type: "array",
+				items: {
+					type: "string",
+					enum: tokens
+				},
+				description: "Fields to sort by, in order. A leading `-` sorts that field descending. Leave null for the default order."
+			});
+			plan.sort = true;
+		}
+	}
+	const paths = params.some((p) => p.in === "query" && p.name === "include") ? capIncludePaths(includePaths(doc, ctx.operation), includeDepth) : [];
+	if (paths.length > 0) {
+		properties["include"] = nullable({
+			type: "array",
+			items: {
+				type: "string",
+				enum: paths
+			},
+			description: includeDescription(includeDepth)
+		});
+		plan.include = true;
+		plan.includePaths = paths;
+	}
+	const fieldTypes = params.map((p) => p.in === "query" ? /^fields\[(.+)\]$/.exec(p.name)?.[1] : void 0).filter((t) => t !== void 0);
+	if (fieldTypes.length > 0) {
+		const members = {};
+		for (const type of fieldTypes) members[type] = nullable({
+			type: "array",
+			items: { type: "string" }
+		});
+		properties["fields"] = nullable(closedObject(members, FIELDS_DESCRIPTION));
+		plan.fields = fieldTypes;
+	}
+	if (collection && paginator !== void 0) {
+		const resolved = resolvePaginator(paginator);
+		if (resolved.kind !== "none") {
+			plan.paginated = true;
+			const sizeKey = resolved.keys.size ?? resolved.keys.limit;
+			if (sizeKey !== void 0) {
+				const bounds = pageBounds(doc, params, resolved.kind, sizeKey);
+				const fallback = Math.min(defaultPageSize, bounds.max ?? defaultPageSize);
+				plan.sizeKey = sizeKey;
+				plan.defaultPageSize = fallback;
+				if (bounds.max !== void 0) plan.maxPageSize = bounds.max;
+				properties["pageSize"] = nullable({
+					type: "integer",
+					description: `How many results a page holds, ${bounds.max === void 0 ? "at least 1" : `1 to ${bounds.max}`}. Leave null for ${fallback}.`
+				});
+			}
+			properties["pageLink"] = nullableString(PAGE_LINK_DESCRIPTION);
+		}
+	}
+	return {
+		properties,
+		plan
+	};
+}
+/** The `data` member's schema of a write request body. */
+function requestData(doc, schema) {
+	const body = deref(doc, schema);
+	return deref(doc, isObject(body?.["properties"]) ? body["properties"]["data"] : void 0);
+}
+/** A relation's write argument: an id, ids, or `{ type, id }` objects for a polymorphic one. */
+function relationArgument(name, relation, allowNull) {
+	const polymorphic = isPolymorphic(relation);
+	const one = polymorphic ? closedObject({
+		type: {
+			type: "string",
+			enum: [...relation.types]
+		},
+		id: { type: "string" }
+	}) : { type: "string" };
+	const target = polymorphic ? relation.types.join(" or ") : relation.types[0];
+	if (relation.cardinality === "many") return {
+		type: "array",
+		items: one,
+		description: polymorphic ? `The ${name} relationship: every related resource, as its type (${target}) and id.` : `The ${name} relationship: the ids of the related \`${target}\` resources.`
+	};
+	const schema = {
+		...one,
+		description: polymorphic ? `The ${name} relationship: the related resource's type (${target}) and id.` : `The ${name} relationship: the id of the related \`${target}\` resource.`
+	};
+	return allowNull ? nullable(schema) : schema;
+}
+/**
+* A flat write input from a JSON:API write request body: the attributes and relationships as
+* one object, the API's required members required, the rest nullable.
+*/
+function writeInput(doc, descriptor, type, bodySchema, mode) {
+	const properties = {};
+	const required = [];
+	const fields = {};
+	const clearable = [];
+	const data = requestData(doc, bodySchema);
+	const dataProps = isObject(data?.["properties"]) ? data["properties"] : {};
+	const attributes = deref(doc, dataProps["attributes"]);
+	const converted = attributes === void 0 ? void 0 : toPortable(doc, attributes, [], 0);
+	if (converted !== void 0 && converted.decoder.kind === "object") {
+		const attrRequired = new Set(Array.isArray(attributes["required"]) ? attributes["required"] : []);
+		const attrProps = converted.schema["properties"];
+		for (const [name, prop] of Object.entries(converted.decoder.props)) {
+			const schema = attrProps[name];
+			properties[name] = schema;
+			const isRequired = mode !== "update" && attrRequired.has(name);
+			fields[name] = { property: {
+				decoder: prop.decoder,
+				nullMeansOmit: !isRequired
+			} };
+			if (isRequired) required.push(name);
+			if (!prop.nullMeansOmit && allowsNull(schema)) clearable.push(name);
+		}
+	}
+	const relationships = deref(doc, dataProps["relationships"]);
+	const relProps = isObject(relationships?.["properties"]) ? relationships["properties"] : {};
+	const relRequired = new Set(Array.isArray(relationships?.["required"]) ? relationships["required"] : []);
+	for (const [name, raw] of Object.entries(relProps)) {
+		const relation = descriptor[type]?.relations[name];
+		if (relation === void 0 || name in properties) continue;
+		const relSchema = deref(doc, raw);
+		const linkage = isObject(relSchema?.["properties"]) ? relSchema["properties"]["data"] : void 0;
+		const linkageAllowsNull = relation.cardinality === "one" && JSON.stringify(deref(doc, linkage) ?? {}).includes("\"null\"");
+		const isRequired = mode !== "update" && relRequired.has(name);
+		const schema = relationArgument(name, relation, linkageAllowsNull);
+		properties[name] = isRequired || allowsNull(schema) ? schema : nullable(schema);
+		fields[name] = {
+			relation: isPolymorphic(relation) ? {
+				cardinality: relation.cardinality,
+				types: relation.types,
+				polymorphic: true
+			} : {
+				cardinality: relation.cardinality,
+				types: relation.types
+			},
+			property: {
+				decoder: { kind: "value" },
+				nullMeansOmit: !isRequired
+			}
+		};
+		if (isRequired) required.push(name);
+		if (linkageAllowsNull) clearable.push(name);
+	}
+	let clientId = "none";
+	if (mode === "create") {
+		const idProp = dataProps["id"];
+		const dataRequired = Array.isArray(data?.["required"]) ? data["required"] : [];
+		if (idProp !== void 0 && idProp !== false) clientId = dataRequired.includes("id") ? "required" : "optional";
+	}
+	return {
+		properties,
+		required,
+		plan: {
+			fields,
+			clientId,
+			clearable: mode === "update" ? clearable : []
+		}
+	};
+}
+/** Close a root object: every property required, the optional ones already nullable. */
+function root(properties, required) {
+	const out = {};
+	for (const [name, schema] of Object.entries(properties)) out[name] = required.includes(name) || allowsNull(schema) ? schema : nullable(schema);
+	return closedObject(out);
+}
+/** A list or to-many related read. */
+function collectionInput(ctx, paginator, parent, countable) {
+	const { properties, plan } = queryInput(ctx, paginator, true);
+	if (countable !== void 0 && countable.tokens.includes("_self_")) {
+		properties["withCount"] = nullable({
+			type: "boolean",
+			description: WITH_COUNT_DESCRIPTION
+		});
+		plan.countProfile = countable.profile;
+	}
+	const props = {};
+	const required = [];
+	if (parent !== void 0) {
+		props["id"] = idSchema(`The id of the \`${parent.type}\` resource whose ${parent.relation} to list.`);
+		required.push("id");
+	}
+	return {
+		schema: root({
+			...props,
+			...properties
+		}, required),
+		query: plan
+	};
+}
+/** A get or to-one related read. */
+function singleInput(ctx, description) {
+	const { properties, plan } = queryInput(ctx, void 0, false);
+	return {
+		schema: root({
+			id: idSchema(description),
+			...properties
+		}, ["id"]),
+		query: plan
+	};
+}
+/** A create, from the type's create request body. */
+function createInput(ctx, type) {
+	const schema = deref(ctx.doc, ctx.operation.requestBody)?.content?.["application/vnd.api+json"]?.schema;
+	const write = writeInput(ctx.doc, ctx.descriptor, type, schema, "create");
+	const properties = {};
+	const required = [...write.required];
+	if (write.plan.clientId !== "none") {
+		properties["id"] = idSchema(`The id to give the new \`${type}\` resource.`);
+		if (write.plan.clientId === "required") required.push("id");
+	}
+	return {
+		schema: root({
+			...properties,
+			...write.properties
+		}, required),
+		write: write.plan
+	};
+}
+/** An update, from the type's update request body. */
+function updateInput(ctx, type) {
+	const schema = deref(ctx.doc, ctx.operation.requestBody)?.content?.["application/vnd.api+json"]?.schema;
+	const write = writeInput(ctx.doc, ctx.descriptor, type, schema, "update");
+	const properties = { id: idSchema(`The id of the \`${type}\` resource to update.`) };
+	const clearable = "clear" in write.properties ? [] : write.plan.clearable;
+	const extra = {};
+	if (clearable.length > 0) extra["clear"] = nullable({
+		type: "array",
+		items: {
+			type: "string",
+			enum: [...clearable]
+		},
+		description: "Fields to set to null. Every other argument left null keeps its current value."
+	});
+	return {
+		schema: root({
+			...properties,
+			...write.properties,
+			...extra
+		}, ["id"]),
+		write: {
+			...write.plan,
+			clearable
+		}
+	};
+}
+/** A delete. */
+function deleteInput(type) {
+	return { schema: root({ id: idSchema(`The id of the \`${type}\` resource to delete.`) }, ["id"]) };
+}
+/** The request media type a model can send to an action, in order of preference. */
+function pickBody(ctx) {
+	const body = deref(ctx.doc, ctx.operation.requestBody);
+	const content = Object.entries(body?.content ?? {});
+	if (content.length === 0) return "none";
+	const find = (test) => content.find(([mediaType]) => test(mediaType.toLowerCase()));
+	const document = find((m) => m === "application/vnd.api+json");
+	if (document !== void 0) return {
+		mediaType: document[0],
+		schema: document[1].schema,
+		kind: "document"
+	};
+	const json = find((m) => m === "application/json" || m.endsWith("+json"));
+	if (json !== void 0) return {
+		mediaType: json[0],
+		schema: json[1].schema,
+		kind: "json"
+	};
+	const text = find((m) => m.startsWith("text/"));
+	if (text !== void 0) return {
+		mediaType: text[0],
+		schema: { type: "string" },
+		kind: "text"
+	};
+	const form = content.find(([mediaType, media]) => {
+		const m = mediaType.toLowerCase();
+		const schema = deref(ctx.doc, media.schema);
+		return (m === "application/x-www-form-urlencoded" || m.startsWith("multipart/")) && isObject(schema?.["properties"]) && Object.keys(schema["properties"]).length > 0;
+	});
+	if (form !== void 0) return {
+		mediaType: form[0],
+		schema: form[1].schema,
+		kind: "form"
+	};
+}
+/**
+* A custom action's input: the resource id at resource scope, then the body. A JSON:API body
+* whose type the descriptor knows is flat, like a create; any other body is one `body` argument.
+* `undefined` when every media type the action takes is one a model can't send, such as binary.
+*/
+function actionInput(ctx, type, name, action) {
+	const properties = {};
+	const required = [];
+	if (action.scope === "resource") {
+		properties["id"] = idSchema(`The id of the \`${type}\` resource to run ${name} on.`);
+		required.push("id");
+	}
+	const picked = pickBody(ctx);
+	if (picked === void 0) return;
+	if (picked === "none") return {
+		schema: root(properties, required),
+		action: { kind: "none" }
+	};
+	const body = deref(ctx.doc, ctx.operation.requestBody);
+	const bodyRequired = body?.required === true;
+	if (picked.kind === "document" && action.inputType !== void 0) {
+		const write = writeInput(ctx.doc, ctx.descriptor, action.inputType, picked.schema, "action");
+		for (const [key, schema] of Object.entries(write.properties)) if (!(key in properties)) properties[key] = schema;
+		return {
+			schema: root(properties, [...required, ...write.required.filter((r) => r !== "id")]),
+			action: {
+				kind: "flat",
+				write: write.plan
+			}
+		};
+	}
+	const converted = toPortable(ctx.doc, picked.schema ?? {}, [], 1);
+	const description = typeof body?.description === "string" ? body.description : `The request body, as ${picked.mediaType}.`;
+	properties["body"] = {
+		...converted.schema,
+		description: converted.schema["description"] === void 0 ? description : `${description} ${String(converted.schema["description"])}`
+	};
+	if (bodyRequired) required.push("body");
+	return {
+		schema: root(properties, required),
+		action: {
+			kind: "body",
+			decoder: converted.decoder,
+			required: bodyRequired,
+			mediaType: picked.mediaType,
+			mediaKind: picked.kind
+		}
+	};
+}
+//#endregion
+//#region src/names.ts
+/** The name pattern OpenAI's and Anthropic's tool names share. */
+const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+const CRUD = {
+	fetchCollection: "list",
+	fetchOne: "get",
+	create: "create",
+	update: "update",
+	delete: "delete"
+};
+/**
+* Parse an `operationId` into what a tool needs. `undefined` for an operation that isn't a tool:
+* relationship endpoints, Atomic Operations, or an id this package doesn't recognise.
+*/
+function parseOperationId(operationId) {
+	const parts = operationId.split(".");
+	const [verb, type] = parts;
+	if (verb === void 0 || type === void 0 || type === "") return;
+	const crud = CRUD[verb];
+	if (crud !== void 0) return parts.length === 2 ? {
+		kind: crud,
+		type
+	} : void 0;
+	if (verb === "fetchRelated" && parts.length === 3 && parts[2] !== "") return {
+		kind: "related",
+		type,
+		relation: parts[2]
+	};
+	if (verb === "action" && parts[2] !== void 0 && parts[2] !== "") {
+		if (parts.length === 3) return {
+			kind: "action",
+			type,
+			action: parts[2]
+		};
+		const method = parts[3];
+		if (parts.length === 4 && HTTP_METHODS.includes(method)) return {
+			kind: "action",
+			type,
+			action: parts[2],
+			method
+		};
+	}
+}
+const snake = (value) => value.replace(/-/g, "_");
+/**
+* The tool name for a parsed `operationId`: noun first, the type as the document spells it with
+* kebab-case turned into snake_case. A related read ends in `list` or `get` by the relation's
+* cardinality; an action is named after its path, plus the method for a multi-method action.
+*/
+function toolName(parsed, descriptor) {
+	const type = snake(parsed.type);
+	switch (parsed.kind) {
+		case "related": {
+			const verb = (descriptor[parsed.type]?.relations[parsed.relation])?.cardinality === "one" ? "get" : "list";
+			return `${type}_${snake(parsed.relation)}_${verb}`;
+		}
+		case "action": return parsed.method === void 0 ? `${type}_${snake(parsed.action)}` : `${type}_${snake(parsed.action)}_${parsed.method}`;
+		default: return `${type}_${parsed.kind}`;
+	}
+}
+/** Thrown when the tools can't be named: a name too long, with a stray character, or a clash. */
+var ToolNameError = class extends Error {
+	problems;
+	constructor(problems) {
+		super(`Cannot build MCP tools from this document:\n- ${problems.join("\n- ")}`);
+		this.name = "ToolNameError";
+		this.problems = problems;
+	}
+};
+/** Collect every naming problem across the tools, so one build reports them all. */
+function checkToolNames(tools) {
+	const problems = [];
+	const byName = /* @__PURE__ */ new Map();
+	for (const { name, operationId } of tools) {
+		if (name.length > 64) problems.push(`"${name}" (${operationId}) is ${name.length} characters; tool names allow 64`);
+		else if (!TOOL_NAME_PATTERN.test(name)) problems.push(`"${name}" (${operationId}) has characters outside [a-zA-Z0-9_-]`);
+		byName.set(name, [...byName.get(name) ?? [], operationId]);
+	}
+	for (const [name, ids] of byName) if (ids.length > 1) problems.push(`"${name}" is the tool name of ${ids.join(" and ")}`);
+	if (problems.length > 0) throw new ToolNameError(problems);
+}
+//#endregion
+//#region src/safety.ts
+/** The vendor extension an action's operation declares its safety in. */
+const SAFETY_EXTENSION = "x-safety";
+/**
+* Read an action's declared safety from its operation. An operation without the extension, or
+* with one this package can't read, declares nothing.
+*/
+function readActionSafety(operation) {
+	const raw = operation[SAFETY_EXTENSION];
+	const safety = {};
+	if (!isObject(raw)) return safety;
+	for (const key of [
+		"readOnly",
+		"destructive",
+		"idempotent"
+	]) if (typeof raw[key] === "boolean") safety[key] = raw[key];
+	return safety;
+}
+//#endregion
+//#region src/scopes.ts
+/** The descriptor's key for each kind's operation in a type's `scopes`. */
+const SCOPE_KEYS = {
+	list: "fetchCollection",
+	get: "fetchOne",
+	create: "create",
+	update: "update",
+	delete: "delete"
+};
+/** The scopes the descriptor says an operation needs, or `undefined` when it names none. */
+function descriptorScopes(op) {
+	let scopes;
+	if (op.kind === "action") scopes = op.actionDescriptor?.scopes;
+	else if (op.kind === "related") scopes = op.resource.scopes?.[`fetchRelated.${op.relation ?? ""}`];
+	else scopes = op.resource.scopes?.[SCOPE_KEYS[op.kind]];
+	return scopes === void 0 || scopes.length === 0 ? void 0 : scopes;
+}
+//#endregion
+//#region src/catalogue.ts
+function annotations(op) {
+	switch (op.kind) {
+		case "list":
+		case "get":
+		case "related": return { readOnlyHint: true };
+		case "create":
+		case "update": return {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		};
+		case "delete": return {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		};
+		case "action": {
+			const safety = actionSafety(op);
+			const out = {};
+			if (safety.readOnly !== void 0) out.readOnlyHint = safety.readOnly;
+			if (safety.destructive !== void 0) out.destructiveHint = safety.destructive;
+			if (safety.idempotent !== void 0) out.idempotentHint = safety.idempotent;
+			return Object.keys(out).length > 0 ? out : void 0;
+		}
+	}
+}
+/**
+* An action's declared safety: the flags its descriptor entry carries, with the operation's own
+* `x-safety` winning where both say. A codegen descriptor mirrors `x-safety`, so they agree.
+*/
+function actionSafety(op) {
+	const safety = {};
+	const declared = op.actionDescriptor;
+	for (const key of [
+		"readOnly",
+		"destructive",
+		"idempotent"
+	]) {
+		const value = declared?.[key];
+		if (typeof value === "boolean") safety[key] = value;
+	}
+	return {
+		...safety,
+		...readActionSafety(op.operation)
+	};
+}
+/** The descriptor entry an action operation calls: the one at its path and method. */
+function findAction(op) {
+	return Object.entries(op.resource.actions ?? {}).find(([, action]) => action.path === op.path && (action.method ?? "POST") === op.method);
+}
+function actionResult(action) {
+	if (action.output === "location") return "location";
+	if (action.output === "none") return action.rawOutput !== void 0 && action.rawOutput.length > 0 ? "raw" : "none";
+	if (action.output === "meta") return "meta";
+	if (action.outputType === void 0) return "loose";
+	return action.outputCardinality === "many" ? "collection" : "resource";
+}
+/**
+* An action's output schema. One that may answer with a URL instead of its usual result takes
+* either; one that only answers with a URL takes the URL.
+*/
+function actionOutput(ctx, action) {
+	const usual = documentOutput(ctx, action);
+	if (action.location === void 0) return usual;
+	return usual === void 0 ? locationOutput(action.location.mediaType) : orLocation(usual, action.location.mediaType);
+}
+function documentOutput(ctx, action) {
+	switch (actionResult(action)) {
+		case "collection": return collectionOutput(ctx, [action.outputType]);
+		case "resource": return resourceOutput(ctx, action.outputType);
+		case "meta": return metaOutput(ctx);
+		case "loose": return LOOSE_OUTPUT;
+		default: return;
+	}
+}
+/** Build every tool the document and descriptor describe. Throws on a naming problem. */
+function buildCatalogue(doc, descriptor, defaultPageSize, includeDepth = null) {
+	const entries = [];
+	const skipped = [];
+	const schemas = resourceSchemas(doc);
+	for (const [path, item] of Object.entries(doc.paths ?? {})) for (const method of HTTP_METHODS) {
+		const operation = item[method];
+		const operationId = operation?.operationId;
+		if (operation === void 0 || typeof operationId !== "string") continue;
+		const parsed = parseOperationId(operationId);
+		if (parsed === void 0) continue;
+		const resource = descriptor[parsed.type];
+		if (resource === void 0) {
+			skipped.push({
+				operationId,
+				reason: `the descriptor has no type "${parsed.type}"`
+			});
+			continue;
+		}
+		const built = buildEntry({
+			operationId,
+			toolName: toolName(parsed, descriptor),
+			kind: parsed.kind,
+			type: parsed.type,
+			method: method.toUpperCase(),
+			path,
+			resource,
+			operation,
+			security: operation.security ?? doc.security ?? []
+		}, parsed, {
+			doc,
+			descriptor,
+			params: operationParameters(doc, item, operation),
+			operation,
+			defaultPageSize,
+			includeDepth
+		}, {
+			doc,
+			descriptor,
+			schemas,
+			operation,
+			includes: capIncludePaths(includePaths(doc, operation), includeDepth)
+		}, descriptor);
+		if (typeof built === "string") {
+			skipped.push({
+				operationId,
+				reason: built
+			});
+			continue;
+		}
+		entries.push(built);
+	}
+	checkToolNames(entries.map((e) => ({
+		name: e.tool.name,
+		operationId: e.op.operationId
+	})));
+	entries.sort((a, b) => a.tool.name.localeCompare(b.tool.name));
+	return {
+		entries,
+		skipped
+	};
+}
+function buildEntry(op, parsed, inputCtx, outputCtx, descriptor) {
+	let input;
+	let output;
+	let result;
+	let key;
+	switch (parsed.kind) {
+		case "list":
+			input = collectionInput(inputCtx, op.resource.paginator, void 0, op.resource.countable);
+			output = collectionOutput(outputCtx, [op.type]);
+			result = "collection";
+			break;
+		case "get":
+			input = singleInput(inputCtx, `The id of the \`${op.type}\` resource to get.`);
+			output = itemOutput(outputCtx, [op.type], false);
+			result = "item";
+			break;
+		case "create":
+			input = createInput(inputCtx, op.type);
+			output = resourceOutput(outputCtx, op.type);
+			result = "resource";
+			break;
+		case "update":
+			input = updateInput(inputCtx, op.type);
+			output = resourceOutput(outputCtx, op.type);
+			result = "resource";
+			break;
+		case "delete":
+			input = deleteInput(op.type);
+			result = "deleted";
+			break;
+		case "related": {
+			const relation = op.resource.relations[parsed.relation];
+			if (relation === void 0) return `the descriptor has no relation "${parsed.relation}" on "${op.type}"`;
+			op.relation = parsed.relation;
+			op.relationDescriptor = relation;
+			if (relation.cardinality === "many") {
+				input = collectionInput(inputCtx, relation.paginator ?? descriptor[relation.types[0] ?? ""]?.paginator, {
+					type: op.type,
+					relation: parsed.relation
+				}, relation.countable);
+				output = collectionOutput(outputCtx, relation.types);
+				result = "collection";
+			} else {
+				input = singleInput(inputCtx, `The id of the \`${op.type}\` resource whose ${parsed.relation} to get.`);
+				output = itemOutput(outputCtx, relation.types, true);
+				result = "item";
+			}
+			break;
+		}
+		case "action": {
+			const found = findAction(op);
+			if (found === void 0) return `the descriptor has no ${op.method} action at "${op.path}" on "${op.type}"`;
+			const [actionKey, action] = found;
+			op.action = parsed.action;
+			op.actionDescriptor = action;
+			key = actionKey;
+			input = actionInput(inputCtx, op.type, parsed.action, action);
+			if (input === void 0) return "every request media type it accepts is one a model cannot send, such as a binary upload";
+			output = actionOutput(outputCtx, action);
+			result = actionResult(action);
+			break;
+		}
+	}
+	const scopes = descriptorScopes(op);
+	if (scopes !== void 0) op.scopes = scopes;
+	const tool = {
+		name: op.toolName,
+		inputSchema: input.schema
+	};
+	const operation = op.operation;
+	if (typeof operation.summary === "string") tool.title = operation.summary;
+	const description = operation.description ?? operation.summary;
+	if (typeof description === "string") tool.description = description;
+	if (output !== void 0) tool.outputSchema = output;
+	const hints = annotations(op);
+	if (hints !== void 0) tool.annotations = hints;
+	tool._meta = { operationId: op.operationId };
+	return key === void 0 ? {
+		op,
+		tool,
+		input,
+		result
+	} : {
+		op,
+		tool,
+		input,
+		result,
+		actionKey: key
+	};
+}
+/**
+* Throw unless the document's `info.x-generator.contract` is in the range this package reads. A
+* document outside it would yield tools that miss or misread what the server offers, so there is
+* no warning mode.
+*/
+function assertContract(doc) {
+	const contract = doc.info?.["x-generator"]?.contract;
+	if (typeof contract !== "number") throw new Error(`The OpenAPI document declares no generator contract (info.x-generator.contract). @haddowg/json-api-mcp reads contracts 13 to 18; regenerate the document from a newer haddowg/json-api server.`);
+	if (contract < 13) throw new Error(`The OpenAPI document declares generator contract ${contract}, older than this package reads (13 to 18). Regenerate it from a newer haddowg/json-api server.`);
+	if (contract > 18) throw new Error(`The OpenAPI document declares generator contract ${contract}, newer than this package reads (13 to 18). Upgrade @haddowg/json-api-mcp.`);
+	return contract;
+}
+//#endregion
+//#region src/model.ts
+/** The package that writes the artefact. */
+const MODEL_GENERATOR = "@haddowg/json-api-mcp";
+//#endregion
+//#region src/build.ts
+const OMITTED = /* @__PURE__ */ new Set([
+	"parameters",
+	"requestBody",
+	"responses",
+	"callbacks",
+	"security"
+]);
+function lightOperation(operation) {
+	const out = {};
+	for (const [key, value] of Object.entries(operation)) if (!OMITTED.has(key)) out[key] = value;
+	return out;
+}
+/** The names of the document's `oauth2` security schemes, the ones an MCP caller presents. */
+function oauthSchemes(document) {
+	const schemes = document.components?.["securitySchemes"];
+	if (!isObject(schemes)) return [];
+	return Object.keys(schemes).filter((name) => {
+		const scheme = deref(document, schemes[name]);
+		return isObject(scheme) && scheme["type"] === "oauth2";
+	});
+}
+/**
+* Build the model from a document and its descriptor. Throws when the document's generator
+* contract is out of range or a tool name breaks the rules. Needs no codegen: pass the
+* descriptor a generated client exports, or use `generateMcpModel` to build it too.
+*/
+function buildMcpModel(document, descriptor, options) {
+	const contract = assertContract(document);
+	const includeDepth = options.includeDepth === void 0 ? 1 : options.includeDepth;
+	if (includeDepth !== null && !(Number.isInteger(includeDepth) && includeDepth >= 0)) throw new Error(`includeDepth must be a whole number of 0 or more, or null; got ${includeDepth}`);
+	const catalogue = buildCatalogue(document, descriptor, options.defaultPageSize ?? 10, includeDepth);
+	const info = document.info;
+	const model = {
+		format: 3,
+		generator: MODEL_GENERATOR,
+		contract,
+		source: {
+			title: `${String(info?.title ?? "unknown")} ${String(info?.version ?? "unknown")}`,
+			hash: options.hash
+		},
+		credentialSchemes: oauthSchemes(document),
+		includeDepth,
+		descriptor,
+		tools: catalogue.entries.map((entry) => {
+			const { op } = entry;
+			const operation = {
+				operationId: op.operationId,
+				toolName: op.toolName,
+				kind: op.kind,
+				type: op.type,
+				method: op.method,
+				path: op.path,
+				operation: lightOperation(op.operation)
+			};
+			if (op.operation.security !== void 0) operation.security = op.operation.security;
+			if (op.relation !== void 0) operation.relation = op.relation;
+			if (op.action !== void 0) operation.action = op.action;
+			if (entry.actionKey !== void 0) operation.actionKey = entry.actionKey;
+			const { schema: _schema, ...plan } = entry.input;
+			return {
+				operation,
+				tool: entry.tool,
+				plan,
+				result: entry.result
+			};
+		}),
+		skipped: catalogue.skipped
+	};
+	if (document.security !== void 0) model.security = document.security;
+	const server = document.servers?.[0]?.url;
+	if (server !== void 0) model.baseUrl = server;
+	return model;
+}
+//#endregion
+//#region src/generate.ts
+/**
+* @haddowg/json-api-mcp/generate: the build-time half. It reads an OpenAPI document, builds the
+* descriptor with `@haddowg/json-api-codegen` and writes the model the runtime serves. Run it
+* against the committed spec and commit its output, as with the generated client. The runtime
+* entry point never loads this module or the codegen.
+*/
+async function codegen() {
+	try {
+		return await import("@haddowg/json-api-codegen");
+	} catch (error) {
+		throw new Error("Generating an MCP model needs @haddowg/json-api-codegen; add it to your dev dependencies.", { cause: error });
+	}
+}
+/** Build the model from a parsed document, building its descriptor with the codegen. */
+async function generateMcpModel(document, options = {}) {
+	const { buildDescriptor, hashJson } = await codegen();
+	return buildMcpModel(document, buildDescriptor(document), {
+		...options,
+		hash: hashJson(document)
+	});
+}
+/** The model as the generator writes it: two-space JSON with a trailing newline. */
+function serialiseMcpModel(model) {
+	return `${JSON.stringify(model, null, 2)}\n`;
+}
+/**
+* Read the document, build the model and write it, or with `check` compare it with the committed
+* file. The comparison is of the parsed JSON, so a formatter rewriting the file's whitespace
+* doesn't count as a change.
+*/
+async function writeMcpModel(options) {
+	const { readDocument } = await codegen();
+	const document = await readDocument(options.input);
+	const generateOptions = {};
+	if (options.defaultPageSize !== void 0) generateOptions.defaultPageSize = options.defaultPageSize;
+	if (options.includeDepth !== void 0) generateOptions.includeDepth = options.includeDepth;
+	const content = serialiseMcpModel(await generateMcpModel(document, generateOptions));
+	if (options.check === true) {
+		let committed;
+		try {
+			committed = JSON.parse(await readFile(options.output, "utf8"));
+		} catch {
+			return {
+				path: options.output,
+				upToDate: false
+			};
+		}
+		return {
+			path: options.output,
+			upToDate: JSON.stringify(committed) === JSON.stringify(JSON.parse(content))
+		};
+	}
+	await mkdir(dirname(options.output), { recursive: true });
+	await writeFile(options.output, content, "utf8");
+	return {
+		path: options.output,
+		upToDate: true
+	};
+}
+//#endregion
+export { buildMcpModel as i, serialiseMcpModel as n, writeMcpModel as r, generateMcpModel as t };
+
+//# sourceMappingURL=generate-CiLuqQJ0.mjs.map