@haddowg/json-api-mcp 1.2.1 → 1.4.0

package/README.md

@@ -24,8 +24,8 @@ npm install --save-dev @haddowg/json-api-codegen
 ## Generate the model
 
 ```bash
-npx json-api-mcp --input openapi/v5.json --output src/mcp/v5.mcp.json
-npx json-api-mcp --input openapi/v5.json --output src/mcp/v5.mcp.json --check # in CI
+npx @haddowg/json-api-mcp --input openapi/v5.json --output src/mcp/v5.mcp.json
+npx @haddowg/json-api-mcp --input openapi/v5.json --output src/mcp/v5.mcp.json --check # in CI
 ```
 
 Tools include one relationship deep by default, so each tool's schema carries only the types its
@@ -45,6 +45,20 @@ 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`. A delete returns `{ data: null }` instead of a line of text, a
+meta-only action `{ meta }` instead of the bare meta object, and a URL action
+`{ data: { url, type, expiresAt? } }` instead of the bare object. 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. The [migration notes](https://haddowg.github.io/json-api-ts/mcp/#migrating-from-12)
+cover the rest.
+
 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-yf5Kc4Yh.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{generate-CuWnYJUB.d.mts → generate-D0kx-DHv.d.mts}

@@ -196,7 +196,7 @@ type ResultShape = 'collection' | 'resource' | 'item' | 'deleted' | 'meta' | 'lo
 //#endregion
 //#region src/model.d.ts
 /** The artefact's own format. A runtime refuses a format it doesn't know. */
-declare const MODEL_FORMAT = 3;
+declare const MODEL_FORMAT = 4;
 /** The package that writes the artefact. */
 declare const MODEL_GENERATOR = "@haddowg/json-api-mcp";
 /** One operation, as hooks see it, without the descriptor entries the runtime adds back. */
@@ -243,7 +243,7 @@ interface McpModelTool {
 }
 /** The generated artefact. */
 interface McpModel {
-  format: 1 | 2 | typeof MODEL_FORMAT;
+  format: 1 | 2 | 3 | typeof MODEL_FORMAT;
   generator: typeof MODEL_GENERATOR;
   /** The generator contract the source document declared. */
   contract: number;
@@ -269,6 +269,11 @@ interface McpModel {
    * declares. Formats 1 and 2 don't carry it and set no cap.
    */
   includeDepth?: number | null;
+  /**
+   * Format 4: the links each type names, its declared links and action links, for the types that
+   * name any. A flattened resource carries these under `links`.
+   */
+  resourceLinks?: Record<string, string[]>;
   /** The json-api-ts descriptor the client calls through. */
   descriptor: ApiDescriptor;
   tools: McpModelTool[];
@@ -334,4 +339,4 @@ interface WriteModelResult {
 declare function writeMcpModel(options: WriteModelOptions): Promise<WriteModelResult>;
 //#endregion
 export { serialiseMcpModel as a, buildMcpModel as c, generateMcpModel as i, WriteModelOptions as n, writeMcpModel as o, WriteModelResult as r, BuildModelOptions as s, GenerateModelOptions as t };
-//# sourceMappingURL=generate-CuWnYJUB.d.mts.map
+//# sourceMappingURL=generate-D0kx-DHv.d.mts.map

package/dist/{generate-CuWnYJUB.d.mts.map → generate-D0kx-DHv.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"generate-CuWnYJUB.d.mts","names":[],"sources":["../src/openapi.ts","../src/portable.ts","../src/inputs.ts","../src/types.ts","../src/catalogue.ts","../src/model.ts","../src/build.ts","../src/generate.ts"],"mappings":"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"}
+{"version":3,"file":"generate-D0kx-DHv.d.mts","names":[],"sources":["../src/openapi.ts","../src/portable.ts","../src/inputs.ts","../src/types.ts","../src/catalogue.ts","../src/model.ts","../src/build.ts","../src/generate.ts"],"mappings":"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"}

package/dist/{generate-CiLuqQJ0.mjs → generate-yf5Kc4Yh.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;
@@ -1323,9 +1445,9 @@ function buildEntry(op, parsed, inputCtx, outputCtx, descriptor) {
 */
 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
@@ -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-yf5Kc4Yh.mjs.map