@haddowg/json-api-mcp 1.2.1 → 1.4.0

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { JsonApiError, createClient, execute, fetchTransport, isActionLocation,
 /** 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;
+const MAXIMUM_CONTRACT = 19;
 /**
 * 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
@@ -11,9 +11,9 @@ const MAXIMUM_CONTRACT = 18;
 */
 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.`);
+	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 19; 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 19). Regenerate it from a newer haddowg/json-api server.`);
+	if (contract > 19) throw new Error(`The OpenAPI document declares generator contract ${contract}, newer than this package reads (13 to 19). Upgrade @haddowg/json-api-mcp.`);
 	return contract;
 }
 //#endregion
@@ -91,9 +91,11 @@ const SELF_COUNT = "_self_";
 //#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.
+* `{ id, type, ...attributes, relation, links? }`, 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, and `links` holds only the links the type names. Generic links such as `self` and
+* resource meta are dropped. Results go back in a JSON:API-like envelope of `data`, `links` and
+* `meta`, where `links` only carries a collection's pagination.
 */
 /** A materialised related value carries `$raw` when it was included, not when it's only linkage. */
 const isIncluded = (value) => "$raw" in value;
@@ -103,14 +105,36 @@ function identifier(value, polymorphic) {
 		id: value["id"]
 	} : value["id"];
 }
+/** A link as a flattened resource carries it: `{ href, type?, title?, meta? }`. */
+function flatLink(link) {
+	if (typeof link === "string") return { href: link };
+	if (!isObject(link) || typeof link["href"] !== "string") return;
+	const out = { href: link["href"] };
+	if (typeof link["type"] === "string") out["type"] = link["type"];
+	if (typeof link["title"] === "string") out["title"] = link["title"];
+	if (isObject(link["meta"])) out["meta"] = link["meta"];
+	return out;
+}
+/** The links of a resource its type names, or undefined when it carries none of them. */
+function namedLinks(value, names) {
+	const links = value.$links;
+	if (names === void 0 || !isObject(links)) return;
+	const out = {};
+	for (const name of names) {
+		const link = flatLink(links[name]);
+		if (link !== void 0) out[name] = link;
+	}
+	return Object.keys(out).length > 0 ? out : void 0;
+}
 /**
 * 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.
+* `includeDepth` relationships from the root, is cut back to its id.
 */
-function flattenResource(value, descriptor, path = [], maxDepth = null) {
+function flattenResource(value, ctx, path = []) {
 	const type = String(value["type"]);
 	const key = `${type}:${String(value["id"])}`;
-	const relations = descriptor[type]?.relations ?? {};
+	const relations = ctx.descriptor[type]?.relations ?? {};
+	const maxDepth = ctx.includeDepth;
 	const out = {
 		id: value["id"],
 		type
@@ -126,10 +150,12 @@ function flattenResource(value, descriptor, path = [], maxDepth = null) {
 		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);
+			return isIncluded(item) && itemKey !== key && !path.includes(itemKey) && (maxDepth === null || path.length < maxDepth) ? flattenResource(item, ctx, [...path, key]) : identifier(item, polymorphic);
 		};
 		out[name] = Array.isArray(member) ? member.map(one) : one(member);
 	}
+	const links = namedLinks(value, ctx.resourceLinks[type]);
+	if (links !== void 0) out["links"] = links;
 	return out;
 }
 const PAGE_LINKS = [
@@ -142,15 +168,30 @@ 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) {
+/** The document `meta` a materialised resource came with. */
+function resourceDocumentMeta(value) {
+	const document = isObject(value) ? value.$document : void 0;
+	return isObject(document?.meta) ? document.meta : void 0;
+}
+/**
+* One resource in its envelope: `{ data, meta? }`, with `data` null when there is none.
+* `fallbackMeta` is the document meta when the value can't carry it, such as a null.
+*/
+function resourceEnvelope(value, ctx, fallbackMeta) {
+	const out = { data: isObject(value) ? flattenResource(value, ctx) : null };
+	const meta = resourceDocumentMeta(value) ?? fallbackMeta;
+	if (meta !== void 0) out["meta"] = meta;
+	return out;
+}
+/** A materialised collection in its envelope: `{ data, links, meta? }`. */
+function collectionEnvelope(value, ctx) {
 	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),
+		data: value.map((item) => isObject(item) ? flattenResource(item, ctx) : item),
 		links
 	};
 	if (value.$meta !== void 0) out["meta"] = value.$meta;
@@ -175,6 +216,47 @@ function structured(value) {
 		structuredContent: value
 	};
 }
+/** The `meta` of a JSON:API response body, when it has one. */
+function responseMeta(response) {
+	if (response === void 0 || response.body === "") return;
+	try {
+		const body = JSON.parse(response.body);
+		return isObject(body) && isObject(body["meta"]) ? body["meta"] : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* A result in the shape a model before format 4 describes: `{ item }` for a single read,
+* `{ items, links, meta }` for a collection, the bare resource, meta object or URL otherwise,
+* and a delete as text.
+*/
+function legacyResult(entry, envelope, location, id) {
+	const data = envelope["data"];
+	if (location || entry.result === "resource" || entry.result === "loose") {
+		if (Array.isArray(data)) {
+			const { data: items, ...rest } = envelope;
+			return structured({
+				items,
+				...rest
+			});
+		}
+		return isObject(data) ? structured(data) : { content: [text("The action returned no resource.")] };
+	}
+	switch (entry.result) {
+		case "item": return structured({ item: data ?? null });
+		case "collection": {
+			const { data: items, ...rest } = envelope;
+			return structured({
+				items,
+				...rest
+			});
+		}
+		case "deleted": return { content: [text(`Deleted ${entry.op.type} ${String(id)}.`)] };
+		case "meta": return structured(isObject(envelope["meta"]) ? envelope["meta"] : {});
+		default: return structured(envelope);
+	}
+}
 function requireId(args) {
 	const id = args["id"];
 	if (typeof id === "string" && id !== "") return id;
@@ -355,29 +437,62 @@ 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");
+	let last;
+	const inner = env.transport ?? fetchTransport;
+	const transport = async (request) => {
+		last = await inner(request);
+		return last;
+	};
+	const outcome = await callApi(entry, args, {
+		...env,
+		baseUrl: env.baseUrl,
+		transport
+	});
+	const id = entry.op.kind === "delete" ? requireId(args) : void 0;
+	if (outcome.kind === "content") return outcome.result;
+	const location = outcome.kind === "envelope" && outcome.location === true;
+	const envelope = outcome.kind === "envelope" ? outcome.envelope : withFallbackMeta(outcome.envelope, responseMeta(last));
+	return env.legacyResults ? legacyResult(entry, envelope, location, id) : structured(envelope);
+}
+function withFallbackMeta(envelope, meta) {
+	return meta === void 0 || envelope["meta"] !== void 0 ? envelope : {
+		...envelope,
+		meta
+	};
+}
+const envelope = (value) => ({
+	kind: "envelope",
+	envelope: value
+});
+async function callApi(entry, args, env) {
 	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 } : {},
+		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;
+	const flat = {
+		descriptor: env.descriptor,
+		includeDepth: env.includeDepth,
+		resourceLinks: env.resourceLinks
+	};
 	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 });
-			}
+			if (entry.result === "item") return {
+				kind: "bare",
+				envelope: resourceEnvelope(await accessor.id(requireId(args)).rel(op.relation).related(query), flat)
+			};
 			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,
+					transport: env.transport,
 					...headers !== void 0 ? { headers: () => headers } : {}
 				}, {
 					method: "GET",
@@ -392,37 +507,44 @@ async function runCall(entry, rawArgs, env) {
 				});
 			} 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 });
+			return envelope(collectionEnvelope(Array.isArray(collection) ? collection : [], flat));
 		}
+		case "get": return {
+			kind: "bare",
+			envelope: resourceEnvelope(await accessor.get(requireId(args), query), flat)
+		};
 		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
-			});
+			return {
+				kind: "bare",
+				envelope: resourceEnvelope(isObject(created) ? created : {
+					id: String(input["id"] ?? ""),
+					type: op.type
+				}, flat)
+			};
 		}
 		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}.`)] };
+			return {
+				kind: "bare",
+				envelope: resourceEnvelope(isObject(updated) ? updated : {
+					id,
+					type: op.type
+				}, flat)
+			};
 		}
-		case "action": return runAction(entry, args, accessor, env);
+		case "delete":
+			await accessor.id(requireId(args)).delete();
+			return {
+				kind: "bare",
+				envelope: { data: null }
+			};
+		case "action": return runAction(entry, args, accessor, env, flat);
 	}
 }
-async function runAction(entry, args, accessor, env) {
+async function runAction(entry, args, accessor, env, flat) {
 	const { op } = entry;
 	const action = op.actionDescriptor;
 	const call = (action.scope === "resource" ? accessor.id(requireId(args)).actions : accessor.actions)[entry.actionKey];
@@ -435,22 +557,36 @@ async function runAction(entry, args, accessor, env) {
 		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 });
+	if (action.location !== void 0 && isActionLocation(result)) return {
+		kind: "envelope",
+		envelope: { data: { ...result } },
+		location: true
+	};
+	const content = (value) => ({
+		kind: "content",
+		result: { content: [text(value)] }
+	});
 	switch (entry.result) {
-		case "collection": return structured(flattenCollection(Array.isArray(result) ? result : [], env.descriptor, env.includeDepth));
+		case "collection": return envelope(collectionEnvelope(Array.isArray(result) ? result : [], flat));
 		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 : {});
+			if (Array.isArray(result)) return envelope(collectionEnvelope(result, flat));
+			return {
+				kind: "bare",
+				envelope: resourceEnvelope(isObject(result) ? result : null, flat)
+			};
+		case "meta": return envelope({ meta: 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))] };
+			if (result === void 0) return content("Done.");
+			if (typeof result === "string") return content(result);
+			if (result instanceof ArrayBuffer || typeof Blob !== "undefined" && result instanceof Blob) return {
+				kind: "content",
+				result: { content: [await binaryContent(result, `${env.baseUrl}${action.path}`, mimeType)] }
+			};
+			return content(JSON.stringify(result));
 		}
-		default: return { content: [text("Done.")] };
+		default: return content("Done.");
 	}
 }
 /** The error a failed call carries, before the host's `mapError`. */
@@ -489,15 +625,18 @@ function errorResult(error) {
 //#endregion
 //#region src/model.ts
 /** The artefact's own format. A runtime refuses a format it doesn't know. */
-const MODEL_FORMAT = 3;
+const MODEL_FORMAT = 4;
 /**
 * 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.
+* Formats 1 to 3 have no `resourceLinks`, and their output schemas describe the results before
+* the envelope, which the runtime still returns for them.
 */
 const READABLE_FORMATS = [
 	1,
 	2,
-	3
+	3,
+	4
 ];
 /** The package that writes the artefact. */
 const MODEL_GENERATOR = "@haddowg/json-api-mcp";
@@ -511,14 +650,16 @@ var McpModelError = class extends Error {
 /** 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.`);
+	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 4. 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 (typeof contract !== "number" || contract < 13 || contract > 19) throw new McpModelError(`The model was built from a document with generator contract ${String(contract)}, and this runtime reads contracts 13 to 19.`);
 	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.");
+	if (value["format"] >= 3 && includeDepth !== null && !(typeof includeDepth === "number" && Number.isInteger(includeDepth) && includeDepth >= 0)) throw new McpModelError("The model has no includeDepth; regenerate it.");
+	const resourceLinks = value["resourceLinks"];
+	if (value["format"] === 4 && !(isObject(resourceLinks) && Object.values(resourceLinks).every((names) => Array.isArray(names) && names.every((name) => typeof name === "string")))) throw new McpModelError("The model has no resourceLinks; regenerate it.");
 	return value;
 }
 /**
@@ -632,6 +773,8 @@ function createJsonApiMcp(options) {
 	const defaultBaseUrl = options.baseUrl ?? model.baseUrl;
 	const credentialSchemes = resolveCredentialSchemes(model, options.credentialSchemes);
 	const includeDepth = model.includeDepth ?? null;
+	const resourceLinks = model.resourceLinks ?? {};
+	const legacyResults = model.format < 4;
 	async function forRequest(request) {
 		const ctx = request.context;
 		let entries = catalogue.entries;
@@ -671,7 +814,9 @@ function createJsonApiMcp(options) {
 					transport: options.transport,
 					headers: init.headers,
 					signal: callOptions.signal,
-					includeDepth
+					includeDepth,
+					resourceLinks,
+					legacyResults
 				});
 			} catch (error) {
 				const toolError = toToolError(error);