@squadrules/mcp 4.8.6

package/dist/utils/tenant-context.js

@@ -0,0 +1,247 @@
+/**
+ * Space and tenant context for multitenancy.
+ * SpaceContext is derived from Keycloak (sub + groups); getTenantId() remains for metrics.
+ * AsyncLocalStorage allows Redis and other services to get current space without request reference.
+ * When AUTH_ENABLED, default space is disabled for strict isolation; unauthenticated/no-context
+ * uses a sentinel space so no tenant data is shared.
+ */
+import { AsyncLocalStorage } from 'async_hooks';
+import { v5 as uuidv5 } from 'uuid';
+import { AUTH_ENABLED, KAIROS_APP_SPACE_ID, KAIROS_SIMPLE_PERSONAL_REALM, KAIROS_SIMPLE_PERSONAL_SPACE_ID, KAIROS_SIMPLE_PERSONAL_UUIDV5_SEED } from '../config.js';
+import { resolveSpaceParamForContext } from './resolve-space-param.js';
+/** Sentinel space when AUTH is on but no auth context (strict isolation; not shared with tenants). */
+export const NO_AUTH_SPACE_ID = 'space:no-auth';
+/** Sentinel for "no context" when restoring after runWithSpaceContextAsync (enterWith does not accept undefined). */
+const NO_CONTEXT_SENTINEL = {
+    userId: '',
+    groupIds: [],
+    allowedSpaceIds: [],
+    defaultWriteSpaceId: '',
+    personalSpaceId: '',
+    spaceNamesById: {},
+    requestId: ''
+};
+const spaceStorage = new AsyncLocalStorage();
+function defaultSpaceContext() {
+    const personalSpaceId = defaultPersonalSpaceIdForNoAuth();
+    const appSpaceId = KAIROS_APP_SPACE_ID;
+    return {
+        userId: '',
+        groupIds: [],
+        allowedSpaceIds: [personalSpaceId, appSpaceId],
+        defaultWriteSpaceId: personalSpaceId,
+        personalSpaceId: personalSpaceId,
+        spaceNamesById: { [personalSpaceId]: 'Personal', [appSpaceId]: 'Kairos app' },
+        requestId: ''
+    };
+}
+/** Context when AUTH_ENABLED and no auth/storage — no access to shared default space. */
+function noDefaultSpaceContext() {
+    return {
+        userId: '',
+        groupIds: [],
+        allowedSpaceIds: [],
+        defaultWriteSpaceId: NO_AUTH_SPACE_ID,
+        personalSpaceId: '',
+        spaceNamesById: {},
+        requestId: ''
+    };
+}
+/**
+ * Run a function with the given space context stored in AsyncLocalStorage.
+ * Used by HTTP auth middleware so Redis and Qdrant helpers can read space without request.
+ * For sync callbacks the context is preserved. For async callbacks use runWithSpaceContextAsync
+ * so the context persists across await boundaries (run() loses context after the callback returns a Promise).
+ */
+export function runWithSpaceContext(ctx, fn) {
+    return spaceStorage.run(ctx, fn);
+}
+/**
+ * Run an async function with the given space context. Uses enterWith so the context
+ * persists for the entire async execution (including all await continuations).
+ * Use this when the callback does async work (e.g. storeChain) and getSpaceContext()
+ * must see the context inside that work.
+ */
+export async function runWithSpaceContextAsync(ctx, fn) {
+    const prev = spaceStorage.getStore();
+    spaceStorage.enterWith(ctx);
+    try {
+        return await fn();
+    }
+    finally {
+        spaceStorage.enterWith(prev ?? NO_CONTEXT_SENTINEL);
+    }
+}
+/**
+ * Get space context from AsyncLocalStorage (set by auth middleware via runWithSpaceContext).
+ * When not in a request: if AUTH_ENABLED, returns no-default context (strict isolation);
+ * otherwise returns default single-tenant context.
+ */
+export function getSpaceContextFromStorage() {
+    const stored = spaceStorage.getStore();
+    if (stored && stored !== NO_CONTEXT_SENTINEL)
+        return stored;
+    return AUTH_ENABLED ? noDefaultSpaceContext() : defaultSpaceContext();
+}
+/** Current space id for Redis key prefix and similar; uses storage or KAIROS_APP_SPACE_ID when auth off. */
+export function getSpaceIdFromStorage() {
+    return getSpaceContextFromStorage().defaultWriteSpaceId;
+}
+/** Correlation id propagated through AsyncLocalStorage for forensic tracing. */
+export function getRequestIdFromStorage() {
+    const requestId = getSpaceContextFromStorage().requestId;
+    return requestId && requestId.trim().length > 0 ? requestId : 'no-request-id';
+}
+/**
+ * Space IDs to use for search only: allowedSpaceIds plus Kairos app space (deduped).
+ * Writes (train, tune, delete) continue to use allowedSpaceIds only.
+ */
+export function getSearchSpaceIds() {
+    const ctx = getSpaceContextFromStorage();
+    const scope = ctx.activateSpaceScope;
+    if (scope && scope.length > 0) {
+        return [...scope];
+    }
+    const allowed = ctx.allowedSpaceIds;
+    if (allowed.includes(KAIROS_APP_SPACE_ID))
+        return [...allowed];
+    return [...allowed, KAIROS_APP_SPACE_ID];
+}
+/**
+ * Async variant: run fn in narrowed space context so context persists across await.
+ * Use when the callback does async work (for example search) and getSpaceContext() must see the context.
+ */
+export async function runWithOptionalSpaceAsync(spaceParam, fn) {
+    if (!spaceParam || typeof spaceParam !== 'string')
+        return fn();
+    const trimmed = spaceParam.trim();
+    if (!trimmed)
+        return fn();
+    const ctx = getSpaceContextFromStorage();
+    const searchableBeforeNarrow = getSearchSpaceIds();
+    const resolved = resolveSpaceParamForContext(ctx, trimmed, { allowReadOnlyAppSearchScope: true });
+    if (!resolved.ok) {
+        throw new Error(resolved.message);
+    }
+    const spaceId = resolved.spaceId;
+    if (!searchableBeforeNarrow.includes(spaceId)) {
+        throw new Error('Requested space is not in your allowed spaces');
+    }
+    const readOnlyAppScope = spaceId === KAIROS_APP_SPACE_ID;
+    const narrowed = {
+        ...ctx,
+        allowedSpaceIds: [spaceId],
+        defaultWriteSpaceId: readOnlyAppScope ? ctx.defaultWriteSpaceId : spaceId,
+        personalSpaceId: ctx.personalSpaceId,
+        activateSpaceScope: [spaceId]
+    };
+    return runWithSpaceContextAsync(narrowed, fn);
+}
+/**
+ * Build allowed spaces from JWT-derived auth (`sub`, `groups`, `realm`, `iss`).
+ * - Personal id: `user:{realm}:{uuidv5(iss + "\\nuser\\n" + sub)}`
+ * - Group id: `group:{realm}:{uuidv5(iss + "\\ngroup\\n" + fullPath)}`
+ * Group names shown by tools/UI are canonical Keycloak full paths from the token.
+ */
+const SPACE_ID_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';
+function normalizeRealmSlug(realm) {
+    const raw = (realm || '').trim().toLowerCase();
+    const slug = raw.replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return slug || 'default';
+}
+function normalizeIssuer(iss, realm) {
+    const trimmed = (iss || '').trim();
+    if (!trimmed)
+        return `realm:${realm}`;
+    return trimmed.replace(/\/+$/, '');
+}
+function defaultPersonalSpaceIdForNoAuth() {
+    if (KAIROS_SIMPLE_PERSONAL_UUIDV5_SEED.length > 0) {
+        const realmSlug = normalizeRealmSlug(KAIROS_SIMPLE_PERSONAL_REALM);
+        const personalUuid = uuidv5(KAIROS_SIMPLE_PERSONAL_UUIDV5_SEED, SPACE_ID_NAMESPACE);
+        return `user:${realmSlug}:${personalUuid}`;
+    }
+    return KAIROS_SIMPLE_PERSONAL_SPACE_ID;
+}
+function normalizeGroupFullPath(value) {
+    const t = (value || '').trim();
+    if (!t)
+        return '';
+    const withLeading = t.startsWith('/') ? t : `/${t}`;
+    return withLeading.replace(/\/+/g, '/');
+}
+function fromAuthPayload(sub, groupNames, realm, iss) {
+    const realmSlug = normalizeRealmSlug(realm);
+    const issuerKey = normalizeIssuer(iss, realmSlug);
+    const personalUuid = uuidv5(`${issuerKey}\nuser\n${sub}`, SPACE_ID_NAMESPACE);
+    const personal = `user:${realmSlug}:${personalUuid}`;
+    const groupSpaces = [];
+    const spaceNamesById = { [personal]: 'Personal' };
+    const seen = new Set();
+    for (const rawPath of groupNames) {
+        const fullPath = normalizeGroupFullPath(rawPath);
+        if (!fullPath)
+            continue;
+        const groupUuid = uuidv5(`${issuerKey}\ngroup\n${fullPath}`, SPACE_ID_NAMESPACE);
+        const sid = `group:${realmSlug}:${groupUuid}`;
+        if (seen.has(sid))
+            continue;
+        seen.add(sid);
+        groupSpaces.push(sid);
+        spaceNamesById[sid] = fullPath;
+    }
+    const allowedSpaceIds = [personal, ...groupSpaces];
+    const defaultWriteSpaceId = personal;
+    return { allowedSpaceIds, defaultWriteSpaceId, spaceNamesById, personalSpaceId: personal };
+}
+/**
+ * Get space context from request. Uses req.auth (set by auth middleware) when AUTH_ENABLED.
+ * When AUTH_ENABLED and no auth, returns no-default context (strict isolation).
+ * When AUTH_ENABLED=false, returns default single-tenant context.
+ * If no request is passed, falls back to AsyncLocalStorage (e.g. from runWithSpaceContext).
+ */
+export function getSpaceContext(request) {
+    if (request?.spaceContext)
+        return request.spaceContext;
+    const stored = spaceStorage.getStore();
+    if (stored && stored !== NO_CONTEXT_SENTINEL)
+        return stored;
+    const requestId = typeof request?.requestId === 'string'
+        ? request.requestId
+        : typeof request?.headers?.['x-request-id'] === 'string'
+            ? request.headers['x-request-id']
+            : '';
+    if (!AUTH_ENABLED)
+        return { ...defaultSpaceContext(), requestId };
+    const auth = request?.auth;
+    if (!auth?.sub)
+        return { ...noDefaultSpaceContext(), requestId };
+    const realm = auth.realm ?? 'default';
+    const iss = auth.iss ?? `realm:${realm}`;
+    const { allowedSpaceIds, defaultWriteSpaceId, spaceNamesById, personalSpaceId } = fromAuthPayload(auth.sub, auth.groups ?? [], realm, iss);
+    return {
+        userId: auth.sub,
+        groupIds: auth.groups ?? [],
+        allowedSpaceIds,
+        defaultWriteSpaceId,
+        personalSpaceId,
+        spaceNamesById,
+        requestId
+    };
+}
+/**
+ * Persist request-derived space context across async HTTP route handlers.
+ * Auth middleware sets `req.spaceContext` using synchronous `spaceStorage.run`, which does not
+ * keep AsyncLocalStorage active after the handler awaits; wrap the tool body with this helper.
+ */
+export async function runHttpApiWithSpaceContext(request, fn) {
+    return runWithSpaceContextAsync(getSpaceContext(request), fn);
+}
+/**
+ * Get tenant ID for metrics. Returns default write space id or first allowed space.
+ */
+export function getTenantId(request) {
+    const ctx = getSpaceContext(request);
+    return ctx.defaultWriteSpaceId || ctx.allowedSpaceIds[0] || 'default';
+}
+//# sourceMappingURL=tenant-context.js.map

package/dist/utils/tenant-context.js.map

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

package/dist/utils/uri-builder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * URI Builder for KAIROS Resources
+ *
+ * Generates canonical kairos:// URIs for:
+ * - Domain/type/task resources: kairos://{domain}/{type}/{task}
+ * - Protocol steps: kairos://{domain}/{type}/{task}/step/{n}
+ * - Unified UUID resources: kairos://{uuid}
+ * - Templates: kairos://templates/{template_type}/{param}
+ */
+/**
+ * Build kairos://{domain}/{type}/{task} URI for domain/type/task format
+ *
+ * @param domain - Knowledge domain (e.g., 'typescript', 'docker')
+ * @param type - Knowledge type (e.g., 'rule', 'pattern', 'context')
+ * @param task - Task identifier (e.g., 'error-handling', 'networking')
+ * @returns kairos:// domain/type/task URI
+ *
+ * @example
+ * buildDomainTypeTaskURI('docker', 'pattern', 'networking')
+ * // Returns: 'kairos://docker/pattern/networking'
+ */
+export declare function buildDomainTypeTaskURI(domain: string, type: string, task: string): string;
+/**
+ * Build kairos://{domain}/{type}/{task}/step/{step} URI for protocol steps
+ *
+ * @param domain - Knowledge domain
+ * @param type - Knowledge type
+ * @param task - Task identifier
+ * @param step - Step number (1-based)
+ * @returns kairos:// protocol step URI
+ *
+ * @example
+ * buildProtocolStepURI('ai', 'rule', 'coding-rules', 3)
+ * // Returns: 'kairos://ai/rule/coding-rules/step/3'
+ */
+export declare function buildProtocolStepURI(domain: string, type: string, task: string, step: number): string;
+//# sourceMappingURL=uri-builder.d.ts.map

package/dist/utils/uri-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-builder.d.ts","sourceRoot":"","sources":["../../src/utils/uri-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAYzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBrG"}

package/dist/utils/uri-builder.js

@@ -0,0 +1,60 @@
+/**
+ * URI Builder for KAIROS Resources
+ *
+ * Generates canonical kairos:// URIs for:
+ * - Domain/type/task resources: kairos://{domain}/{type}/{task}
+ * - Protocol steps: kairos://{domain}/{type}/{task}/step/{n}
+ * - Unified UUID resources: kairos://{uuid}
+ * - Templates: kairos://templates/{template_type}/{param}
+ */
+/**
+ * Build kairos://{domain}/{type}/{task} URI for domain/type/task format
+ *
+ * @param domain - Knowledge domain (e.g., 'typescript', 'docker')
+ * @param type - Knowledge type (e.g., 'rule', 'pattern', 'context')
+ * @param task - Task identifier (e.g., 'error-handling', 'networking')
+ * @returns kairos:// domain/type/task URI
+ *
+ * @example
+ * buildDomainTypeTaskURI('docker', 'pattern', 'networking')
+ * // Returns: 'kairos://docker/pattern/networking'
+ */
+export function buildDomainTypeTaskURI(domain, type, task) {
+    if (!domain || !type || !task) {
+        throw new Error('buildDomainTypeTaskURI requires domain, type, and task parameters');
+    }
+    // Validate domain/type/task format (lowercase, alphanumeric, hyphens)
+    const validFormat = /^[a-z0-9-]+$/;
+    if (!validFormat.test(domain) || !validFormat.test(type) || !validFormat.test(task)) {
+        throw new Error('Domain, type, and task must be lowercase alphanumeric with hyphens only');
+    }
+    return `kairos://${domain}/${type}/${task}`;
+}
+/**
+ * Build kairos://{domain}/{type}/{task}/step/{step} URI for protocol steps
+ *
+ * @param domain - Knowledge domain
+ * @param type - Knowledge type
+ * @param task - Task identifier
+ * @param step - Step number (1-based)
+ * @returns kairos:// protocol step URI
+ *
+ * @example
+ * buildProtocolStepURI('ai', 'rule', 'coding-rules', 3)
+ * // Returns: 'kairos://ai/rule/coding-rules/step/3'
+ */
+export function buildProtocolStepURI(domain, type, task, step) {
+    if (!domain || !type || !task || step === undefined || step === null) {
+        throw new Error('buildProtocolStepURI requires domain, type, task, and step parameters');
+    }
+    if (!Number.isInteger(step) || step < 1) {
+        throw new Error('Step must be a positive integer');
+    }
+    // Validate domain/type/task format
+    const validFormat = /^[a-z0-9-]+$/;
+    if (!validFormat.test(domain) || !validFormat.test(type) || !validFormat.test(task)) {
+        throw new Error('Domain, type, and task must be lowercase alphanumeric with hyphens only');
+    }
+    return `kairos://${domain}/${type}/${task}/step/${step}`;
+}
+//# sourceMappingURL=uri-builder.js.map

package/dist/utils/uri-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-builder.js","sourceRoot":"","sources":["../../src/utils/uri-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,IAAY,EAAE,IAAY;IAC7E,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACzF,CAAC;IAED,sEAAsE;IACtE,MAAM,WAAW,GAAG,cAAc,CAAC;IACnC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC/F,CAAC;IAED,OAAO,YAAY,MAAM,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,IAAY,EAAE,IAAY,EAAE,IAAY;IACzF,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC7F,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACvD,CAAC;IAED,mCAAmC;IACnC,MAAM,WAAW,GAAG,cAAc,CAAC;IACnC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC/F,CAAC;IAED,OAAO,YAAY,MAAM,IAAI,IAAI,IAAI,IAAI,SAAS,IAAI,EAAE,CAAC;AAC7D,CAAC"}

package/dist/utils/version-compare.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compare two semver strings (major.minor.patch).
+ * Returns:  1 if a > b, -1 if a < b, 0 if equal.
+ *
+ * Handles incomplete versions gracefully:
+ *  - Missing parts are treated as 0 (e.g. "4.7" → [4,7,0]).
+ *  - Non-numeric or empty strings are treated as [0,0,0].
+ */
+export declare function compareSemver(a: string | undefined | null, b: string | undefined | null): number;
+//# sourceMappingURL=version-compare.d.ts.map

package/dist/utils/version-compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compare.d.ts","sourceRoot":"","sources":["../../src/utils/version-compare.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAWhG"}

package/dist/utils/version-compare.js

@@ -0,0 +1,31 @@
+/**
+ * Compare two semver strings (major.minor.patch).
+ * Returns:  1 if a > b, -1 if a < b, 0 if equal.
+ *
+ * Handles incomplete versions gracefully:
+ *  - Missing parts are treated as 0 (e.g. "4.7" → [4,7,0]).
+ *  - Non-numeric or empty strings are treated as [0,0,0].
+ */
+export function compareSemver(a, b) {
+    const pa = parseParts(a);
+    const pb = parseParts(b);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const va = pa[i] ?? 0;
+        const vb = pb[i] ?? 0;
+        if (va > vb)
+            return 1;
+        if (va < vb)
+            return -1;
+    }
+    return 0;
+}
+function parseParts(v) {
+    if (!v)
+        return [0, 0, 0];
+    return v.split('.').map(s => {
+        const n = parseInt(s, 10);
+        return Number.isFinite(n) ? n : 0;
+    });
+}
+//# sourceMappingURL=version-compare.js.map

package/dist/utils/version-compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compare.js","sourceRoot":"","sources":["../../src/utils/version-compare.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,CAA4B,EAAE,CAA4B;IACtF,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,CAAC;QACtB,IAAI,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,UAAU,CAAC,CAA4B;IAC9C,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzB,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QAC1B,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1B,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/zod-to-jsonschema.d.ts

@@ -0,0 +1,4 @@
+import type { z } from 'zod';
+export declare function zodToInputJsonSchema(schema: z.ZodTypeAny): Record<string, unknown>;
+export declare function zodToOutputJsonSchema(schema: z.ZodTypeAny): Record<string, unknown>;
+//# sourceMappingURL=zod-to-jsonschema.d.ts.map

package/dist/utils/zod-to-jsonschema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-jsonschema.d.ts","sourceRoot":"","sources":["../../src/utils/zod-to-jsonschema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAO7B,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOlF;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOnF"}

package/dist/utils/zod-to-jsonschema.js

@@ -0,0 +1,25 @@
+import { normalizeObjectSchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
+const EMPTY_OBJECT_JSON_SCHEMA = {
+    type: 'object',
+    properties: {}
+};
+export function zodToInputJsonSchema(schema) {
+    const obj = normalizeObjectSchema(schema);
+    if (!obj)
+        return EMPTY_OBJECT_JSON_SCHEMA;
+    return toJsonSchemaCompat(obj, {
+        strictUnions: true,
+        pipeStrategy: 'input'
+    });
+}
+export function zodToOutputJsonSchema(schema) {
+    const obj = normalizeObjectSchema(schema);
+    if (!obj)
+        return EMPTY_OBJECT_JSON_SCHEMA;
+    return toJsonSchemaCompat(obj, {
+        strictUnions: true,
+        pipeStrategy: 'output'
+    });
+}
+//# sourceMappingURL=zod-to-jsonschema.js.map

package/dist/utils/zod-to-jsonschema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-jsonschema.js","sourceRoot":"","sources":["../../src/utils/zod-to-jsonschema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAGhG,MAAM,wBAAwB,GAA4B;IACxD,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,EAAE;CACf,CAAC;AAEF,MAAM,UAAU,oBAAoB,CAAC,MAAoB;IACvD,MAAM,GAAG,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,GAAG;QAAE,OAAO,wBAAwB,CAAC;IAC1C,OAAO,kBAAkB,CAAC,GAAG,EAAE;QAC7B,YAAY,EAAE,IAAI;QAClB,YAAY,EAAE,OAAO;KACtB,CAA4B,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAoB;IACxD,MAAM,GAAG,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,GAAG;QAAE,OAAO,wBAAwB,CAAC;IAC1C,OAAO,kBAAkB,CAAC,GAAG,EAAE;QAC7B,YAAY,EAAE,IAAI;QAClB,YAAY,EAAE,QAAQ;KACvB,CAA4B,CAAC;AAChC,CAAC"}