@knitli/openapi-mcp 1.2.0 → 1.2.1

package/README.md

@@ -117,6 +117,13 @@ 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

@@ -15,7 +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>]
+  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>
@@ -214,6 +214,7 @@ if (command === "slice") {
             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" },
         },
@@ -231,6 +232,7 @@ if (command === "slice") {
         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;

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

@@ -1,10 +1,18 @@
 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. */
+/** 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. */

package/dist/slice.js

@@ -16,6 +16,31 @@ export const HTTP_METHODS = [
     "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))
@@ -193,12 +218,14 @@ export function sliceSpec(document, selection) {
     const server = document.servers?.[0]?.url;
     if (!server)
         throw new Error("The document names no server.");
-    return {
+    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. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@knitli/openapi-mcp",
   "private": false,
-  "version": "1.2.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",