@knitli/openapi-mcp 1.0.0 → 1.2.0

package/README.md

@@ -75,6 +75,48 @@ 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.
+
 ## Configure and start the local MCP server
 
 Save this as `operator/config.json`, substituting absolute paths, the public key,
@@ -217,6 +259,17 @@ restart with the remaining valid catalogs. Config requires at least one catalog;
 leave the server stopped if disabling the last one. Removing a file while the
 process is using it is not a reliable disable procedure.
 
+## Complete release admission
+
+`admitCatalogRelease(options, catalogId, releaseId)` from
+`@knitli/openapi-mcp/runtime` verifies every signed inventory operation and
+schema before admitting the generation through the configured `GenerationStore`.
+It revalidates the manifest and inventory around generation CAS retries. Use
+this supported portable API when activating an executable catalog; `admitManifest`
+retains its signed-envelope-only contract. Storage must preserve immutable release
+identities. Admission does not guarantee future availability, so runtime reads
+continue verifying records at use time.
+
 ## Recover from a bad release
 
 Before release, record the prior **observed package version**, its tarball digest,

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>]... [--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,46 @@ 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 },
+            "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 ?? [],
+        });
+        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/admission.d.ts

@@ -0,0 +1,8 @@
+import type { AdmittedManifest } from "./manifest.ts";
+import { type OpenApiRuntimeOptions } from "./runtime.ts";
+import type { CatalogId, ReleaseId } from "./types.ts";
+/** Verify the complete release inventory before atomically admitting its generation.
+ * Storage must preserve immutable release identities; later runtime reads still
+ * verify records because this check cannot guarantee future storage availability.
+ */
+export declare function admitCatalogRelease(options: OpenApiRuntimeOptions, catalogId: CatalogId, releaseId: ReleaseId): Promise<AdmittedManifest>;

package/dist/runtime/admission.js

@@ -0,0 +1,9 @@
+import { admitExecutableRelease, verifyExecutableRelease, } from "./runtime.js";
+/** Verify the complete release inventory before atomically admitting its generation.
+ * Storage must preserve immutable release identities; later runtime reads still
+ * verify records because this check cannot guarantee future storage availability.
+ */
+export async function admitCatalogRelease(options, catalogId, releaseId) {
+    const preflight = await verifyExecutableRelease(options, catalogId, releaseId);
+    return admitExecutableRelease(options, preflight);
+}

package/dist/runtime/index.d.ts

@@ -1,4 +1,5 @@
 export type { ActionDispatchPermit } from "./action-permit.ts";
+export { admitCatalogRelease } from "./admission.ts";
 export { classifyOperation, type OperationClassification, } from "./classify.ts";
 export { digestCredentialAuthorizationBinding, snapshotCredentialAuthorizationBinding, } from "./credential-binding.ts";
 export { sha256, verifyEd25519 } from "./digest.ts";

package/dist/runtime/index.js

@@ -1,3 +1,4 @@
+export { admitCatalogRelease } from "./admission.js";
 export { classifyOperation, } from "./classify.js";
 export { digestCredentialAuthorizationBinding, snapshotCredentialAuthorizationBinding, } from "./credential-binding.js";
 export { sha256, verifyEd25519 } from "./digest.js";

package/dist/slice.d.ts

@@ -0,0 +1,14 @@
+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. */
+export interface SliceSelection {
+    readonly tags: readonly string[];
+    readonly operations: readonly string[];
+}
+/** 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,220 @@
+// 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",
+];
+/** 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.");
+    return {
+        ...document,
+        servers: [{ url: new URL(server).origin }],
+        paths,
+        components: prunedComponents,
+    };
+}
+/** 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.0.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Compile signed OpenAPI catalogs and serve verified search and authorized API calls over MCP.",
   "license": "MIT OR Apache-2.0",