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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gregory Haddow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @haddowg/json-api-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Part of the [jsonapi.rest](https://jsonapi.rest) suite** — a complete, spec-compliant
+> JSON:API 1.1 stack: a framework-agnostic PHP [core](https://github.com/haddowg/json-api), a
+> [Symfony bundle](https://github.com/haddowg/json-api-symfony), a
+> [Laravel package](https://github.com/haddowg/json-api-laravel), and the **typed TypeScript
+> client**, bound together by one conformance-tested OpenAPI 3.1 contract.
+> Full documentation: **[haddowg.github.io/json-api-ts](https://haddowg.github.io/json-api-ts/)**.
+
+MCP tool definitions and a call handler for a `haddowg/json-api` server. A build-time
+generator turns the server's OpenAPI document into one JSON model, which you commit; the
+runtime serves one tool per collection, resource, related and custom action operation from it,
+with input schemas valid under OpenAI's and Anthropic's strict modes. Calls run through
+[`@haddowg/json-api-client`](../client). The package doesn't own an MCP server: the host lists
+the tools and passes calls to the handler.
+
+## Install
+
+```bash
+npm install @haddowg/json-api-mcp @haddowg/json-api-client
+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
+```
+
+Tools include one relationship deep by default, so each tool's schema carries only the types its
+direct relations reach. Pass `--include-depth <n>`, or `all` for every path the document
+declares, to change that.
+
+## Serve it
+
+The runtime loads from ESM or CommonJS and needs only the client.
+
+```ts
+const { createJsonApiMcp } = require('@haddowg/json-api-mcp')
+
+const mcp = createJsonApiMcp({ model: require('./mcp/v5.mcp.json') })
+const session = await mcp.forRequest({ grantedScopes: token.scopes, context: { token } })
+session.tools // answer tools/list with these
+await session.callTool('albums_list', { sort: ['-releasedAt'], pageSize: 5 })
+```
+
+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`,
+`includeOperation`, `decorateTool`, `requestInit` and `mapError`. See the
+[MCP tools guide](https://haddowg.github.io/json-api-ts/mcp/).

package/dist/cli.d.mts

@@ -0,0 +1,11 @@
+import { n as WriteModelOptions } from "./generate-CuWnYJUB.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]";
+/** Read the command line into generator options. */
+declare function parseArgs(argv: readonly string[]): Partial<WriteModelOptions>;
+/** Run the CLI; resolves to the process exit code. */
+declare function main(argv: readonly string[]): Promise<number>;
+//#endregion
+export { USAGE, main, parseArgs };
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";;;cAKa,KAAA;AAAb;AAAA,iBAIgB,SAAA,CAAU,IAAA,sBAA0B,OAAO,CAAC,iBAAA;;iBA8BtC,IAAA,CAAK,IAAA,sBAA0B,OAAO"}

package/dist/cli.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { r as writeMcpModel } from "./generate-CiLuqQJ0.mjs";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/cli.ts
+const USAGE = "Usage: json-api-mcp --input <url|file> --output <file> [--default-page-size <n>] [--include-depth <n|all>] [--check]";
+/** Read the command line into generator options. */
+function parseArgs(argv) {
+	const options = {};
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--check") {
+			options.check = true;
+			continue;
+		}
+		const next = argv[i + 1];
+		if (next === void 0) continue;
+		if (arg === "--input") {
+			options.input = next;
+			i++;
+		} else if (arg === "--output") {
+			options.output = next;
+			i++;
+		} else if (arg === "--default-page-size") {
+			options.defaultPageSize = Number(next);
+			i++;
+		} else if (arg === "--include-depth") {
+			options.includeDepth = next === "all" ? null : Number(next);
+			i++;
+		}
+	}
+	return options;
+}
+/** Run the CLI; resolves to the process exit code. */
+async function main(argv) {
+	const options = parseArgs(argv);
+	if (options.input === void 0 || options.output === void 0) {
+		console.error(USAGE);
+		return 1;
+	}
+	if (options.defaultPageSize !== void 0 && !(Number.isInteger(options.defaultPageSize) && options.defaultPageSize > 0)) {
+		console.error("--default-page-size takes a positive whole number");
+		return 1;
+	}
+	if (typeof options.includeDepth === "number" && !(Number.isInteger(options.includeDepth) && options.includeDepth >= 0)) {
+		console.error("--include-depth takes a whole number of 0 or more, or all");
+		return 1;
+	}
+	try {
+		const result = await writeMcpModel(options);
+		if (options.check === true) {
+			if (!result.upToDate) {
+				console.error(`[json-api-mcp] ${result.path} is out of date with ${options.input}; run json-api-mcp without --check to regenerate it.`);
+				return 1;
+			}
+			console.error(`ok   ${result.path}`);
+			return 0;
+		}
+		console.error(`[json-api-mcp] wrote ${result.path}`);
+		return 0;
+	} catch (error) {
+		console.error(`[json-api-mcp] ${error instanceof Error ? error.message : String(error)}`);
+		return 1;
+	}
+}
+const invoked = process.argv[1];
+if (invoked !== void 0 && realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url))) process.exitCode = await main(process.argv.slice(2));
+//#endregion
+export { USAGE, main, parseArgs };
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { realpathSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\nimport { writeMcpModel, type WriteModelOptions } from './generate'\n\nexport const USAGE =\n  'Usage: json-api-mcp --input <url|file> --output <file> [--default-page-size <n>] [--include-depth <n|all>] [--check]'\n\n/** Read the command line into generator options. */\nexport function parseArgs(argv: readonly string[]): Partial<WriteModelOptions> {\n  const options: Partial<WriteModelOptions> = {}\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i]\n    if (arg === '--check') {\n      options.check = true\n      continue\n    }\n    const next = argv[i + 1]\n    if (next === undefined) {\n      continue\n    }\n    if (arg === '--input') {\n      options.input = next\n      i++\n    } else if (arg === '--output') {\n      options.output = next\n      i++\n    } else if (arg === '--default-page-size') {\n      options.defaultPageSize = Number(next)\n      i++\n    } else if (arg === '--include-depth') {\n      options.includeDepth = next === 'all' ? null : Number(next)\n      i++\n    }\n  }\n  return options\n}\n\n/** Run the CLI; resolves to the process exit code. */\nexport async function main(argv: readonly string[]): Promise<number> {\n  const options = parseArgs(argv)\n  if (options.input === undefined || options.output === undefined) {\n    console.error(USAGE)\n    return 1\n  }\n  if (\n    options.defaultPageSize !== undefined &&\n    !(Number.isInteger(options.defaultPageSize) && options.defaultPageSize > 0)\n  ) {\n    console.error('--default-page-size takes a positive whole number')\n    return 1\n  }\n  if (\n    typeof options.includeDepth === 'number' &&\n    !(Number.isInteger(options.includeDepth) && options.includeDepth >= 0)\n  ) {\n    console.error('--include-depth takes a whole number of 0 or more, or all')\n    return 1\n  }\n  try {\n    const result = await writeMcpModel(options as WriteModelOptions)\n    if (options.check === true) {\n      if (!result.upToDate) {\n        console.error(\n          `[json-api-mcp] ${result.path} is out of date with ${options.input}; run json-api-mcp without --check to regenerate it.`,\n        )\n        return 1\n      }\n      console.error(`ok   ${result.path}`)\n      return 0\n    }\n    console.error(`[json-api-mcp] wrote ${result.path}`)\n    return 0\n  } catch (error) {\n    console.error(`[json-api-mcp] ${error instanceof Error ? error.message : String(error)}`)\n    return 1\n  }\n}\n\n// A package manager runs the bin through a symlink, so compare real paths.\nconst invoked = process.argv[1]\nif (\n  invoked !== undefined &&\n  realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url))\n) {\n  process.exitCode = await main(process.argv.slice(2))\n}\n"],"mappings":";;;;;AAKA,MAAa,QACX;;AAGF,SAAgB,UAAU,MAAqD;CAC7E,MAAM,UAAsC,CAAC;CAC7C,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,MAAM,MAAM,KAAK;EACjB,IAAI,QAAQ,WAAW;GACrB,QAAQ,QAAQ;GAChB;EACF;EACA,MAAM,OAAO,KAAK,IAAI;EACtB,IAAI,SAAS,KAAA,GACX;EAEF,IAAI,QAAQ,WAAW;GACrB,QAAQ,QAAQ;GAChB;EACF,OAAO,IAAI,QAAQ,YAAY;GAC7B,QAAQ,SAAS;GACjB;EACF,OAAO,IAAI,QAAQ,uBAAuB;GACxC,QAAQ,kBAAkB,OAAO,IAAI;GACrC;EACF,OAAO,IAAI,QAAQ,mBAAmB;GACpC,QAAQ,eAAe,SAAS,QAAQ,OAAO,OAAO,IAAI;GAC1D;EACF;CACF;CACA,OAAO;AACT;;AAGA,eAAsB,KAAK,MAA0C;CACnE,MAAM,UAAU,UAAU,IAAI;CAC9B,IAAI,QAAQ,UAAU,KAAA,KAAa,QAAQ,WAAW,KAAA,GAAW;EAC/D,QAAQ,MAAM,KAAK;EACnB,OAAO;CACT;CACA,IACE,QAAQ,oBAAoB,KAAA,KAC5B,EAAE,OAAO,UAAU,QAAQ,eAAe,KAAK,QAAQ,kBAAkB,IACzE;EACA,QAAQ,MAAM,mDAAmD;EACjE,OAAO;CACT;CACA,IACE,OAAO,QAAQ,iBAAiB,YAChC,EAAE,OAAO,UAAU,QAAQ,YAAY,KAAK,QAAQ,gBAAgB,IACpE;EACA,QAAQ,MAAM,2DAA2D;EACzE,OAAO;CACT;CACA,IAAI;EACF,MAAM,SAAS,MAAM,cAAc,OAA4B;EAC/D,IAAI,QAAQ,UAAU,MAAM;GAC1B,IAAI,CAAC,OAAO,UAAU;IACpB,QAAQ,MACN,kBAAkB,OAAO,KAAK,uBAAuB,QAAQ,MAAM,qDACrE;IACA,OAAO;GACT;GACA,QAAQ,MAAM,QAAQ,OAAO,MAAM;GACnC,OAAO;EACT;EACA,QAAQ,MAAM,wBAAwB,OAAO,MAAM;EACnD,OAAO;CACT,SAAS,OAAO;EACd,QAAQ,MAAM,kBAAkB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAAG;EACxF,OAAO;CACT;AACF;AAGA,MAAM,UAAU,QAAQ,KAAK;AAC7B,IACE,YAAY,KAAA,KACZ,aAAa,OAAO,MAAM,aAAa,cAAc,OAAO,KAAK,GAAG,CAAC,GAErE,QAAQ,WAAW,MAAM,KAAK,QAAQ,KAAK,MAAM,CAAC,CAAC"}