@mcpmake/core 0.2.4 → 0.3.0

package/dist/utils/json-extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-extract.js","sourceRoot":"","sources":["../../src/utils/json-extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,SAAS,eAAe,CAAC,IAAY,EAAE,IAAY,EAAE,KAAa;IAChE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,OAAO;gBAAE,OAAO,GAAG,KAAK,CAAC;iBACxB,IAAI,EAAE,KAAK,IAAI;gBAAE,OAAO,GAAG,IAAI,CAAC;iBAChC,IAAI,EAAE,KAAK,GAAG;gBAAE,QAAQ,GAAG,KAAK,CAAC;QACxC,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACtB,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;aAAM,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YACvB,KAAK,EAAE,CAAC;QACV,CAAC;aAAM,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;YACxB,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAEnC,IAAI,QAAQ,KAAK,CAAC,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,kEAAkE;IAClE,MAAM,QAAQ,GAAG,QAAQ,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,IAAI,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAE7E,OAAO,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AACtF,CAAC"}

package/dist/utils/model-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/model-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAG/C;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAqB5C;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,SAAS,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAsCjB"}
+{"version":3,"file":"model-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/model-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAG/C;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAqB5C;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,SAAS,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CA4CjB"}

package/dist/utils/model-resolver.js

@@ -56,8 +56,14 @@ export async function resolveModel(client, tier, override) {
         }
     }
     catch (err) {
+        // Transient Models API failure: return the fallback for this call WITHOUT
+        // caching it, so a later call retries once the API recovers (a poisoned
+        // cache would pin the whole process to the fallback alias).
         logger.warn(`Could not list models (${err instanceof Error ? err.message : err}); using "${preferred}"`);
+        return preferred;
     }
+    // Only successful resolutions are cached — the served-model list rarely
+    // changes mid-run, so one API round-trip per tier is enough.
     cache.set(tier, choice);
     return choice;
 }

package/dist/utils/model-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-resolver.js","sourceRoot":"","sources":["../../src/utils/model-resolver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AASrC;;;;GAIG;AACH,MAAM,SAAS,GAA8B;IAC3C,QAAQ,EAAE,mBAAmB;IAC7B,IAAI,EAAE,kBAAkB;CACzB,CAAC;AAEF,MAAM,YAAY,GAA8B;IAC9C,QAAQ,EAAE,SAAS;IACnB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,2EAA2E;AAC3E,wEAAwE;AACxE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAiB,EACjB,IAAe,EACf,QAAiB;IAEjB,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,MAAM,GAAG,SAAS,CAAC;IAEvB,IAAI,CAAC;QACH,MAAM,MAAM,GAA+D,EAAE,CAAC;QAC9E,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;QACpF,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,EAAE,CAAC;YAC5C,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM;iBAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;gBAClE,yEAAyE;iBACxE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/D,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,IAAI,CAAC,oBAAoB,SAAS,yBAAyB,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;gBAChF,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CACT,oBAAoB,SAAS,wBAAwB,IAAI,gCAAgC,CAC1F,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CACT,0BAA0B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,aAAa,SAAS,GAAG,CAC5F,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"model-resolver.js","sourceRoot":"","sources":["../../src/utils/model-resolver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AASrC;;;;GAIG;AACH,MAAM,SAAS,GAA8B;IAC3C,QAAQ,EAAE,mBAAmB;IAC7B,IAAI,EAAE,kBAAkB;CACzB,CAAC;AAEF,MAAM,YAAY,GAA8B;IAC9C,QAAQ,EAAE,SAAS;IACnB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,2EAA2E;AAC3E,wEAAwE;AACxE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAiB,EACjB,IAAe,EACf,QAAiB;IAEjB,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,MAAM,GAAG,SAAS,CAAC;IAEvB,IAAI,CAAC;QACH,MAAM,MAAM,GAA+D,EAAE,CAAC;QAC9E,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;QACpF,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,EAAE,CAAC;YAC5C,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM;iBAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;gBAClE,yEAAyE;iBACxE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/D,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,IAAI,CAAC,oBAAoB,SAAS,yBAAyB,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;gBAChF,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CACT,oBAAoB,SAAS,wBAAwB,IAAI,gCAAgC,CAC1F,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0EAA0E;QAC1E,wEAAwE;QACxE,4DAA4D;QAC5D,MAAM,CAAC,IAAI,CACT,0BAA0B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,aAAa,SAAS,GAAG,CAC5F,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,wEAAwE;IACxE,6DAA6D;IAC7D,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/sanitize.d.ts

@@ -1,6 +1,6 @@
 /**
  * Sanitize a string for safe embedding in a JavaScript/TypeScript single-quoted string literal.
- * Escapes backslashes, single quotes, and newlines.
+ * Escapes backslashes, single quotes, and CR/LF.
  */
 export declare function escapeStringLiteral(str: string): string;
 /**
@@ -13,6 +13,68 @@ export declare function escapeTemplateLiteral(str: string): string;
  * Strips anything that isn't alphanumeric, underscore, or hyphen.
  */
 export declare function sanitizeIdentifier(str: string): string;
+/**
+ * Sanitize an HTTP header name (e.g. an apiKey scheme `name`) for safe embedding
+ * in a string literal. Real header names are RFC 7230 tokens; in practice API
+ * key headers are `[A-Za-z0-9-]` (plus `_`). Stripping everything else removes
+ * quotes/backticks/newlines that could break out of the generated literal.
+ */
+export declare function sanitizeHeaderName(str: string): string;
+/**
+ * Sanitize an environment-variable name. It is emitted both as a quoted string
+ * and as a bare member access (`process.env.<NAME>` / `env.<NAME>`), so it must
+ * be a valid JS/POSIX identifier. Strips invalid chars and prefixes `_` when the
+ * result would start with a digit or be empty.
+ */
+export declare function sanitizeEnvVarName(str: string): string;
+/**
+ * Resolve OpenAPI server-variable placeholders (`{var}`) in a server URL from
+ * their declared defaults, then validate the result is a real http(s) URL.
+ *
+ * OpenAPI server URLs may carry variables — `https://{region}.api.test/{version}`
+ * — with a `variables` map giving each a `default`. Substituting them here keeps
+ * the URL semantically intact instead of stripping the braces (which would corrupt
+ * the path, e.g. `{version}` → empty). Variables without a known default are left
+ * as-is; the subsequent per-sink escaper neutralizes any residual unsafe chars.
+ */
+export declare function resolveServerUrl(url: string, variables?: Record<string, {
+    default?: string;
+} | undefined>): string;
+/**
+ * Escape a base URL for safe embedding in a string literal across multiple
+ * target languages without mutating its semantics. Unlike a strip-based
+ * approach, this preserves every character that is legal in a URL (including
+ * `$`, `{`, `}`, `~`, etc. that appear in real paths such as `/v1/$metadata`)
+ * and only neutralizes the characters that could break out of, or inject into,
+ * the literal it is embedded in:
+ *   - backslash, single/double quote, backtick → backslash-escaped
+ *   - `${` (TS template-literal interpolation) → broken with a backslash
+ *   - CR/LF (could inject extra dotenv/TOML lines) → backslash-escaped
+ * The same escaped form is safe in a TS single/double-quote string, a TS
+ * backtick literal, a Python double-quote string, a TOML basic string, and a
+ * single-line dotenv value. Validation/variable-resolution happens upstream in
+ * the emitter via {@link resolveServerUrl}.
+ */
+export declare function sanitizeUrlLiteral(str: string): string;
+/**
+ * Validate a request-body media type against the RFC media-type grammar
+ * (`type/subtype`, optional parameters). The OpenAPI `content` map key is
+ * attacker-influenced and is interpolated into a string literal, so a value
+ * that is not a well-formed media type is replaced with `application/json`
+ * (the universal safe default) rather than trusted. The returned value is
+ * still escaped at the literal sink by {@link escapeStringLiteral}.
+ */
+export declare function sanitizeMediaType(str: string): string;
+/**
+ * Escape a string for safe embedding in a double-quoted Python string literal.
+ * Escapes backslashes, double quotes, and newlines.
+ */
+export declare function escapePyString(str: string): string;
+/**
+ * Convert an arbitrary parameter name into a valid, non-keyword Python
+ * identifier for use as a function argument or local variable name.
+ */
+export declare function sanitizePyIdentifier(str: string): string;
 /**
  * Validate that a URL path template contains only safe characters.
  * Allows: alphanumeric, /, {, }, -, _, .

package/dist/utils/sanitize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/utils/sanitize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKpD;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD"}
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/utils/sanitize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,GAC3D,MAAM,CAUR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAStD;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMlD;AA0CD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKpD;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/utils/sanitize.js

@@ -1,9 +1,13 @@
 /**
  * Sanitize a string for safe embedding in a JavaScript/TypeScript single-quoted string literal.
- * Escapes backslashes, single quotes, and newlines.
+ * Escapes backslashes, single quotes, and CR/LF.
  */
 export function escapeStringLiteral(str) {
-    return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n').replace(/\r/g, '');
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
 }
 /**
  * Sanitize a string for safe embedding in a JavaScript/TypeScript template literal.
@@ -19,6 +23,147 @@ export function escapeTemplateLiteral(str) {
 export function sanitizeIdentifier(str) {
     return str.replace(/[^a-zA-Z0-9_\-]/g, '');
 }
+/**
+ * Sanitize an HTTP header name (e.g. an apiKey scheme `name`) for safe embedding
+ * in a string literal. Real header names are RFC 7230 tokens; in practice API
+ * key headers are `[A-Za-z0-9-]` (plus `_`). Stripping everything else removes
+ * quotes/backticks/newlines that could break out of the generated literal.
+ */
+export function sanitizeHeaderName(str) {
+    return str.replace(/[^A-Za-z0-9_\-]/g, '');
+}
+/**
+ * Sanitize an environment-variable name. It is emitted both as a quoted string
+ * and as a bare member access (`process.env.<NAME>` / `env.<NAME>`), so it must
+ * be a valid JS/POSIX identifier. Strips invalid chars and prefixes `_` when the
+ * result would start with a digit or be empty.
+ */
+export function sanitizeEnvVarName(str) {
+    const cleaned = str.replace(/[^A-Za-z0-9_]/g, '');
+    return /^[A-Za-z_]/.test(cleaned) ? cleaned : `_${cleaned}`;
+}
+/**
+ * Resolve OpenAPI server-variable placeholders (`{var}`) in a server URL from
+ * their declared defaults, then validate the result is a real http(s) URL.
+ *
+ * OpenAPI server URLs may carry variables — `https://{region}.api.test/{version}`
+ * — with a `variables` map giving each a `default`. Substituting them here keeps
+ * the URL semantically intact instead of stripping the braces (which would corrupt
+ * the path, e.g. `{version}` → empty). Variables without a known default are left
+ * as-is; the subsequent per-sink escaper neutralizes any residual unsafe chars.
+ */
+export function resolveServerUrl(url, variables) {
+    if (!url)
+        return url;
+    let resolved = url;
+    if (variables) {
+        resolved = resolved.replace(/\{([^{}]+)\}/g, (match, name) => {
+            const def = variables[name]?.default;
+            return typeof def === 'string' ? def : match;
+        });
+    }
+    return resolved;
+}
+/**
+ * Escape a base URL for safe embedding in a string literal across multiple
+ * target languages without mutating its semantics. Unlike a strip-based
+ * approach, this preserves every character that is legal in a URL (including
+ * `$`, `{`, `}`, `~`, etc. that appear in real paths such as `/v1/$metadata`)
+ * and only neutralizes the characters that could break out of, or inject into,
+ * the literal it is embedded in:
+ *   - backslash, single/double quote, backtick → backslash-escaped
+ *   - `${` (TS template-literal interpolation) → broken with a backslash
+ *   - CR/LF (could inject extra dotenv/TOML lines) → backslash-escaped
+ * The same escaped form is safe in a TS single/double-quote string, a TS
+ * backtick literal, a Python double-quote string, a TOML basic string, and a
+ * single-line dotenv value. Validation/variable-resolution happens upstream in
+ * the emitter via {@link resolveServerUrl}.
+ */
+export function sanitizeUrlLiteral(str) {
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/`/g, '\\`')
+        .replace(/'/g, "\\'")
+        .replace(/"/g, '\\"')
+        .replace(/\$\{/g, '\\${')
+        .replace(/\r/g, '\\r')
+        .replace(/\n/g, '\\n');
+}
+/** RFC 6838 / RFC 7231 media-type token: `type/subtype` with optional params. */
+const MEDIA_TYPE_RE = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*(\s*;\s*[^\s;]+)*$/;
+/**
+ * Validate a request-body media type against the RFC media-type grammar
+ * (`type/subtype`, optional parameters). The OpenAPI `content` map key is
+ * attacker-influenced and is interpolated into a string literal, so a value
+ * that is not a well-formed media type is replaced with `application/json`
+ * (the universal safe default) rather than trusted. The returned value is
+ * still escaped at the literal sink by {@link escapeStringLiteral}.
+ */
+export function sanitizeMediaType(str) {
+    return MEDIA_TYPE_RE.test(str.trim()) ? str.trim() : 'application/json';
+}
+/**
+ * Escape a string for safe embedding in a double-quoted Python string literal.
+ * Escapes backslashes, double quotes, and newlines.
+ */
+export function escapePyString(str) {
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+}
+const PY_KEYWORDS = new Set([
+    'False',
+    'None',
+    'True',
+    'and',
+    'as',
+    'assert',
+    'async',
+    'await',
+    'break',
+    'class',
+    'continue',
+    'def',
+    'del',
+    'elif',
+    'else',
+    'except',
+    'finally',
+    'for',
+    'from',
+    'global',
+    'if',
+    'import',
+    'in',
+    'is',
+    'lambda',
+    'nonlocal',
+    'not',
+    'or',
+    'pass',
+    'raise',
+    'return',
+    'try',
+    'while',
+    'with',
+    'yield',
+    'match',
+    'case',
+]);
+/**
+ * Convert an arbitrary parameter name into a valid, non-keyword Python
+ * identifier for use as a function argument or local variable name.
+ */
+export function sanitizePyIdentifier(str) {
+    let id = str.replace(/[^A-Za-z0-9_]/g, '_');
+    if (!/^[A-Za-z_]/.test(id))
+        id = `_${id}`;
+    if (PY_KEYWORDS.has(id))
+        id = `${id}_`;
+    return id || '_param';
+}
 /**
  * Validate that a URL path template contains only safe characters.
  * Allows: alphanumeric, /, {, }, -, _, .

package/dist/utils/sanitize.js.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../src/utils/sanitize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAClG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAClF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,OAAO,GAAG,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,GAAG,CAAC,OAAO,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG;SACP,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;AAE1E;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../src/utils/sanitize.ts"],"names":[],"mappings":"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"}

package/dist/utils/ssrf-guard.d.ts

@@ -0,0 +1,10 @@
+export declare function privateHostsAllowed(): boolean;
+/** Whether `ip` (a literal IPv4 or IPv6 address) is private, loopback, or reserved. */
+export declare function isPrivateOrReservedIp(ip: string): boolean;
+/**
+ * Throw if `urlString` is not a public http(s) URL. Resolves the host via DNS and
+ * rejects when any resolved address is private/loopback/link-local/reserved.
+ * Honors the `MCPMAKE_ALLOW_PRIVATE_HOSTS` escape hatch.
+ */
+export declare function assertPublicUrl(urlString: string): Promise<void>;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/dist/utils/ssrf-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.d.ts","sourceRoot":"","sources":["../../src/utils/ssrf-guard.ts"],"names":[],"mappings":"AAyBA,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AA0CD,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CtE"}

package/dist/utils/ssrf-guard.js

@@ -0,0 +1,130 @@
+import { isIP } from 'node:net';
+import { lookup } from 'node:dns/promises';
+/**
+ * SSRF guard for outbound requests driven by untrusted input — crawled links,
+ * recorded navigations, and remote OpenAPI spec/`$ref` URLs.
+ *
+ * The browser crawler/recorder and the spec loader all fetch URLs that originate
+ * from user input or from an LLM/page following links. Without a host check they
+ * can be steered at `localhost`, RFC1918 intranets, or the cloud metadata
+ * endpoint (`169.254.169.254`). This module resolves a URL's host and rejects
+ * any that points at a private, loopback, link-local, or otherwise reserved
+ * address.
+ *
+ * Residual limitation (documented, not closed here): this checks at request time
+ * but does not pin DNS at the socket, so a TOCTOU/DNS-rebinding attacker who
+ * flips a record between this lookup and the browser's own connect can still slip
+ * through. Full DNS-pinning would require intercepting at the socket layer.
+ *
+ * Escape hatch: set `MCPMAKE_ALLOW_PRIVATE_HOSTS=1` to allow private/loopback
+ * targets (local development against `localhost` test servers).
+ */
+const ALLOW_ENV = 'MCPMAKE_ALLOW_PRIVATE_HOSTS';
+export function privateHostsAllowed() {
+    return process.env[ALLOW_ENV] === '1' || process.env[ALLOW_ENV] === 'true';
+}
+/** Parse a dotted-quad IPv4 string into its four octets, or null if malformed. */
+function ipv4Octets(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return null;
+    const nums = parts.map((p) => Number(p));
+    if (nums.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return null;
+    return nums;
+}
+function isPrivateIpv4(ip) {
+    const o = ipv4Octets(ip);
+    if (!o)
+        return false;
+    const [a, b] = o;
+    if (a === 0)
+        return true; // 0.0.0.0/8 "this network"
+    if (a === 10)
+        return true; // 10.0.0.0/8 private
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local (cloud metadata)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16 private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    if (a === 192 && b === 0 && o[2] === 0)
+        return true; // 192.0.0.0/24 IETF protocol
+    if (a >= 224)
+        return true; // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.* broadcast
+    return false;
+}
+function isPrivateIpv6(raw) {
+    const ip = raw.toLowerCase();
+    if (ip === '::1' || ip === '::')
+        return true; // loopback / unspecified
+    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible / NAT64 — re-check embedded v4.
+    const mapped = ip.match(/(?:::ffff:|::ffff:0:|64:ff9b::)(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        return isPrivateIpv4(mapped[1]);
+    if (ip.startsWith('fe8') || ip.startsWith('fe9') || ip.startsWith('fea') || ip.startsWith('feb'))
+        return true; // fe80::/10 link-local
+    if (ip.startsWith('fc') || ip.startsWith('fd'))
+        return true; // fc00::/7 unique-local
+    if (ip.startsWith('fec') || ip.startsWith('fed') || ip.startsWith('fee') || ip.startsWith('fef'))
+        return true; // fec0::/10 deprecated site-local
+    if (ip.startsWith('ff'))
+        return true; // ff00::/8 multicast
+    return false;
+}
+/** Whether `ip` (a literal IPv4 or IPv6 address) is private, loopback, or reserved. */
+export function isPrivateOrReservedIp(ip) {
+    const kind = isIP(ip);
+    if (kind === 4)
+        return isPrivateIpv4(ip);
+    if (kind === 6)
+        return isPrivateIpv6(ip);
+    return false; // not an IP literal
+}
+/**
+ * Throw if `urlString` is not a public http(s) URL. Resolves the host via DNS and
+ * rejects when any resolved address is private/loopback/link-local/reserved.
+ * Honors the `MCPMAKE_ALLOW_PRIVATE_HOSTS` escape hatch.
+ */
+export async function assertPublicUrl(urlString) {
+    let url;
+    try {
+        url = new URL(urlString);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${urlString}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`Refusing non-http(s) URL: ${urlString}`);
+    }
+    if (privateHostsAllowed())
+        return;
+    // Strip IPv6 brackets from the hostname for literal checks.
+    const host = url.hostname.replace(/^\[/, '').replace(/\]$/, '');
+    // Literal IP host — check directly, no DNS needed.
+    if (isIP(host)) {
+        if (isPrivateOrReservedIp(host)) {
+            throw new Error(`Refusing to access private/reserved address ${host} (set ${ALLOW_ENV}=1 to allow).`);
+        }
+        return;
+    }
+    // Hostname — resolve every address it maps to and reject if ANY is private.
+    let addresses;
+    try {
+        addresses = await lookup(host, { all: true });
+    }
+    catch {
+        throw new Error(`Cannot resolve host "${host}" to verify it is public; refusing request.`);
+    }
+    for (const { address } of addresses) {
+        if (isPrivateOrReservedIp(address)) {
+            throw new Error(`Refusing request: host "${host}" resolves to private/reserved address ${address} ` +
+                `(set ${ALLOW_ENV}=1 to allow).`);
+        }
+    }
+}
+//# sourceMappingURL=ssrf-guard.js.map

package/dist/utils/ssrf-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.js","sourceRoot":"","sources":["../../src/utils/ssrf-guard.ts"],"names":[],"mappings":"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"}

package/dist/utils/watcher.d.ts

@@ -4,9 +4,25 @@ export interface WatchOptions {
     onChange: () => Promise<void>;
     debounceMs?: number;
 }
+/**
+ * Debounce + coalesce change notifications into regeneration runs.
+ *
+ * - Rapid bursts before a run are debounced into one run.
+ * - A change that arrives *while* a run is in flight sets a single `pending`
+ *   flag, so exactly one trailing run fires afterwards. The flag (not a queue)
+ *   caps the backlog at one regardless of how many events land mid-run, which
+ *   avoids an unbounded backlog / memory growth.
+ *
+ * Exposed (and exported) separately from the fs binding so the coalescing logic
+ * is testable without relying on platform fs.watch event timing.
+ */
+export declare function createChangeHandler(onChange: () => Promise<void>, debounceMs: number): {
+    notify: () => void;
+};
 /**
  * Watch a file for changes and invoke a callback.
- * Debounces rapid successive changes (e.g., editor save + format).
+ * Debounces rapid successive changes (e.g., editor save + format) and coalesces
+ * changes that arrive during a regeneration into a single trailing run.
  */
 export declare function watchFile(options: WatchOptions): FSWatcher;
 //# sourceMappingURL=watcher.d.ts.map

package/dist/utils/watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/utils/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAGhD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CA4B1D"}
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/utils/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAGhD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB;IAAE,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,CAmCxB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAa1D"}

package/dist/utils/watcher.js

@@ -1,34 +1,66 @@
 import { watch } from 'node:fs';
 import { logger } from './logger.js';
+/**
+ * Debounce + coalesce change notifications into regeneration runs.
+ *
+ * - Rapid bursts before a run are debounced into one run.
+ * - A change that arrives *while* a run is in flight sets a single `pending`
+ *   flag, so exactly one trailing run fires afterwards. The flag (not a queue)
+ *   caps the backlog at one regardless of how many events land mid-run, which
+ *   avoids an unbounded backlog / memory growth.
+ *
+ * Exposed (and exported) separately from the fs binding so the coalescing logic
+ * is testable without relying on platform fs.watch event timing.
+ */
+export function createChangeHandler(onChange, debounceMs) {
+    let timer;
+    let running = false;
+    let pending = false;
+    async function regenerate() {
+        running = true;
+        try {
+            do {
+                pending = false;
+                logger.info('Spec file changed, regenerating...');
+                try {
+                    await onChange();
+                    logger.success('Regeneration complete');
+                }
+                catch (err) {
+                    logger.error(`Regeneration failed: ${err instanceof Error ? err.message : err}`);
+                }
+            } while (pending);
+        }
+        finally {
+            running = false;
+        }
+    }
+    return {
+        notify() {
+            if (running) {
+                pending = true;
+                return;
+            }
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                void regenerate();
+            }, debounceMs);
+        },
+    };
+}
 /**
  * Watch a file for changes and invoke a callback.
- * Debounces rapid successive changes (e.g., editor save + format).
+ * Debounces rapid successive changes (e.g., editor save + format) and coalesces
+ * changes that arrive during a regeneration into a single trailing run.
  */
 export function watchFile(options) {
     const debounceMs = options.debounceMs ?? 500;
-    let timer;
-    let running = false;
+    const handler = createChangeHandler(options.onChange, debounceMs);
     const watcher = watch(options.filePath, (eventType) => {
         if (eventType !== 'change')
             return;
-        if (running)
-            return;
-        if (timer)
-            clearTimeout(timer);
-        timer = setTimeout(async () => {
-            running = true;
-            logger.info('Spec file changed, regenerating...');
-            try {
-                await options.onChange();
-                logger.success('Regeneration complete');
-            }
-            catch (err) {
-                logger.error(`Regeneration failed: ${err instanceof Error ? err.message : err}`);
-            }
-            finally {
-                running = false;
-            }
-        }, debounceMs);
+        handler.notify();
     });
     logger.info(`Watching for changes: ${options.filePath}`);
     logger.info('Press Ctrl+C to stop');

package/dist/utils/watcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/utils/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAkB,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAQrC;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,OAAqB;IAC7C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;IAC7C,IAAI,KAAgD,CAAC;IACrD,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,EAAE;QACpD,IAAI,SAAS,KAAK,QAAQ;YAAE,OAAO;QACnC,IAAI,OAAO;YAAE,OAAO;QAEpB,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE;YAC5B,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;YAClD,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACzB,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC;YAC1C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,KAAK,CAAC,wBAAwB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;YACnF,CAAC;oBAAS,CAAC;gBACT,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,CAAC,yBAAyB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACzD,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAEpC,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/utils/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAkB,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAQrC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAA6B,EAC7B,UAAkB;IAElB,IAAI,KAAgD,CAAC;IACrD,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,KAAK,UAAU,UAAU;QACvB,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,CAAC;YACH,GAAG,CAAC;gBACF,OAAO,GAAG,KAAK,CAAC;gBAChB,MAAM,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;gBAClD,IAAI,CAAC;oBACH,MAAM,QAAQ,EAAE,CAAC;oBACjB,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC;gBAC1C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,CAAC,KAAK,CAAC,wBAAwB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;gBACnF,CAAC;YACH,CAAC,QAAQ,OAAO,EAAE;QACpB,CAAC;gBAAS,CAAC;YACT,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO;QACL,MAAM;YACJ,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO;YACT,CAAC;YACD,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,KAAK,UAAU,EAAE,CAAC;YACpB,CAAC,EAAE,UAAU,CAAC,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAqB;IAC7C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;IAC7C,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAElE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,EAAE;QACpD,IAAI,SAAS,KAAK,QAAQ;YAAE,OAAO;QACnC,OAAO,CAAC,MAAM,EAAE,CAAC;IACnB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,CAAC,yBAAyB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACzD,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAEpC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpmake/core",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Shared generation library for mcpmake — parse APIs (OpenAPI/HAR/Postman/websites) and emit MCP servers.",
   "type": "module",
   "license": "Apache-2.0",
@@ -35,6 +35,7 @@
     "handlebars": "^4.7.8",
     "json-schema-to-zod": "^2.4.1",
     "marked": "^12.0.2",
+    "openai": "^6.44.0",
     "openapi-types": "^12.1.3",
     "playwright": "^1.59.1",
     "yaml": "^2.7.0"