@haddowg/json-api-mcp 1.2.1 → 1.3.0

package/README.md

@@ -45,6 +45,16 @@ session.tools // answer tools/list with these
 await session.callTool('albums_list', { sort: ['-releasedAt'], pageSize: 5 })
 ```
 
+Every result's `structuredContent` is a JSON:API-like envelope. A single resource comes back as
+`{ data }`, a collection as `{ data, links, meta }` with only the pagination links, a delete as
+`{ data: null }` and a meta-only action as `{ meta }`. A flattened resource keeps the links its
+type names, such as a presigned upload URL, under `links`.
+
+Coming from 1.2: a get returns `{ data }` where it returned `{ item }`, a create or update is
+wrapped in `{ data }` instead of coming back bare, and a collection lists its resources under
+`data` instead of `items`. Regenerate the model to get the new shapes. A model generated by 1.2
+still loads and keeps the 1.2 shapes its output schemas describe.
+
 Scope filtering counts only the security requirements a caller can meet with its credential
 schemes, the document's `oauth2` schemes unless you pass `credentialSchemes`. Scopes, feature
 gates, headers and error hints come from optional hooks: `scopeMatcher`, `capabilities`,

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { n as WriteModelOptions } from "./generate-CuWnYJUB.mjs";
+import { n as WriteModelOptions } from "./generate-D0kx-DHv.mjs";
 
 //#region src/cli.d.ts
 declare const USAGE = "Usage: json-api-mcp --input <url|file> --output <file> [--default-page-size <n>] [--include-depth <n|all>] [--check]";

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as writeMcpModel } from "./generate-CiLuqQJ0.mjs";
+import { r as writeMcpModel } from "./generate-BcqHRSxB.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{generate-CiLuqQJ0.mjs → generate-BcqHRSxB.mjs}

@@ -123,7 +123,81 @@ function includePaths(doc, op) {
 	return [];
 }
 const ref = (type) => ({ $ref: `#/$defs/${type}` });
-/** One type's flattened resource schema: id, type, attributes and relations, all optional but id and type. */
+/** Links every resource may carry, which a flattened resource leaves out. */
+const GENERIC_LINKS = /* @__PURE__ */ new Set([
+	"self",
+	"related",
+	"describedby"
+]);
+/** The members a flattened link keeps. */
+const LINK_MEMBERS = [
+	"href",
+	"type",
+	"title",
+	"meta"
+];
+/**
+* The links a resource schema names: its declared links and its action links. From generator
+* contract 18 they're the properties of the `<Type>ResourceLinks` component's own `allOf`
+* member; before, they sit beside `self` in its properties.
+*/
+function namedLinkSchemas(doc, resource) {
+	const component = deref(doc, (isObject(resource?.["properties"]) ? resource["properties"] : {})["links"]);
+	if (!isObject(component)) return [];
+	const own = isObject(component["properties"]) ? Object.entries(component["properties"]) : [];
+	const extended = (Array.isArray(component["allOf"]) ? component["allOf"] : []).filter((member) => isObject(member) && member["$ref"] === void 0).flatMap((member) => isObject(member["properties"]) ? Object.entries(member["properties"]) : []);
+	return [...own, ...extended].filter((entry) => !GENERIC_LINKS.has(entry[0]) && isObject(entry[1]));
+}
+const hasHref = (s) => isObject(s) && isObject(s["properties"]) && s["properties"]["href"] !== void 0;
+/** The link object branch of a link schema: the schema itself, or its `anyOf` branch with `href`. */
+function linkObjectSchema(schema) {
+	if (hasHref(schema)) return schema;
+	return (Array.isArray(schema["anyOf"]) ? schema["anyOf"] : []).find(hasHref);
+}
+/**
+* One named link as a flattened resource carries it: `{ href, type?, title?, meta? }`, typed from
+* the document's link schema, meta members included. A link the server renders as a bare URL is
+* normalised to `{ href }`.
+*/
+function linkOutput(doc, schema) {
+	const resolved = outputSchema(doc, schema);
+	const object = linkObjectSchema(resolved);
+	const source = isObject(object?.["properties"]) ? object["properties"] : {};
+	const properties = { href: {
+		type: "string",
+		format: "uri-reference"
+	} };
+	for (const member of LINK_MEMBERS) {
+		const value = source[member];
+		if (isObject(value)) properties[member] = member === "href" ? {
+			...properties["href"],
+			...value
+		} : value;
+	}
+	const out = {
+		type: "object",
+		properties,
+		required: ["href", ...(Array.isArray(object?.["required"]) ? object["required"] : []).filter((name) => name !== "href" && name in properties)]
+	};
+	if (typeof resolved["description"] === "string") out["description"] = resolved["description"];
+	return out;
+}
+/**
+* The names of the links each type names, for the types that name any. Throws when such a type
+* also has an attribute or relationship called `links`, which the flattened resource couldn't
+* hold beside them.
+*/
+function resourceLinkNames(doc, descriptor, schemas) {
+	const out = {};
+	for (const [type, resource] of Object.entries(descriptor)) {
+		const names = namedLinkSchemas(doc, schemas.get(type)).map(([name]) => name);
+		if (names.length === 0) continue;
+		if ("links" in resource.attributes || "links" in resource.relations) throw new Error(`The "${type}" type names links (${names.join(", ")}) and also has a field called "links". A flattened resource carries its links under "links", so rename the field.`);
+		out[type] = names;
+	}
+	return out;
+}
+/** One type's flattened resource schema: id, type, attributes, relations and named links, 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"]);
@@ -161,6 +235,12 @@ function flatResource(doc, descriptor, schemas, type, expanded) {
 			description: `The related ${target}: ${polymorphic ? "its type and id" : "its id"}, or the resource itself when included.`
 		};
 	}
+	const links = namedLinkSchemas(doc, resource);
+	if (links.length > 0) properties["links"] = {
+		type: "object",
+		description: "The links the resource names, such as an upload or download URL or a custom action. A link that does not apply to this resource is absent.",
+		properties: Object.fromEntries(links.map(([name, link]) => [name, linkOutput(doc, link)]))
+	};
 	const schema = {
 		type: "object",
 		properties,
@@ -195,65 +275,96 @@ const LINKS = {
 		last: { type: "string" }
 	}
 };
-/** A collection: `{ items, links, meta }`. */
+/** The document `meta` member of an envelope: what the response declares, when it sends any. */
+function documentMeta(ctx, description) {
+	return {
+		...responseMeta(ctx),
+		description
+	};
+}
+/** A collection: `{ data, links, meta? }`. */
 function collectionOutput(ctx, types) {
 	const reachable = reachableTypes(ctx.descriptor, types, ctx.includes);
 	return {
 		type: "object",
 		properties: {
-			items: {
+			data: {
 				type: "array",
-				items: types.length === 1 ? ref(types[0]) : { anyOf: types.map(ref) }
+				items: types.length === 1 ? ref(types[0]) : { anyOf: types.map(ref) },
+				description: "The resources on this page."
 			},
 			links: LINKS,
-			meta: {
-				...responseMeta(ctx),
-				description: "The document meta, such as page totals."
-			}
+			meta: documentMeta(ctx, "The document meta, such as page totals.")
 		},
-		required: ["items", "links"],
+		required: ["data", "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);
+/**
+* One resource: `{ data, meta? }`. `data` is null where the operation may find nothing, such as
+* a to-one related read with nothing related.
+*/
+function resourceOutput(ctx, types, nullable = false) {
+	const reachable = reachableTypes(ctx.descriptor, types, ctx.includes);
 	return {
-		...defs[type],
-		$defs: defs
+		type: "object",
+		properties: {
+			data: nullable !== false ? {
+				anyOf: [...types.map(ref), { type: "null" }],
+				description: nullable
+			} : types.length === 1 ? {
+				...ref(types[0]),
+				description: "The resource."
+			} : {
+				anyOf: types.map(ref),
+				description: "The resource."
+			},
+			meta: documentMeta(ctx, "The document meta, when the API sends any.")
+		},
+		required: ["data"],
+		$defs: defsFor(ctx.doc, ctx.descriptor, ctx.schemas, reachable)
 	};
 }
-/** 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);
+/** A delete: `{ data: null, meta? }`. */
+function deletedOutput(ctx) {
 	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)
+		properties: {
+			data: {
+				type: "null",
+				description: "Always null: the resource is gone."
+			},
+			meta: documentMeta(ctx, "The document meta, when the API sends any.")
+		},
+		required: ["data"]
 	};
 }
-/** A meta-only result: the document's `meta`. */
+/** A meta-only result: `{ meta }`, the document's own `meta`, with no `data`. */
 function metaOutput(ctx) {
 	return {
-		...responseMeta(ctx),
-		type: "object"
+		type: "object",
+		properties: { meta: {
+			...responseMeta(ctx),
+			type: "object",
+			description: "The document meta."
+		} },
+		required: ["meta"]
 	};
 }
 /** A JSON:API result whose primary type the descriptor doesn't name. */
-const LOOSE_OUTPUT = { type: "object" };
+const LOOSE_OUTPUT = {
+	type: "object",
+	properties: {
+		data: { description: "The flattened resource or resources." },
+		links: LINKS,
+		meta: {
+			type: "object",
+			description: "The document meta, when the API sends any."
+		}
+	}
+};
 /** The URL an action answered with (generator contract 17): `{ url, type, expiresAt? }`. */
-function locationOutput(mediaType) {
+function locationData(mediaType) {
 	return {
 		type: "object",
 		description: "The URL the action produced, such as a short-lived download link. The tool does not fetch it.",
@@ -277,6 +388,14 @@ function locationOutput(mediaType) {
 		additionalProperties: false
 	};
 }
+/** An action that answered with a URL: `{ data: { url, type, expiresAt? } }`. */
+function locationOutput(mediaType) {
+	return {
+		type: "object",
+		properties: { data: locationData(mediaType) },
+		required: ["data"]
+	};
+}
 /** 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;
@@ -1158,7 +1277,7 @@ function actionOutput(ctx, action) {
 function documentOutput(ctx, action) {
 	switch (actionResult(action)) {
 		case "collection": return collectionOutput(ctx, [action.outputType]);
-		case "resource": return resourceOutput(ctx, action.outputType);
+		case "resource": return resourceOutput(ctx, [action.outputType], "The resource the action returned.");
 		case "meta": return metaOutput(ctx);
 		case "loose": return LOOSE_OUTPUT;
 		default: return;
@@ -1169,6 +1288,7 @@ function buildCatalogue(doc, descriptor, defaultPageSize, includeDepth = null) {
 	const entries = [];
 	const skipped = [];
 	const schemas = resourceSchemas(doc);
+	const resourceLinks = resourceLinkNames(doc, descriptor, schemas);
 	for (const [path, item] of Object.entries(doc.paths ?? {})) for (const method of HTTP_METHODS) {
 		const operation = item[method];
 		const operationId = operation?.operationId;
@@ -1223,7 +1343,8 @@ function buildCatalogue(doc, descriptor, defaultPageSize, includeDepth = null) {
 	entries.sort((a, b) => a.tool.name.localeCompare(b.tool.name));
 	return {
 		entries,
-		skipped
+		skipped,
+		resourceLinks
 	};
 }
 function buildEntry(op, parsed, inputCtx, outputCtx, descriptor) {
@@ -1239,21 +1360,22 @@ function buildEntry(op, parsed, inputCtx, outputCtx, descriptor) {
 			break;
 		case "get":
 			input = singleInput(inputCtx, `The id of the \`${op.type}\` resource to get.`);
-			output = itemOutput(outputCtx, [op.type], false);
+			output = resourceOutput(outputCtx, [op.type]);
 			result = "item";
 			break;
 		case "create":
 			input = createInput(inputCtx, op.type);
-			output = resourceOutput(outputCtx, op.type);
+			output = resourceOutput(outputCtx, [op.type]);
 			result = "resource";
 			break;
 		case "update":
 			input = updateInput(inputCtx, op.type);
-			output = resourceOutput(outputCtx, op.type);
+			output = resourceOutput(outputCtx, [op.type]);
 			result = "resource";
 			break;
 		case "delete":
 			input = deleteInput(op.type);
+			output = deletedOutput(outputCtx);
 			result = "deleted";
 			break;
 		case "related": {
@@ -1270,7 +1392,7 @@ function buildEntry(op, parsed, inputCtx, outputCtx, descriptor) {
 				result = "collection";
 			} else {
 				input = singleInput(inputCtx, `The id of the \`${op.type}\` resource whose ${parsed.relation} to get.`);
-				output = itemOutput(outputCtx, relation.types, true);
+				output = resourceOutput(outputCtx, relation.types, "The related resource, or null when there is none.");
 				result = "item";
 			}
 			break;
@@ -1367,7 +1489,7 @@ function buildMcpModel(document, descriptor, options) {
 	const catalogue = buildCatalogue(document, descriptor, options.defaultPageSize ?? 10, includeDepth);
 	const info = document.info;
 	const model = {
-		format: 3,
+		format: 4,
 		generator: MODEL_GENERATOR,
 		contract,
 		source: {
@@ -1376,6 +1498,7 @@ function buildMcpModel(document, descriptor, options) {
 		},
 		credentialSchemes: oauthSchemes(document),
 		includeDepth,
+		resourceLinks: catalogue.resourceLinks,
 		descriptor,
 		tools: catalogue.entries.map((entry) => {
 			const { op } = entry;
@@ -1471,4 +1594,4 @@ async function writeMcpModel(options) {
 //#endregion
 export { buildMcpModel as i, serialiseMcpModel as n, writeMcpModel as r, generateMcpModel as t };
 
-//# sourceMappingURL=generate-CiLuqQJ0.mjs.map
+//# sourceMappingURL=generate-BcqHRSxB.mjs.map