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

package/dist/index.mjs

@@ -0,0 +1,788 @@
+import { JsonApiError, createClient, execute, fetchTransport, isActionLocation, isPolymorphic, materialise } from "@haddowg/json-api-client";
+//#region src/contract.ts
+/** The oldest generator contract this package reads: the baseline current servers stamp. */
+const MINIMUM_CONTRACT = 13;
+/** The newest generator contract this package reads. */
+const MAXIMUM_CONTRACT = 18;
+/**
+* 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/openapi.ts
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"patch",
+	"put",
+	"delete"
+];
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+//#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"
+]);
+/** Thrown when a model's argument can't be decoded, such as JSON text that doesn't parse. */
+var ArgumentError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ArgumentError";
+	}
+};
+/** Turn a model's argument back into the value the API expects. */
+function decode(value, decoder, path = "value") {
+	if (value === null || value === void 0) return value;
+	switch (decoder.kind) {
+		case "json":
+			if (typeof value !== "string") return value;
+			try {
+				return JSON.parse(value);
+			} catch {
+				throw new ArgumentError(`${path} must be JSON text`);
+			}
+		case "array": return Array.isArray(value) ? value.map((item, index) => decode(item, decoder.items, `${path}[${index}]`)) : value;
+		case "object": {
+			if (!isObject(value)) return value;
+			const out = {};
+			for (const [key, member] of Object.entries(value)) {
+				const prop = decoder.props[key];
+				if (prop === void 0) out[key] = member;
+				else if (!(member === null && prop.nullMeansOmit)) out[key] = decode(member, prop.decoder, `${path}.${key}`);
+			}
+			return out;
+		}
+		default: return value;
+	}
+}
+//#endregion
+//#region src/inputs.ts
+/** The Countable profile's token for counting the collection itself. */
+const SELF_COUNT = "_self_";
+//#endregion
+//#region src/flatten.ts
+/**
+* Flatten the client's materialised results into plain tool output. A resource becomes
+* `{ id, type, ...attributes, relation }`, where a relation is an id (ids for a to-many, or type
+* and id for a polymorphic relation), or the flattened related resource when it was included.
+* Links and meta on resources are dropped; a collection keeps only its pagination links.
+*/
+/** A materialised related value carries `$raw` when it was included, not when it's only linkage. */
+const isIncluded = (value) => "$raw" in value;
+function identifier(value, polymorphic) {
+	return polymorphic ? {
+		type: value["type"],
+		id: value["id"]
+	} : value["id"];
+}
+/**
+* Flatten one materialised resource. A resource already on the path, or one more than
+* `maxDepth` relationships from the root, is cut back to its id.
+*/
+function flattenResource(value, descriptor, path = [], maxDepth = null) {
+	const type = String(value["type"]);
+	const key = `${type}:${String(value["id"])}`;
+	const relations = descriptor[type]?.relations ?? {};
+	const out = {
+		id: value["id"],
+		type
+	};
+	for (const [name, member] of Object.entries(value)) {
+		if (name === "id" || name === "type") continue;
+		const relation = relations[name];
+		if (relation === void 0) {
+			out[name] = member;
+			continue;
+		}
+		const polymorphic = isPolymorphic(relation);
+		const one = (item) => {
+			if (!isObject(item)) return item;
+			const itemKey = `${String(item["type"])}:${String(item["id"])}`;
+			return isIncluded(item) && itemKey !== key && !path.includes(itemKey) && (maxDepth === null || path.length < maxDepth) ? flattenResource(item, descriptor, [...path, key], maxDepth) : identifier(item, polymorphic);
+		};
+		out[name] = Array.isArray(member) ? member.map(one) : one(member);
+	}
+	return out;
+}
+const PAGE_LINKS = [
+	"first",
+	"prev",
+	"next",
+	"last"
+];
+function linkHref(link) {
+	if (typeof link === "string") return link;
+	if (isObject(link) && typeof link["href"] === "string") return link["href"];
+}
+/** Flatten a materialised collection into `{ items, links, meta? }`. */
+function flattenCollection(value, descriptor, maxDepth = null) {
+	const links = {};
+	for (const name of PAGE_LINKS) {
+		const href = linkHref(value.$links?.[name]);
+		if (href !== void 0) links[name] = href;
+	}
+	const out = {
+		items: value.map((item) => isObject(item) ? flattenResource(item, descriptor, [], maxDepth) : item),
+		links
+	};
+	if (value.$meta !== void 0) out["meta"] = value.$meta;
+	return out;
+}
+//#endregion
+//#region src/call.ts
+/** Thrown when a `pageLink` isn't a link this tool may follow. */
+var PageLinkError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PageLinkError";
+	}
+};
+const text = (value) => ({
+	type: "text",
+	text: value
+});
+function structured(value) {
+	return {
+		content: [text(JSON.stringify(value))],
+		structuredContent: value
+	};
+}
+function requireId(args) {
+	const id = args["id"];
+	if (typeof id === "string" && id !== "") return id;
+	if (typeof id === "number") return String(id);
+	throw new ArgumentError("id is required");
+}
+function stringList(value, name) {
+	if (value === null || value === void 0) return;
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new ArgumentError(`${name} must be a list of strings`);
+	return value;
+}
+/** The read query a model's arguments describe. */
+function readQuery(args, plan) {
+	const query = {};
+	if (plan.filter !== void 0 && isObject(args["filter"])) {
+		const filter = decode(args["filter"], plan.filter, "filter");
+		for (const [key, value] of Object.entries(filter)) if (isObject(value)) {
+			const bounds = Object.fromEntries(Object.entries(value).filter(([, v]) => v !== null));
+			if (Object.keys(bounds).length === 0) delete filter[key];
+			else filter[key] = bounds;
+		}
+		if (Object.keys(filter).length > 0) query.filter = filter;
+	}
+	const sort = plan.sort ? stringList(args["sort"], "sort") : void 0;
+	if (sort !== void 0 && sort.length > 0) query.sort = sort;
+	const include = plan.include ? stringList(args["include"], "include") : void 0;
+	if (plan.includePaths !== void 0) {
+		const allowed = plan.includePaths;
+		const refused = (include ?? []).filter((path) => !allowed.includes(path));
+		if (refused.length > 0) throw new ArgumentError(`include can't name ${refused.map((p) => `"${p}"`).join(", ")}; this tool includes only ${allowed.join(", ")}`);
+	}
+	if (include !== void 0 && include.length > 0) query.include = include;
+	if (plan.fields.length > 0 && isObject(args["fields"])) {
+		const fields = {};
+		for (const [type, names] of Object.entries(args["fields"])) {
+			const list = stringList(names, `fields.${type}`);
+			if (list !== void 0) fields[type] = list;
+		}
+		if (Object.keys(fields).length > 0) query.fields = fields;
+	}
+	if (plan.countProfile !== void 0 && args["withCount"] === true) query.withCount = [SELF_COUNT];
+	if (plan.sizeKey !== void 0) {
+		const asked = args["pageSize"];
+		let size = typeof asked === "number" && Number.isFinite(asked) ? Math.trunc(asked) : plan.defaultPageSize;
+		size = Math.max(1, plan.maxPageSize === void 0 ? size : Math.min(size, plan.maxPageSize));
+		query.page = { [plan.sizeKey]: size };
+	}
+	return query;
+}
+/** The flat write input a model's arguments describe: relations as identifiers, nulls resolved. */
+function writeInput(args, plan) {
+	const input = {};
+	for (const [name, field] of Object.entries(plan.fields)) {
+		const value = args[name];
+		if (value === void 0 || value === null && field.property.nullMeansOmit) continue;
+		if (value === null) {
+			input[name] = null;
+			continue;
+		}
+		const relation = field.relation;
+		if (relation === void 0) {
+			input[name] = decode(value, field.property.decoder, name);
+			continue;
+		}
+		const identify = (item) => {
+			if (isPolymorphic(relation)) {
+				if (!isObject(item) || typeof item["type"] !== "string" || typeof item["id"] !== "string") throw new ArgumentError(`${name} takes the related resource's type and id`);
+				return {
+					type: item["type"],
+					id: item["id"]
+				};
+			}
+			if (typeof item !== "string" && typeof item !== "number") throw new ArgumentError(`${name} takes the related resource's id`);
+			return {
+				type: relation.types[0],
+				id: String(item)
+			};
+		};
+		if (relation.cardinality === "many") {
+			if (!Array.isArray(value)) throw new ArgumentError(`${name} takes a list`);
+			input[name] = value.map(identify);
+		} else input[name] = identify(value);
+	}
+	for (const name of stringList(args["clear"], "clear") ?? []) {
+		if (!plan.clearable.includes(name)) throw new ArgumentError(`clear can't name "${name}"`);
+		input[name] = null;
+	}
+	if (plan.clientId !== "none" && args["id"] !== null && args["id"] !== void 0) input["id"] = String(args["id"]);
+	return input;
+}
+/** Escape a string for a regular expression. */
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+* Check a `pageLink` against the tool's own endpoint: the base URL's origin and the endpoint's
+* path, with any id in it. Returns the absolute URL to fetch.
+*/
+function checkPageLink(link, baseUrl, template) {
+	if (typeof link !== "string" || link === "") throw new PageLinkError("pageLink must be a link string");
+	let base;
+	try {
+		base = new URL(baseUrl);
+	} catch {
+		throw new PageLinkError("pageLink needs an absolute base URL to be checked against");
+	}
+	let url;
+	try {
+		url = new URL(link, base);
+	} catch {
+		throw new PageLinkError("pageLink is not a valid URL");
+	}
+	const prefix = base.pathname.replace(/\/$/, "");
+	const pattern = template.split(/(\{[^}]+\})/).map((part) => /^\{[^}]+\}$/.test(part) ? "[^/]+" : escape(part)).join("");
+	if (url.protocol !== "http:" && url.protocol !== "https:" || url.origin !== base.origin || !new RegExp(`^${escape(prefix)}${pattern}$`).test(url.pathname)) throw new PageLinkError("pageLink must be one of the links this tool returned; it points somewhere else");
+	return url.href;
+}
+/** The descriptor entry a call sends this action with: the operation's method and the body plan picked. */
+function effectiveAction(entry) {
+	const { inputMedia: _inputMedia, inputType, contentType: _contentType, ...action } = entry.op.actionDescriptor;
+	const plan = entry.input.action;
+	const base = {
+		...action,
+		method: entry.op.method
+	};
+	switch (plan.kind) {
+		case "none": return {
+			...base,
+			input: "none"
+		};
+		case "flat": return inputType === void 0 ? {
+			...base,
+			input: "document"
+		} : {
+			...base,
+			input: "document",
+			inputType
+		};
+		case "body": return plan.mediaKind === "document" ? {
+			...base,
+			input: "document"
+		} : {
+			...base,
+			input: "raw",
+			contentType: plan.mediaType
+		};
+	}
+}
+function withAction(descriptor, entry) {
+	const resource = descriptor[entry.op.type];
+	return {
+		...descriptor,
+		[entry.op.type]: {
+			...resource,
+			actions: {
+				...resource.actions,
+				[entry.actionKey]: effectiveAction(entry)
+			}
+		}
+	};
+}
+async function binaryContent(value, uri, mimeType) {
+	const bytes = value instanceof ArrayBuffer ? value : await value.arrayBuffer();
+	const data = Buffer.from(bytes).toString("base64");
+	return mimeType.startsWith("image/") ? {
+		type: "image",
+		data,
+		mimeType
+	} : {
+		type: "resource",
+		resource: {
+			uri,
+			mimeType,
+			blob: data
+		}
+	};
+}
+/** Run one tool call against the API. Throws what the call failed with. */
+async function runCall(entry, rawArgs, env) {
+	if (rawArgs !== void 0 && rawArgs !== null && !isObject(rawArgs)) throw new ArgumentError("the arguments must be an object");
+	const args = rawArgs ?? {};
+	if (env.baseUrl === void 0) throw new Error("No base URL: pass baseUrl, return one from requestInit, or give the document a server");
+	const { op } = entry;
+	const descriptor = op.kind === "action" ? withAction(env.descriptor, entry) : env.descriptor;
+	const headers = env.headers;
+	const accessor = createClient(descriptor, {
+		baseUrl: env.baseUrl,
+		...env.transport !== void 0 ? { transport: env.transport } : {},
+		...headers !== void 0 ? { headers: () => headers } : {}
+	})[op.type];
+	const query = entry.input.query === void 0 ? void 0 : readQuery(args, entry.input.query);
+	if (query !== void 0 && env.signal !== void 0) query.signal = env.signal;
+	switch (op.kind) {
+		case "list":
+		case "related": {
+			if (entry.result === "item") {
+				const related = await accessor.id(requireId(args)).rel(op.relation).related(query);
+				return structured({ item: isObject(related) ? flattenResource(related, env.descriptor, [], env.includeDepth) : null });
+			}
+			let collection;
+			if (args["pageLink"] !== void 0 && args["pageLink"] !== null && entry.input.query?.paginated) {
+				const url = checkPageLink(args["pageLink"], env.baseUrl, op.path);
+				const doc = await execute({
+					baseUrl: env.baseUrl,
+					transport: env.transport ?? fetchTransport,
+					...headers !== void 0 ? { headers: () => headers } : {}
+				}, {
+					method: "GET",
+					path: url,
+					link: true,
+					...entry.input.query?.countProfile !== void 0 && new URL(url).searchParams.has("withCount") ? { profiles: [entry.input.query.countProfile] } : {},
+					...env.signal !== void 0 ? { signal: env.signal } : {}
+				});
+				collection = doc === void 0 ? [] : materialise(doc, {
+					descriptor: env.descriptor,
+					navigate: () => Promise.reject(/* @__PURE__ */ new Error("not navigable"))
+				});
+			} else if (op.kind === "list") collection = await accessor.list(query);
+			else collection = await accessor.id(requireId(args)).rel(op.relation).related(query);
+			return structured(flattenCollection(Array.isArray(collection) ? collection : [], env.descriptor, env.includeDepth));
+		}
+		case "get": {
+			const resource = await accessor.get(requireId(args), query);
+			return structured({ item: isObject(resource) ? flattenResource(resource, env.descriptor, [], env.includeDepth) : null });
+		}
+		case "create": {
+			const input = writeInput(args, entry.input.write);
+			const created = await accessor.create(input);
+			return structured(isObject(created) ? flattenResource(created, env.descriptor, [], env.includeDepth) : {
+				id: String(input["id"] ?? ""),
+				type: op.type
+			});
+		}
+		case "update": {
+			const id = requireId(args);
+			const updated = await accessor.id(id).update(writeInput(args, entry.input.write));
+			return structured(isObject(updated) ? flattenResource(updated, env.descriptor, [], env.includeDepth) : {
+				id,
+				type: op.type
+			});
+		}
+		case "delete": {
+			const id = requireId(args);
+			await accessor.id(id).delete();
+			return { content: [text(`Deleted ${op.type} ${id}.`)] };
+		}
+		case "action": return runAction(entry, args, accessor, env);
+	}
+}
+async function runAction(entry, args, accessor, env) {
+	const { op } = entry;
+	const action = op.actionDescriptor;
+	const call = (action.scope === "resource" ? accessor.id(requireId(args)).actions : accessor.actions)[entry.actionKey];
+	const options = env.signal === void 0 ? {} : { signal: env.signal };
+	const plan = entry.input.action;
+	let result;
+	if (plan.kind === "none") result = await call(options);
+	else {
+		const body = plan.kind === "flat" ? writeInput(args, plan.write) : args["body"] === null ? void 0 : decode(args["body"], plan.decoder, "body");
+		if (plan.kind === "body" && plan.required && body === void 0) throw new ArgumentError("body is required");
+		result = await call(body, options);
+	}
+	if (action.location !== void 0 && isActionLocation(result)) return structured({ ...result });
+	switch (entry.result) {
+		case "collection": return structured(flattenCollection(Array.isArray(result) ? result : [], env.descriptor, env.includeDepth));
+		case "resource":
+		case "loose":
+			if (Array.isArray(result)) return structured(flattenCollection(result, env.descriptor, env.includeDepth));
+			return isObject(result) ? structured(flattenResource(result, env.descriptor, [], env.includeDepth)) : { content: [text("The action returned no resource.")] };
+		case "meta": return structured(isObject(result) ? result : {});
+		case "raw": {
+			const mimeType = action.rawOutput?.[0]?.mediaType ?? "application/octet-stream";
+			if (result === void 0) return { content: [text("Done.")] };
+			if (typeof result === "string") return { content: [text(result)] };
+			if (result instanceof ArrayBuffer || typeof Blob !== "undefined" && result instanceof Blob) return { content: [await binaryContent(result, `${env.baseUrl}${action.path}`, mimeType)] };
+			return { content: [text(JSON.stringify(result))] };
+		}
+		default: return { content: [text("Done.")] };
+	}
+}
+/** The error a failed call carries, before the host's `mapError`. */
+function toToolError(error) {
+	if (error instanceof JsonApiError) return {
+		status: error.status,
+		message: error.message,
+		errors: error.errors.map((e) => {
+			const out = {};
+			if (e.status !== void 0) out.status = e.status;
+			if (e.code !== void 0) out.code = e.code;
+			if (e.title !== void 0) out.title = e.title;
+			if (e.detail !== void 0) out.detail = e.detail;
+			if (e.source !== void 0) out.source = e.source;
+			if (e.path !== void 0) out.path = e.path;
+			return out;
+		}),
+		cause: error
+	};
+	return {
+		message: error instanceof Error ? error.message : String(error),
+		errors: [],
+		cause: error
+	};
+}
+/** A tool error result: the message, the status and each error object, as JSON text. */
+function errorResult(error) {
+	const body = { error: error.message };
+	if (error.status !== void 0) body["status"] = error.status;
+	if (error.errors.length > 0) body["errors"] = error.errors;
+	return {
+		content: [text(JSON.stringify(body))],
+		isError: true
+	};
+}
+//#endregion
+//#region src/model.ts
+/** The artefact's own format. A runtime refuses a format it doesn't know. */
+const MODEL_FORMAT = 3;
+/**
+* Every format this runtime reads. Format 1 has no `credentialSchemes`. Formats 1 and 2 have no
+* `includeDepth`, and store each operation's `scopes` and the `security` of its operation object.
+*/
+const READABLE_FORMATS = [
+	1,
+	2,
+	3
+];
+/** The package that writes the artefact. */
+const MODEL_GENERATOR = "@haddowg/json-api-mcp";
+/** Thrown when an artefact can't be read: another format, or a contract out of range. */
+var McpModelError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "McpModelError";
+	}
+};
+/** Check a parsed artefact before the runtime trusts it. */
+function assertModel(value) {
+	if (!isObject(value) || value["generator"] !== "@haddowg/json-api-mcp") throw new McpModelError(`This isn't a model written by ${MODEL_GENERATOR}. Generate one with the json-api-mcp CLI.`);
+	if (typeof value["format"] !== "number" || !READABLE_FORMATS.includes(value["format"])) throw new McpModelError(`The model is format ${String(value["format"])} and this runtime reads formats ${READABLE_FORMATS.slice(0, -1).join(", ")} and 3. Regenerate it with the same version of ${MODEL_GENERATOR} the server runs.`);
+	const contract = value["contract"];
+	if (typeof contract !== "number" || contract < 13 || contract > 18) throw new McpModelError(`The model was built from a document with generator contract ${String(contract)}, and this runtime reads contracts 13 to 18.`);
+	if (!isObject(value["descriptor"]) || !Array.isArray(value["tools"])) throw new McpModelError("The model has no descriptor or tools; regenerate it.");
+	const credentialSchemes = value["credentialSchemes"];
+	if (value["format"] !== 1 && (!Array.isArray(credentialSchemes) || !credentialSchemes.every((s) => typeof s === "string"))) throw new McpModelError("The model has no credentialSchemes list; regenerate it.");
+	const includeDepth = value["includeDepth"];
+	if (value["format"] === 3 && includeDepth !== null && !(typeof includeDepth === "number" && Number.isInteger(includeDepth) && includeDepth >= 0)) throw new McpModelError("The model has no includeDepth; regenerate it.");
+	return value;
+}
+/**
+* The schemes a format 1 model's caller is taken to authenticate with, since it doesn't record
+* them: every scheme some operation lists scopes under.
+*/
+function inferCredentialSchemes(model) {
+	const schemes = /* @__PURE__ */ new Set();
+	for (const tool of model.tools) for (const requirement of tool.operation.security ?? []) for (const [scheme, scopes] of Object.entries(requirement)) if (scopes.length > 0) schemes.add(scheme);
+	return [...schemes];
+}
+//#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/mcp.ts
+/** Every required scope appears among the granted ones. */
+const exactScopeMatcher = (granted, required) => required.every((scope) => granted.includes(scope));
+/**
+* Whether granted scopes satisfy an operation's security. No requirement, or an empty one, needs
+* nothing. Given `credentialSchemes`, the schemes the caller authenticates with, a requirement
+* counts only when it names nothing else, so an operation whose every requirement needs another
+* credential fails. A counted requirement passes when its scopes, across its schemes, all match,
+* or when it lists none. Without `credentialSchemes` every requirement counts.
+*/
+function satisfiesSecurity(security, granted, matcher = exactScopeMatcher, credentialSchemes) {
+	if (security.length === 0) return true;
+	return security.some((requirement) => {
+		const schemes = Object.keys(requirement);
+		if (schemes.length === 0) return true;
+		if (credentialSchemes !== void 0 && !schemes.every((scheme) => credentialSchemes.includes(scheme))) return false;
+		const scopes = Object.values(requirement).flat();
+		return scopes.length === 0 || matcher(granted, scopes);
+	});
+}
+/**
+* The schemes the scope filter counts: the host's, else the model's, else for a format 1 model
+* the schemes it lists scopes under. `undefined`, so every requirement counts, when that's empty.
+*/
+function resolveCredentialSchemes(model, override) {
+	if (override !== void 0) return override;
+	const schemes = model.credentialSchemes ?? inferCredentialSchemes(model);
+	return schemes.length > 0 ? schemes : void 0;
+}
+/** Rebuild an operation for the hooks, adding back the descriptor entries it names. */
+function hydrate(model, tool) {
+	const source = tool.operation;
+	const resource = model.descriptor[source.type];
+	if (resource === void 0) throw new McpModelError(`The model's descriptor has no type "${source.type}"; regenerate it.`);
+	const security = source.security ?? model.security ?? [];
+	const operation = model.format < 3 || source.security === void 0 ? source.operation : {
+		...source.operation,
+		security: source.security
+	};
+	const op = {
+		operationId: source.operationId,
+		toolName: source.toolName,
+		kind: source.kind,
+		type: source.type,
+		method: source.method,
+		path: source.path,
+		resource,
+		operation,
+		security
+	};
+	if (source.relation !== void 0) {
+		op.relation = source.relation;
+		const relation = resource.relations[source.relation];
+		if (relation !== void 0) op.relationDescriptor = relation;
+	}
+	if (source.action !== void 0) {
+		op.action = source.action;
+		const action = resource.actions?.[source.actionKey ?? source.action];
+		if (action !== void 0) op.actionDescriptor = action;
+	}
+	const scopes = source.scopes ?? descriptorScopes(op);
+	if (scopes !== void 0) op.scopes = scopes;
+	const entry = {
+		op,
+		tool: tool.tool,
+		input: tool.plan,
+		result: tool.result
+	};
+	if (source.actionKey !== void 0) entry.actionKey = source.actionKey;
+	return entry;
+}
+/**
+* Serve MCP tools from a model the generator wrote: `createJsonApiMcp({ model })` with the parsed
+* artefact. Throws when the artefact isn't one this runtime can read.
+*/
+function createJsonApiMcp(options) {
+	const { hooks = {} } = options;
+	const model = assertModel(options.model);
+	const descriptor = model.descriptor;
+	const catalogue = { entries: model.tools.map((tool) => hydrate(model, tool)) };
+	const defaultBaseUrl = options.baseUrl ?? model.baseUrl;
+	const credentialSchemes = resolveCredentialSchemes(model, options.credentialSchemes);
+	const includeDepth = model.includeDepth ?? null;
+	async function forRequest(request) {
+		const ctx = request.context;
+		let entries = catalogue.entries;
+		if (request.grantedScopes !== void 0) {
+			const granted = request.grantedScopes ?? [];
+			entries = entries.filter((e) => satisfiesSecurity(e.op.security, granted, hooks.scopeMatcher, credentialSchemes));
+		}
+		if (hooks.capabilities !== void 0) {
+			const capabilities = await hooks.capabilities(ctx);
+			const lookup = (id) => capabilities instanceof Map ? capabilities.get(id) : capabilities[id];
+			entries = entries.filter((e) => lookup(e.op.operationId) !== "denied");
+		}
+		if (hooks.includeOperation !== void 0) {
+			const include = hooks.includeOperation;
+			const keep = await Promise.all(entries.map((e) => include(e.op, ctx)));
+			entries = entries.filter((_, index) => keep[index] === true);
+		}
+		const byName = /* @__PURE__ */ new Map();
+		const tools = [];
+		for (const entry of entries) {
+			const tool = hooks.decorateTool === void 0 ? entry.tool : await hooks.decorateTool(structuredClone(entry.tool), entry.op, ctx);
+			tools.push(tool);
+			byName.set(tool.name, entry);
+		}
+		async function callTool(name, args, callOptions = {}) {
+			const entry = byName.get(name);
+			if (entry === void 0) return errorResult({
+				message: `Unknown tool "${name}"`,
+				errors: [],
+				cause: void 0
+			});
+			try {
+				const init = hooks.requestInit === void 0 ? {} : await hooks.requestInit(entry.op, ctx);
+				return await runCall(entry, args, {
+					descriptor,
+					baseUrl: init.baseUrl ?? defaultBaseUrl,
+					transport: options.transport,
+					headers: init.headers,
+					signal: callOptions.signal,
+					includeDepth
+				});
+			} catch (error) {
+				const toolError = toToolError(error);
+				return errorResult(hooks.mapError === void 0 ? toolError : await hooks.mapError(toolError, entry.op, ctx));
+			}
+		}
+		return {
+			tools,
+			callTool
+		};
+	}
+	return {
+		operations: catalogue.entries.map((e) => e.op),
+		tools: catalogue.entries.map((e) => e.tool),
+		skipped: model.skipped,
+		contract: model.contract,
+		source: model.source,
+		credentialSchemes,
+		forRequest
+	};
+}
+//#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;
+	}
+};
+//#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
+export { MAXIMUM_CONTRACT, MINIMUM_CONTRACT, MODEL_FORMAT, MODEL_GENERATOR, McpModelError, PORTABLE_FORMATS, SAFETY_EXTENSION, TOOL_NAME_PATTERN, ToolNameError, assertContract, assertModel, createJsonApiMcp, exactScopeMatcher, parseOperationId, readActionSafety, satisfiesSecurity, toolName };
+
+//# sourceMappingURL=index.mjs.map