@knitli/openapi-mcp 1.1.0 → 1.2.1

package/README.md

@@ -75,6 +75,55 @@ base64url SPKI public key for the config with:
 node --input-type=module -e 'import {readFileSync} from "node:fs"; import {createPublicKey} from "node:crypto"; console.log(createPublicKey(readFileSync("operator/keys/openapi-mcp.pub")).export({type:"spki",format:"der"}).toString("base64url"))'
 ```
 
+### Slice a large document down to one deployment's catalog
+
+`compile-release` enforces `maxDocumentKeys` (default 250,000) and
+`maxDocumentNodes` (default 1,000,000) on the whole spec. A document like
+Microsoft Graph's full v1.0 (over 1M nodes, served from a single `/v1.0`) will
+never fit, no matter how few operations one deployment actually exposes. `slice`
+filters an OpenAPI document down to the operations you select by `--tag` and/or
+`--operation`, prunes every `components` entry nothing kept still references,
+and rewrites `servers` to the bare origin `compile-release` requires (it rejects
+any `servers[0].url` with a path component):
+
+```sh
+./node_modules/.bin/openapi-mcp slice \
+  --spec ./graph-v1.0.yaml --out ./sliced/mail.json \
+  --tag me.message --operation me.sendMail \
+  --max-document-keys 5000000 --max-document-nodes 20000000
+./node_modules/.bin/openapi-mcp compile-release \
+  --spec ./sliced/mail.json --source-label graph-mail --source-revision revision-1 \
+  --catalog mail --release mail-1 --generation 1 \
+  --issuer example-operator --key-id signing-1 --policy-id local-policy-1 \
+  --allowed-origin https://graph.microsoft.com \
+  --out ./operator/releases --sign-key ./operator/keys/openapi-mcp.key
+```
+
+`--max-document-keys` and `--max-document-nodes` only raise the limits `slice`
+itself loads the source document under (`loadSpecV4`'s `CompilerLimits`); they
+have no effect on the sliced output's own size, which is whatever fits under
+`compile-release`'s (unraised) defaults. On success `slice` prints a summary
+line, for example:
+
+```
+paths=23 operations=33 schemas=30 keys=3027 (fits compile-release's default maxDocumentKeys=250000)
+```
+
+`keys=` is the sliced document's own key count, counted the same way the
+compiler counts `maxDocumentKeys`; the number in parentheses is
+`compile-release`'s own (unraised) default, so you can tell before running it
+whether the selection is small enough. An `--operation` or `--tag` that matched
+nothing is an error, not a silently smaller release — fix the typo it names.
+OpenAPI 3.1 `webhooks` are not part of `paths` and are left untouched, dangling
+refs and all; Graph's v1.0 document (3.0) has none.
+
+`--optional <propertyName>` (repeatable) removes that property from every
+`required` array anywhere in the sliced output — component schemas and inline
+request, parameter and response schemas alike — dropping `required` entirely
+where that empties it. Graph's OpenAPI document marks `@odata.type` `required` on nearly
+every schema, but the Graph service itself never requires it on request
+bodies, so pass `--optional '@odata.type'` when slicing Graph specs.
+
 ## Configure and start the local MCP server
 
 Save this as `operator/config.json`, substituting absolute paths, the public key,

package/dist/cli.js

@@ -4,8 +4,10 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { compile } from "./compile.js";
 import { compileRelease } from "./release/compile-release.js";
+import { DEFAULT_COMPILER_LIMITS, loadSpecV4 } from "./release/load-v4.js";
 import { publishRelease } from "./release/publish.js";
 import { generateKeypair, signArtifact, verifyArtifact } from "./sign.js";
+import { countKeys, HTTP_METHODS, keyBudgetNote, sliceSpec } from "./slice.js";
 const USAGE = `openapi-mcp — compile OpenAPI documents into signed MCP artifacts
 
   compile --spec <path> --api <name> --out <path> [--append] [--permissions <path>] [--sign-key <path>]  (legacy v3)
@@ -13,6 +15,7 @@ const USAGE = `openapi-mcp — compile OpenAPI documents into signed MCP artifac
     --catalog <id> --release <id> --generation <n> --issuer <id> --key-id <id>
     --policy-id <id> --allowed-origin <https-origin> --out <directory> --sign-key <path>
     [--permissions <path>] [--reference-root <path> --reference-map <path>]
+  slice --spec <openapi.yaml|json> --out <sliced.json> [--tag <tag>]... [--operation <operationId>]... [--optional <propertyName>]... [--max-document-keys <n>] [--max-document-nodes <n>]
   verify --artifact <path> --sig <path> --pub <path>  (legacy v3 exact-file signature)
   keygen [--out <dir>]
   serve --config <absolute-config-path>
@@ -203,6 +206,48 @@ if (command === "compile-release") {
     }
     process.exit(0);
 }
+if (command === "slice") {
+    const { values } = parseOrFail({
+        args: rest,
+        options: {
+            spec: { type: "string" },
+            out: { type: "string" },
+            tag: { type: "string", multiple: true },
+            operation: { type: "string", multiple: true },
+            optional: { type: "string", multiple: true },
+            "max-document-keys": { type: "string" },
+            "max-document-nodes": { type: "string" },
+        },
+        strict: true,
+    });
+    if (!values.spec)
+        fail("--spec is required");
+    if (!values.out)
+        fail("--out is required");
+    try {
+        const document = (await loadSpecV4(values.spec, {
+            maxDocumentKeys: Number(values["max-document-keys"] ?? 5_000_000),
+            maxDocumentNodes: Number(values["max-document-nodes"] ?? 20_000_000),
+        }));
+        const sliced = sliceSpec(document, {
+            tags: values.tag ?? [],
+            operations: values.operation ?? [],
+            optional: values.optional ?? [],
+        });
+        await writeFile(values.out, `${JSON.stringify(sliced, null, 2)}\n`);
+        const paths = sliced.paths;
+        const operationCount = Object.values(paths).reduce((n, item) => n +
+            Object.keys(item).filter((k) => HTTP_METHODS.includes(k)).length, 0);
+        const schemaCount = Object.keys((sliced.components.schemas ?? {})).length;
+        const keys = countKeys(sliced);
+        console.log(`paths=${Object.keys(paths).length} operations=${operationCount} schemas=${schemaCount} ` +
+            `keys=${keys} (${keyBudgetNote(keys, DEFAULT_COMPILER_LIMITS.maxDocumentKeys)})`);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err), { usage: false });
+    }
+    process.exit(0);
+}
 if (command !== "serve") {
     if (command !== "compile") {
         fail(command ? `unknown command "${command}"` : "no command given");

package/dist/runtime/serialize.js

@@ -308,6 +308,18 @@ function validateDiscriminator(schema, branches, value) {
         schemaFailure();
     return selected[0];
 }
+/** Indices of the `anyOf`/`oneOf` branches the value validates against. When the schema also
+ * carries a discriminator, the branch it selects must be among them. */
+function matchingBranches(schema, raw, value, closure, depth, context) {
+    const branches = schemaArray(raw);
+    const selected = validateDiscriminator(schema, branches, value);
+    const matches = branches
+        .map((branch, index) => validates(branch, value, closure, depth + 1, context) ? index : -1)
+        .filter((index) => index >= 0);
+    if (selected !== null && !matches.includes(selected))
+        schemaFailure();
+    return matches;
+}
 function validateReference(id, schema, value, closure, depth, context) {
     const activeValues = context.activeReferences.get(id) ?? new Set();
     if (activeValues.has(value))
@@ -349,22 +361,22 @@ function validateSchema(schema, value, closure, depth, context) {
             validateSchema(branch, value, closure, depth + 1, context);
     }
     if (Object.hasOwn(schema, "anyOf")) {
-        const matches = schemaArray(schema.anyOf).filter((branch) => validates(branch, value, closure, depth + 1, context));
+        const matches = matchingBranches(schema, schema.anyOf, value, closure, depth, context);
         if (matches.length === 0)
             schemaFailure();
     }
     if (Object.hasOwn(schema, "oneOf")) {
-        const branches = schemaArray(schema.oneOf);
-        const selected = validateDiscriminator(schema, branches, value);
-        const matches = branches
-            .map((branch, index) => validates(branch, value, closure, depth + 1, context) ? index : -1)
-            .filter((index) => index >= 0);
-        if (matches.length !== 1 || (selected !== null && matches[0] !== selected))
+        const matches = matchingBranches(schema, schema.oneOf, value, closure, depth, context);
+        if (matches.length !== 1)
             schemaFailure();
     }
-    else if (Object.hasOwn(schema, "discriminator")) {
+    // A `discriminator` with no `oneOf`/`anyOf` alongside it is OpenAPI 3.0's inheritance form
+    // (OpenAPI 3.0.3 §4.7.24.2, Discriminator Object, "composition and inheritance"): it names the
+    // property a *consumer* would branch on, but the schema itself is a plain `type: object`
+    // (optionally under `allOf`) with no selection for us to perform. Ignore it rather than reject,
+    // but keep the same shape check every other supported key gets.
+    else if (Object.hasOwn(schema, "discriminator") && !isObject(schema.discriminator))
         schemaFailure();
-    }
     if (Object.hasOwn(schema, "nullable")) {
         if (typeof schema.nullable !== "boolean")
             schemaFailure();

package/dist/slice.d.ts

@@ -0,0 +1,22 @@
+export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+type Json = Record<string, unknown>;
+/** Which operations survive: any of these tags, or any of these operation ids. `optional` names
+ * properties to drop from every `required` array in the sliced output — see `dropRequired`. */
+export interface SliceSelection {
+    readonly tags: readonly string[];
+    readonly operations: readonly string[];
+    readonly optional?: readonly string[];
+}
+/** Returns a new value with every `name` in `names` removed from every `required` array found
+ * anywhere in `document` — component schemas and inline schemas (paths, requestBodies,
+ * parameters) alike — deleting the `required` key entirely if that empties it. Does not mutate
+ * `document`. Graph's OpenAPI document marks `@odata.type` `required` on nearly every schema,
+ * but the service itself never requires it on request bodies. */
+export declare function dropRequired(document: Json, names: ReadonlySet<string>): Json;
+/** Number of object keys in a JSON value; compare with the compiler's `maxDocumentKeys` (250,000). */
+export declare function countKeys(value: unknown): number;
+/** Describes a key count against compile-release's default `maxDocumentKeys`, and what to do if it doesn't fit. */
+export declare function keyBudgetNote(keys: number, limit: number): string;
+/** Pure: returns a new document containing only the selected operations and what they reference. */
+export declare function sliceSpec(document: Json, selection: SliceSelection): Json;
+export {};

package/dist/slice.js

@@ -0,0 +1,247 @@
+// Slice an OpenAPI 3.x document down to the operations a deployment will expose, prune the
+// components nothing left references, and rewrite `servers` to the bare origin `compile-release`
+// requires. This is what lets a document far beyond `maxDocumentKeys` (Microsoft Graph's full
+// v1.0, served from `/v1.0`) be compiled as one catalog per deployment.
+//
+// OpenAPI 3.1 `webhooks` are deliberately left untouched: they are not part of `paths` and are
+// spread through as-is, dangling refs and all, same as any other top-level key. Graph is 3.0 and
+// has none.
+export const HTTP_METHODS = [
+    "get",
+    "put",
+    "post",
+    "delete",
+    "options",
+    "head",
+    "patch",
+    "trace",
+];
+/** Returns a new value with every `name` in `names` removed from every `required` array found
+ * anywhere in `document` — component schemas and inline schemas (paths, requestBodies,
+ * parameters) alike — deleting the `required` key entirely if that empties it. Does not mutate
+ * `document`. Graph's OpenAPI document marks `@odata.type` `required` on nearly every schema,
+ * but the service itself never requires it on request bodies. */
+export function dropRequired(document, names) {
+    function walk(value) {
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (!value || typeof value !== "object")
+            return value;
+        const result = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (key === "required" && Array.isArray(item)) {
+                const kept = item.filter((name) => typeof name !== "string" || !names.has(name));
+                if (kept.length > 0)
+                    result[key] = kept;
+                continue;
+            }
+            result[key] = walk(item);
+        }
+        return result;
+    }
+    return walk(document);
+}
+/** Number of object keys in a JSON value; compare with the compiler's `maxDocumentKeys` (250,000). */
+export function countKeys(value) {
+    if (Array.isArray(value))
+        return value.reduce((sum, item) => sum + countKeys(item), 0);
+    if (value && typeof value === "object") {
+        return Object.entries(value).reduce((sum, [, item]) => sum + 1 + countKeys(item), 0);
+    }
+    return 0;
+}
+/** Describes a key count against compile-release's default `maxDocumentKeys`, and what to do if it doesn't fit. */
+export function keyBudgetNote(keys, limit) {
+    return keys <= limit
+        ? `fits compile-release's default maxDocumentKeys=${limit}`
+        : `exceeds compile-release's default maxDocumentKeys=${limit}; pass --max-document-keys to compile-release`;
+}
+function collectRefs(value, into) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectRefs(item, into);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, item] of Object.entries(value)) {
+        if (key === "$ref" &&
+            typeof item === "string" &&
+            item.startsWith("#/components/"))
+            into.add(item);
+        else
+            collectRefs(item, into);
+    }
+}
+/** A `$ref` path segment is a URI-fragment-encoded JSON pointer token: decode `%xx`, then `~1`
+ * (`/`) and `~0` (`~`), in that order, so a component named e.g. `a/b` round-trips. */
+function decodeRefSegment(raw) {
+    return decodeURIComponent(raw).replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function refParts(ref) {
+    const [, , kind, name] = ref.split("/");
+    if (kind === undefined || name === undefined)
+        return undefined;
+    return { kind, name: decodeRefSegment(name) };
+}
+function securitySchemeNames(requirements, into) {
+    if (!Array.isArray(requirements))
+        return;
+    for (const requirement of requirements) {
+        if (!requirement || typeof requirement !== "object")
+            continue;
+        for (const name of Object.keys(requirement))
+            into.add(name);
+    }
+}
+/** Walks `document.paths`, keeping only operations matching `selection`, and reports which
+ * selectors actually matched something (an unmatched selector is the caller's problem, not
+ * this function's — checked by `sliceSpec`). */
+function selectOperations(document, selection) {
+    const tags = new Set(selection.tags);
+    const operations = new Set(selection.operations);
+    const matchedTags = new Set();
+    const matchedOperations = new Set();
+    const keptOperations = [];
+    const paths = {};
+    for (const [path, item] of Object.entries((document.paths ?? {}))) {
+        const source = item;
+        const target = { ...source };
+        let keptAny = false;
+        for (const method of HTTP_METHODS) {
+            const operation = source[method];
+            if (!operation)
+                continue;
+            const operationTags = Array.isArray(operation.tags)
+                ? operation.tags
+                : [];
+            const matchingTags = operationTags.filter((tag) => tags.has(tag));
+            const operationId = operation.operationId;
+            const matchesOperation = operationId !== undefined && operations.has(operationId);
+            if (matchingTags.length === 0 && !matchesOperation) {
+                delete target[method];
+                continue;
+            }
+            for (const tag of matchingTags)
+                matchedTags.add(tag);
+            if (matchesOperation && operationId !== undefined)
+                matchedOperations.add(operationId);
+            keptAny = true;
+            keptOperations.push(operation);
+        }
+        if (!keptAny)
+            continue;
+        paths[path] = target;
+    }
+    if (matchedTags.size === 0 && matchedOperations.size === 0)
+        throw new Error("The selection selected no operations.");
+    const unmatched = [
+        ...[...tags].filter((tag) => !matchedTags.has(tag)),
+        ...[...operations].filter((id) => !matchedOperations.has(id)),
+    ];
+    if (unmatched.length > 0)
+        throw new Error(`Selection matched nothing for: ${unmatched.join(", ")}`);
+    return { paths, keptOperations };
+}
+/** Transitive closure over `$ref` keys only, starting from the kept paths. Discriminator
+ * mappings are plain strings and are followed separately (`pruneDiscriminatorMapping`), so a
+ * pruned mapping target can be dropped instead of resolved. */
+function resolveReachableRefs(paths, components) {
+    const reachable = new Set();
+    const pending = new Set();
+    collectRefs(paths, pending);
+    while (pending.size) {
+        const ref = pending.values().next().value;
+        pending.delete(ref);
+        if (reachable.has(ref))
+            continue;
+        reachable.add(ref);
+        const parts = refParts(ref);
+        const component = parts !== undefined ? components[parts.kind]?.[parts.name] : undefined;
+        if (component === undefined)
+            throw new Error(`Unresolvable reference ${ref}`);
+        const next = new Set();
+        collectRefs(component, next);
+        for (const item of next)
+            if (!reachable.has(item))
+                pending.add(item);
+    }
+    return reachable;
+}
+/** Security schemes are referenced by name in `security` requirements, not by `$ref`, so the
+ * closure in `resolveReachableRefs` never finds them; collect the names the kept operations (or
+ * the root, when an operation has no override) actually use. */
+function collectUsedSecuritySchemes(document, keptOperations) {
+    const usedSchemes = new Set();
+    securitySchemeNames(document.security, usedSchemes);
+    for (const operation of keptOperations)
+        securitySchemeNames(operation.security, usedSchemes);
+    return usedSchemes;
+}
+function buildPrunedComponents(components, reachable, usedSchemes) {
+    const prunedComponents = {};
+    for (const ref of reachable) {
+        const parts = refParts(ref);
+        if (parts === undefined)
+            continue;
+        const bucket = components[parts.kind];
+        if (bucket === undefined)
+            continue;
+        let component = bucket[parts.name];
+        if (parts.kind === "schemas" &&
+            component &&
+            typeof component === "object") {
+            component = pruneDiscriminatorMapping(component, reachable);
+        }
+        const target = prunedComponents[parts.kind] ?? {};
+        target[parts.name] = component;
+        prunedComponents[parts.kind] = target;
+    }
+    if (usedSchemes.size > 0) {
+        const schemes = components.securitySchemes ?? {};
+        const target = {};
+        for (const name of usedSchemes)
+            if (name in schemes)
+                target[name] = schemes[name];
+        if (Object.keys(target).length > 0)
+            prunedComponents.securitySchemes = target;
+    }
+    return prunedComponents;
+}
+/** Pure: returns a new document containing only the selected operations and what they reference. */
+export function sliceSpec(document, selection) {
+    const { paths, keptOperations } = selectOperations(document, selection);
+    const components = (document.components ?? {});
+    const reachable = resolveReachableRefs(paths, components);
+    const usedSchemes = collectUsedSecuritySchemes(document, keptOperations);
+    const prunedComponents = buildPrunedComponents(components, reachable, usedSchemes);
+    const server = document.servers?.[0]?.url;
+    if (!server)
+        throw new Error("The document names no server.");
+    const sliced = {
+        ...document,
+        servers: [{ url: new URL(server).origin }],
+        paths,
+        components: prunedComponents,
+    };
+    const optional = selection.optional ?? [];
+    return optional.length > 0 ? dropRequired(sliced, new Set(optional)) : sliced;
+}
+/** Drops `discriminator.mapping` entries whose target is not in the kept closure, on a shallow
+ * copy — the schema itself is left aliased to the source document when there is nothing to prune. */
+function pruneDiscriminatorMapping(schema, reachable) {
+    const discriminator = schema.discriminator;
+    const mapping = discriminator?.mapping;
+    if (!discriminator || !mapping)
+        return schema;
+    const prunedMapping = {};
+    for (const [key, target] of Object.entries(mapping))
+        if (reachable.has(target))
+            prunedMapping[key] = target;
+    if (Object.keys(prunedMapping).length === Object.keys(mapping).length)
+        return schema;
+    return {
+        ...schema,
+        discriminator: { ...discriminator, mapping: prunedMapping },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@knitli/openapi-mcp",
   "private": false,
-  "version": "1.1.0",
+  "version": "1.2.1",
   "type": "module",
   "description": "Compile signed OpenAPI catalogs and serve verified search and authorized API calls over MCP.",
   "license": "MIT OR Apache-2.0",