@zackbart/connecta 0.1.0

package/dist/auth/clerk.js

@@ -0,0 +1,167 @@
+// Clerk as the OAuth 2.1 authorization server; connecta is the resource server.
+// Single tenant, no tenant-tag requirement, optional gate() with ~60s identity
+// caching.
+import { createClerkClient } from "@clerk/backend";
+const CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, mcp-protocol-version",
+};
+/** Coarse bearer shape for diagnostics — never the token itself. */
+function tokenShape(request) {
+    const header = request.headers.get("authorization");
+    if (!header)
+        return "none";
+    const token = header.replace(/^Bearer\s+/i, "");
+    if (token.startsWith("oat_"))
+        return "oauth-opaque";
+    if (token.startsWith("eyJ"))
+        return "jwt";
+    return "other";
+}
+/** Clerk Frontend API origin, derived from pk_(test|live)_<b64 domain>. */
+function fapiUrl(publishableKey) {
+    const key = publishableKey.replace(/^pk_(test|live)_/, "");
+    const decoded = atob(key).replace(/\$$/, "");
+    return `https://${decoded}`;
+}
+const GATE_ALLOWED_TTL_MS = 60 * 1000;
+const GATE_FORBIDDEN_TTL_MS = 30 * 1000;
+export function clerkAuth(opts) {
+    const clerk = createClerkClient({
+        secretKey: opts.secretKey,
+        publishableKey: opts.publishableKey,
+    });
+    const scopes = opts.scopes ?? ["openid", "profile", "email"];
+    const gateCache = new Map();
+    const resolveBase = (baseUrl) => opts.publicUrl ?? baseUrl;
+    const unauthorized = (baseUrl, tokenPresent) => {
+        const error = tokenPresent ? `error="invalid_token", ` : "";
+        const meta = `${resolveBase(baseUrl)}/.well-known/oauth-protected-resource`;
+        return new Response(JSON.stringify({ error: "unauthorized" }), {
+            status: 401,
+            headers: {
+                "Content-Type": "application/json",
+                "WWW-Authenticate": `Bearer ${error}resource_metadata="${meta}"`,
+            },
+        });
+    };
+    const forbidden = () => new Response(JSON.stringify({ error: "forbidden" }), { status: 403, headers: { "Content-Type": "application/json" } });
+    const checkGate = async (userId) => {
+        if (!opts.gate)
+            return true;
+        const hit = gateCache.get(userId);
+        if (hit && Date.now() < hit.exp)
+            return hit.allowed;
+        let allowed = false;
+        try {
+            allowed = await opts.gate(userId, clerk);
+        }
+        catch {
+            allowed = false;
+        }
+        gateCache.set(userId, {
+            allowed,
+            exp: Date.now() +
+                (allowed ? GATE_ALLOWED_TTL_MS : GATE_FORBIDDEN_TTL_MS),
+        });
+        return allowed;
+    };
+    return {
+        kind: "clerk",
+        uiAuth: {
+            kind: "clerk",
+            publishableKey: opts.publishableKey,
+            frontendApiUrl: fapiUrl(opts.publishableKey),
+            ...(opts.signInUrl ? { signInUrl: opts.signInUrl } : {}),
+            ...(opts.signUpUrl ? { signUpUrl: opts.signUpUrl } : {}),
+        },
+        async handleMetadata(request, baseUrl) {
+            const { pathname } = new URL(request.url);
+            if (!pathname.startsWith("/.well-known/"))
+                return null;
+            if (request.method === "OPTIONS") {
+                return new Response(null, { status: 204, headers: CORS_HEADERS });
+            }
+            const base = resolveBase(baseUrl);
+            if (pathname === "/.well-known/oauth-protected-resource" ||
+                pathname === "/.well-known/oauth-protected-resource/mcp") {
+                return Response.json({
+                    resource: `${base}/mcp`,
+                    authorization_servers: [fapiUrl(opts.publishableKey)],
+                    bearer_methods_supported: ["header"],
+                    scopes_supported: scopes,
+                }, { headers: CORS_HEADERS });
+            }
+            if (pathname === "/.well-known/oauth-authorization-server") {
+                try {
+                    const upstream = await fetch(`${fapiUrl(opts.publishableKey)}/.well-known/oauth-authorization-server`);
+                    if (!upstream.ok) {
+                        return Response.json({ error: "upstream authorization server metadata unavailable" }, { status: 502, headers: CORS_HEADERS });
+                    }
+                    return Response.json(await upstream.json(), { headers: CORS_HEADERS });
+                }
+                catch {
+                    return Response.json({ error: "upstream authorization server metadata unavailable" }, { status: 502, headers: CORS_HEADERS });
+                }
+            }
+            return null;
+        },
+        async authorize(request, baseUrl) {
+            const tokenPresent = Boolean(request.headers.get("authorization"));
+            let userId;
+            try {
+                const state = await clerk.authenticateRequest(request, {
+                    // MCP clients use Clerk OAuth access tokens; the browser dashboard
+                    // uses the signed-in operator's short-lived Clerk session token.
+                    // authorizedParties must NOT be passed here: OAuth access tokens may
+                    // be JWTs without an azp claim, and Clerk rejects azp=undefined when
+                    // that option is set. The sibling-subdomain pin it provided is
+                    // enforced below, only for session tokens that actually carry azp.
+                    acceptsToken: ["oauth_token", "session_token"],
+                });
+                const auth = state.toAuth();
+                if (!auth?.isAuthenticated) {
+                    // Reason (not the token) in the logs: bearer rejections are
+                    // otherwise indistinguishable 401s in `wrangler tail`.
+                    const detail = state;
+                    console.warn(`[connecta] clerk rejected request: status=${state.status}` +
+                        ` reason=${detail.reason ?? "?"} message=${detail.message ?? ""}` +
+                        ` tokenShape=${tokenShape(request)}`);
+                    return {
+                        ok: false,
+                        response: unauthorized(baseUrl, tokenPresent),
+                    };
+                }
+                // Session JWTs carry `azp` (the origin they were minted for); pin it
+                // to this connecta deployment so a sibling subdomain's cookie/token
+                // cannot be replayed here. OAuth access tokens may have no azp.
+                const typed = auth;
+                if (typed.tokenType === "session_token") {
+                    const azp = typed.sessionClaims?.azp;
+                    const origin = new URL(resolveBase(baseUrl)).origin;
+                    if (azp && azp !== origin) {
+                        console.warn(`[connecta] session token azp mismatch: azp=${azp} expected=${origin}`);
+                        return {
+                            ok: false,
+                            response: unauthorized(baseUrl, tokenPresent),
+                        };
+                    }
+                }
+                userId = typed.userId ?? undefined;
+            }
+            catch (error) {
+                console.warn(`[connecta] clerk authenticateRequest threw: ${error instanceof Error ? error.message : String(error)} tokenShape=${tokenShape(request)}`);
+                return { ok: false, response: unauthorized(baseUrl, true) };
+            }
+            if (!userId) {
+                return { ok: false, response: unauthorized(baseUrl, true) };
+            }
+            if (!(await checkGate(userId))) {
+                return { ok: false, response: forbidden() };
+            }
+            return { ok: true, userId };
+        },
+    };
+}
+//# sourceMappingURL=clerk.js.map

package/dist/auth/clerk.js.map

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

package/dist/auth/downstream-oauth.d.ts

@@ -0,0 +1,78 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { KVStorage } from "../types.js";
+/**
+ * OAuthClientProvider implemented over KVStorage for a single downstream
+ * connector. Keys live in the connector's namespace as `oauth:<field>`.
+ *
+ * Headless twist: redirectToAuthorization() cannot navigate a user agent, so it
+ * STORES the authorization URL; the registry surfaces it as status
+ * "auth_required" and the operator opens it. The /oauth/callback/<id> route then
+ * drives transport.finishAuth(code).
+ */
+export declare class KvOAuthProvider implements OAuthClientProvider {
+    private readonly connectorId;
+    private readonly storage;
+    private readonly redirectUri;
+    /**
+     * The force-reauth generation this provider's flow started under, captured by
+     * the connector before it drives a connect. `null` until stamped — a provider
+     * used outside a connect flow (or in isolation) writes unconditionally.
+     */
+    private capturedGeneration;
+    constructor(connectorId: string, storage: KVStorage, redirectUri: string);
+    /**
+     * Stamp the force-reauth generation the current connect flow started under.
+     * Subsequent saveTokens/saveClientInformation writes are dropped if KV's
+     * generation has since advanced (a concurrent force wiped credentials) — see
+     * isStale(). Called by the connector once per connect, before c.connect().
+     */
+    captureGeneration(gen: number): void;
+    /**
+     * Whether a concurrent force re-auth advanced the KV generation past the one
+     * this flow captured. When true, this isolate's SDK is mid-flight against
+     * credentials that were just wiped — persisting them would resurrect the
+     * wiped-and-reauthorized connector for later isolates. Fails open (writes)
+     * when no generation was captured.
+     */
+    private isStale;
+    get redirectUrl(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(info: OAuthClientInformationMixed): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    /**
+     * OAuth `state`. The SDK calls this (when present) and appends the value to
+     * the authorization URL. We generate a fresh random value and persist it so
+     * the public /oauth/callback route can prove the callback belongs to a flow
+     * WE started. Without it, anyone holding a pending authorization URL could
+     * complete consent with their own account (login CSRF) — PKCE does not help,
+     * since the verifier belongs to connecta, not the attacker. Cleared in
+     * clearPending() once the flow completes.
+     */
+    state(): Promise<string>;
+    /**
+     * Constant-time check of a callback's `state` against the stored one-shot
+     * value. Absent stored state or absent candidate → false (fail closed).
+     */
+    verifyState(candidate: string | null): Promise<boolean>;
+    saveCodeVerifier(verifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    /** The stored authorization URL, if a flow is pending. */
+    pendingAuthorizationUrl(): Promise<string | undefined>;
+    /** Clear one-shot flow state after the callback completes. */
+    clearPending(): Promise<void>;
+    /**
+     * Force-reauth generation. Monotonic counter shared across isolates via KV;
+     * NOT cleared by clearPending/invalidateCredentials — its whole job is to
+     * keep advancing so an isolate holding a client from a prior generation can
+     * notice it went stale. Defaults to 0 when never bumped.
+     */
+    generation(): Promise<number>;
+    /** Advance the generation (on force re-auth) and return the new value. */
+    bumpGeneration(): Promise<number>;
+    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void>;
+}
+//# sourceMappingURL=downstream-oauth.d.ts.map

package/dist/auth/downstream-oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downstream-oauth.d.ts","sourceRoot":"","sources":["../../src/auth/downstream-oauth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,KAAK,EACV,2BAA2B,EAC3B,mBAAmB,EACnB,WAAW,EACZ,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAiB7C;;;;;;;;GAQG;AACH,qBAAa,eAAgB,YAAW,mBAAmB;IASvD,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAV9B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAAuB;gBAG9B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,EAClB,WAAW,EAAE,MAAM;IAGtC;;;;;OAKG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIpC;;;;;;OAMG;YACW,OAAO;IAKrB,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,cAAc,IAAI,mBAAmB,CAQxC;IAEK,iBAAiB,IAAI,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC;IAKrE,qBAAqB,CACzB,IAAI,EAAE,2BAA2B,GAChC,OAAO,CAAC,IAAI,CAAC;IASV,MAAM,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAK1C,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAepD;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAM9B;;;OAGG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAMvD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAM/B,uBAAuB,CAAC,gBAAgB,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,0DAA0D;IACpD,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAI5D,8DAA8D;IACxD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAMnC,0EAA0E;IACpE,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAMjC,qBAAqB,CACzB,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAC5D,OAAO,CAAC,IAAI,CAAC;CAWjB"}

package/dist/auth/downstream-oauth.js

@@ -0,0 +1,180 @@
+/** A 256-bit random opaque value, hex-encoded — used for the OAuth `state`. */
+function randomState() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Length-safe, constant-time string compare (no early-exit on first mismatch). */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * OAuthClientProvider implemented over KVStorage for a single downstream
+ * connector. Keys live in the connector's namespace as `oauth:<field>`.
+ *
+ * Headless twist: redirectToAuthorization() cannot navigate a user agent, so it
+ * STORES the authorization URL; the registry surfaces it as status
+ * "auth_required" and the operator opens it. The /oauth/callback/<id> route then
+ * drives transport.finishAuth(code).
+ */
+export class KvOAuthProvider {
+    connectorId;
+    storage;
+    redirectUri;
+    /**
+     * The force-reauth generation this provider's flow started under, captured by
+     * the connector before it drives a connect. `null` until stamped — a provider
+     * used outside a connect flow (or in isolation) writes unconditionally.
+     */
+    capturedGeneration = null;
+    constructor(connectorId, storage, redirectUri) {
+        this.connectorId = connectorId;
+        this.storage = storage;
+        this.redirectUri = redirectUri;
+    }
+    /**
+     * Stamp the force-reauth generation the current connect flow started under.
+     * Subsequent saveTokens/saveClientInformation writes are dropped if KV's
+     * generation has since advanced (a concurrent force wiped credentials) — see
+     * isStale(). Called by the connector once per connect, before c.connect().
+     */
+    captureGeneration(gen) {
+        this.capturedGeneration = gen;
+    }
+    /**
+     * Whether a concurrent force re-auth advanced the KV generation past the one
+     * this flow captured. When true, this isolate's SDK is mid-flight against
+     * credentials that were just wiped — persisting them would resurrect the
+     * wiped-and-reauthorized connector for later isolates. Fails open (writes)
+     * when no generation was captured.
+     */
+    async isStale() {
+        if (this.capturedGeneration === null)
+            return false;
+        return (await this.generation()) > this.capturedGeneration;
+    }
+    get redirectUrl() {
+        return this.redirectUri;
+    }
+    get clientMetadata() {
+        return {
+            redirect_uris: [this.redirectUri],
+            client_name: "connecta",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        };
+    }
+    async clientInformation() {
+        const raw = await this.storage.get("oauth:client");
+        return raw ? JSON.parse(raw) : undefined;
+    }
+    async saveClientInformation(info) {
+        // A concurrent force wiped credentials and bumped the generation while this
+        // flow ran — skip rather than re-register a client under revoked state. The
+        // in-memory SDK keeps this info for the current (doomed) connect, which the
+        // connector's post-connect fence then discards.
+        if (await this.isStale())
+            return;
+        await this.storage.set("oauth:client", JSON.stringify(info));
+    }
+    async tokens() {
+        const raw = await this.storage.get("oauth:tokens");
+        return raw ? JSON.parse(raw) : undefined;
+    }
+    async saveTokens(tokens) {
+        // Generation-guarded write. The dangerous case: an isolate mid-connect (or
+        // mid-refresh) whose SDK just minted fresh tokens against a still-valid
+        // grant, racing a force re-auth that wiped KV and bumped the generation.
+        // Persisting here would resurrect those tokens for later isolates to read.
+        // A silent skip (not a throw) is deliberate: throwing propagates out of the
+        // SDK's auth() and fails the in-flight request/connect noisily, whereas
+        // skipping lets the in-memory client finish its current operation while
+        // leaving KV wiped — the connector's generation check drops that client on
+        // its next call. Fails open when no generation was captured, so ordinary
+        // token refresh (no force) still persists.
+        if (await this.isStale())
+            return;
+        await this.storage.set("oauth:tokens", JSON.stringify(tokens));
+    }
+    /**
+     * OAuth `state`. The SDK calls this (when present) and appends the value to
+     * the authorization URL. We generate a fresh random value and persist it so
+     * the public /oauth/callback route can prove the callback belongs to a flow
+     * WE started. Without it, anyone holding a pending authorization URL could
+     * complete consent with their own account (login CSRF) — PKCE does not help,
+     * since the verifier belongs to connecta, not the attacker. Cleared in
+     * clearPending() once the flow completes.
+     */
+    async state() {
+        const value = randomState();
+        await this.storage.set("oauth:state", value);
+        return value;
+    }
+    /**
+     * Constant-time check of a callback's `state` against the stored one-shot
+     * value. Absent stored state or absent candidate → false (fail closed).
+     */
+    async verifyState(candidate) {
+        const expected = await this.storage.get("oauth:state");
+        if (!expected || candidate === null)
+            return false;
+        return timingSafeEqual(candidate, expected);
+    }
+    async saveCodeVerifier(verifier) {
+        await this.storage.set("oauth:verifier", verifier);
+    }
+    async codeVerifier() {
+        const raw = await this.storage.get("oauth:verifier");
+        if (!raw)
+            throw new Error(`No PKCE code verifier for "${this.connectorId}"`);
+        return raw;
+    }
+    async redirectToAuthorization(authorizationUrl) {
+        await this.storage.set("oauth:pending", authorizationUrl.toString());
+    }
+    /** The stored authorization URL, if a flow is pending. */
+    async pendingAuthorizationUrl() {
+        return (await this.storage.get("oauth:pending")) ?? undefined;
+    }
+    /** Clear one-shot flow state after the callback completes. */
+    async clearPending() {
+        await this.storage.delete("oauth:pending");
+        await this.storage.delete("oauth:verifier");
+        await this.storage.delete("oauth:state");
+    }
+    /**
+     * Force-reauth generation. Monotonic counter shared across isolates via KV;
+     * NOT cleared by clearPending/invalidateCredentials — its whole job is to
+     * keep advancing so an isolate holding a client from a prior generation can
+     * notice it went stale. Defaults to 0 when never bumped.
+     */
+    async generation() {
+        const raw = await this.storage.get("oauth:generation");
+        const n = raw ? Number(raw) : 0;
+        return Number.isFinite(n) ? n : 0;
+    }
+    /** Advance the generation (on force re-auth) and return the new value. */
+    async bumpGeneration() {
+        const next = (await this.generation()) + 1;
+        await this.storage.set("oauth:generation", String(next));
+        return next;
+    }
+    async invalidateCredentials(scope) {
+        if (scope === "all" || scope === "client") {
+            await this.storage.delete("oauth:client");
+        }
+        if (scope === "all" || scope === "tokens") {
+            await this.storage.delete("oauth:tokens");
+        }
+        if (scope === "all" || scope === "verifier") {
+            await this.storage.delete("oauth:verifier");
+        }
+    }
+}
+//# sourceMappingURL=downstream-oauth.js.map

package/dist/auth/downstream-oauth.js.map

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

package/dist/catalog.d.ts

@@ -0,0 +1,11 @@
+import type { JsonSchema, ToolDef } from "./types.js";
+export declare function summarizeDescription(text: string | undefined, full: boolean): string | undefined;
+/** Rank a connector's tools while caching its normalized plain-data index. */
+export declare function rankTools(tools: ToolDef[], query: string): Array<{
+    tool: ToolDef;
+    score: number;
+    order: number;
+}>;
+/** Render and cache a compact TypeScript-like representation of JSON Schema. */
+export declare function compactSchema(schema: JsonSchema): string;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAItD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,OAAO,GACZ,MAAM,GAAG,SAAS,CAMpB;AAiDD,8EAA8E;AAC9E,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EAAE,EAChB,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CASxD;AA0ED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAexD"}

package/dist/catalog.js

@@ -0,0 +1,144 @@
+const DEFAULT_DESCRIPTION_LENGTH = 240;
+export function summarizeDescription(text, full) {
+    if (!text)
+        return undefined;
+    if (full)
+        return text;
+    const compact = text.replace(/\s+/g, " ").trim();
+    if (compact.length <= DEFAULT_DESCRIPTION_LENGTH)
+        return compact;
+    return `${compact.slice(0, DEFAULT_DESCRIPTION_LENGTH - 1).trimEnd()}…`;
+}
+function normalized(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+const searchDocuments = new WeakMap();
+function documentsFor(tools) {
+    let docs = searchDocuments.get(tools);
+    if (!docs) {
+        docs = tools.map((tool) => ({
+            tool,
+            name: normalized(tool.name),
+            description: normalized(tool.description ?? ""),
+        }));
+        searchDocuments.set(tools, docs);
+    }
+    return docs;
+}
+function scoreDocument(doc, phrase, terms) {
+    if (!phrase)
+        return 0;
+    const haystack = `${doc.name} ${doc.description}`;
+    if (!terms.every((term) => haystack.includes(term)))
+        return null;
+    let score = 0;
+    if (doc.name === phrase)
+        score += 1_000;
+    else if (doc.name.startsWith(phrase))
+        score += 800;
+    else if (doc.name.includes(phrase))
+        score += 600;
+    for (const term of terms) {
+        if (doc.name === term)
+            score += 200;
+        else if (doc.name.startsWith(term))
+            score += 120;
+        else if (doc.name.includes(term))
+            score += 80;
+        if (doc.description.includes(term))
+            score += 10;
+    }
+    return score;
+}
+/** Rank a connector's tools while caching its normalized plain-data index. */
+export function rankTools(tools, query) {
+    const phrase = normalized(query);
+    const terms = phrase.split(/\s+/).filter(Boolean);
+    const ranked = [];
+    documentsFor(tools).forEach((doc, order) => {
+        const score = scoreDocument(doc, phrase, terms);
+        if (score !== null)
+            ranked.push({ tool: doc.tool, score, order });
+    });
+    return ranked;
+}
+function refName(ref) {
+    return ref.split("/").pop() ?? ref;
+}
+function renderSchema(schema, defs, seen, depth) {
+    if (depth > 4)
+        return "…";
+    if (schema === null || typeof schema !== "object") {
+        return JSON.stringify(schema);
+    }
+    const s = schema;
+    if (typeof s.$ref === "string") {
+        const name = refName(s.$ref);
+        if (seen.has(name))
+            return name;
+        const target = defs[name];
+        if (target === undefined)
+            return name;
+        seen.add(name);
+        const rendered = renderSchema(target, defs, seen, depth);
+        seen.delete(name);
+        return rendered;
+    }
+    const union = (s.oneOf ?? s.anyOf);
+    if (Array.isArray(union)) {
+        return (union.map((u) => renderSchema(u, defs, seen, depth + 1)).join(" | ") ||
+            "unknown");
+    }
+    if (Array.isArray(s.enum)) {
+        return s.enum.map((value) => JSON.stringify(value)).join(" | ");
+    }
+    const type = s.type;
+    if (type === "array" || s.items) {
+        const items = s.items
+            ? renderSchema(s.items, defs, seen, depth + 1)
+            : "unknown";
+        return `${items}[]`;
+    }
+    if (type === "object" || s.properties) {
+        const props = (s.properties ?? {});
+        const required = new Set((Array.isArray(s.required) ? s.required : []));
+        const keys = Object.keys(props);
+        if (keys.length === 0)
+            return "{}";
+        return `{ ${keys
+            .map((key) => {
+            const optional = required.has(key) ? "" : "?";
+            const rendered = renderSchema(props[key], defs, seen, depth + 1);
+            const description = props[key]?.description;
+            const comment = typeof description === "string" ? ` // ${description}` : "";
+            return `${key}${optional}: ${rendered}${comment}`;
+        })
+            .join(", ")} }`;
+    }
+    if (typeof type === "string")
+        return type;
+    if (Array.isArray(type))
+        return type.join(" | ");
+    return JSON.stringify(schema);
+}
+const compactSchemas = new WeakMap();
+/** Render and cache a compact TypeScript-like representation of JSON Schema. */
+export function compactSchema(schema) {
+    const cached = compactSchemas.get(schema);
+    if (cached)
+        return cached;
+    const defs = {
+        ...(schema.$defs ?? {}),
+        ...(schema.definitions ?? {}),
+    };
+    let rendered;
+    try {
+        rendered = renderSchema(schema, defs, new Set(), 0);
+    }
+    catch {
+        rendered = JSON.stringify(schema);
+    }
+    compactSchemas.set(schema, rendered);
+    return rendered;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

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