@zackbart/connecta 0.8.0 → 0.9.0

package/src/auth/downstream-oauth.ts

@@ -1,9 +1,10 @@
-import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 import type {
+  OAuthClientInformationContext,
   OAuthClientInformationMixed,
   OAuthClientMetadata,
+  OAuthClientProvider,
   OAuthTokens,
-} from "@modelcontextprotocol/sdk/shared/auth.js";
+} from "@modelcontextprotocol/client";
 import type { KVStorage } from "../types.js";
 
 /** A 256-bit random opaque value, hex-encoded — used for the OAuth `state`. */
@@ -25,7 +26,7 @@ const LEGACY_GENERATION = "legacy";
 const ACTIVE_GENERATION_PREFIX = "v2:";
 const RESETTING_GENERATION_PREFIX = "reset:";
 const DISCONNECTED_GENERATION_PREFIX = "disconnected:";
-const STORED_VALUE_VERSION = 1;
+const STORED_VALUE_VERSION = 2;
 const OAUTH_VALUE_KEYS = [
   "oauth:client",
   "oauth:tokens",
@@ -38,6 +39,13 @@ const MAX_CLEANUP_BACKLOG = 1_000;
 interface StoredOAuthValue<T> {
   connectaOAuthVersion: typeof STORED_VALUE_VERSION;
   generation: string;
+  issuer?: string;
+  value: T;
+}
+
+interface LegacyStoredOAuthValue<T> {
+  connectaOAuthVersion: 1;
+  generation: string;
   value: T;
 }
 
@@ -49,6 +57,19 @@ function storedOAuthValue<T>(
   return (
     candidate.connectaOAuthVersion === STORED_VALUE_VERSION &&
     typeof candidate.generation === "string" &&
+    (candidate.issuer === undefined || typeof candidate.issuer === "string") &&
+    "value" in candidate
+  );
+}
+
+function legacyStoredOAuthValue<T>(
+  value: unknown,
+): value is LegacyStoredOAuthValue<T> {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<LegacyStoredOAuthValue<T>>;
+  return (
+    candidate.connectaOAuthVersion === 1 &&
+    typeof candidate.generation === "string" &&
     "value" in candidate
   );
 }
@@ -132,6 +153,7 @@ export class KvOAuthProvider implements OAuthClientProvider {
     key: string,
     value: T,
     serializeLegacy: (value: T) => string,
+    issuer?: string,
   ): Promise<void> {
     const generation = await this.writeGeneration();
     if (
@@ -144,12 +166,13 @@ export class KvOAuthProvider implements OAuthClientProvider {
     const stored: StoredOAuthValue<T> = {
       connectaOAuthVersion: STORED_VALUE_VERSION,
       generation,
+      ...(issuer !== undefined ? { issuer } : {}),
       value,
     };
     const physicalKey = oauthValueStorageKey(key, generation);
     await this.storage.set(
       physicalKey,
-      isModernGeneration(generation)
+      isModernGeneration(generation) || issuer !== undefined
         ? JSON.stringify(stored)
         : serializeLegacy(value),
     );
@@ -182,7 +205,9 @@ export class KvOAuthProvider implements OAuthClientProvider {
   private async readValue<T>(
     key: string,
     parseLegacy: (raw: string) => T,
-  ): Promise<{ value: T; generation: string } | undefined> {
+  ): Promise<
+    { value: T; generation: string; issuer?: string } | undefined
+  > {
     const generation = await this.generation();
     const raw = await this.storage.get(
       oauthValueStorageKey(key, generation),
@@ -202,6 +227,15 @@ export class KvOAuthProvider implements OAuthClientProvider {
       // Raw string state from a pre-envelope deployment is handled below.
     }
     if (storedOAuthValue<T>(parsed)) {
+      return parsed.generation === generation
+        ? {
+            value: parsed.value,
+            generation,
+            ...(parsed.issuer !== undefined ? { issuer: parsed.issuer } : {}),
+          }
+        : undefined;
+    }
+    if (legacyStoredOAuthValue<T>(parsed)) {
       return parsed.generation === generation
         ? { value: parsed.value, generation }
         : undefined;
@@ -210,6 +244,40 @@ export class KvOAuthProvider implements OAuthClientProvider {
     return { value: parseLegacy(raw), generation };
   }
 
+  /**
+   * Read credentials only for the authorization server that issued them.
+   *
+   * Values written before issuer binding are bound on their first read with a
+   * validated SDK issuer, preserving an existing grant across this upgrade.
+   * A later issuer change is different: publish a new generation before
+   * returning no credentials, so every isolate drops the old registration and
+   * token set and the SDK starts authorization from scratch.
+   */
+  private async readIssuerBoundValue<T>(
+    key: "oauth:client" | "oauth:tokens",
+    parseLegacy: (raw: string) => T,
+    serializeLegacy: (value: T) => string,
+    ctx?: OAuthClientInformationContext,
+  ): Promise<T | undefined> {
+    const stored = await this.readValue(key, parseLegacy);
+    if (!stored || !ctx) return stored?.value;
+    if (stored.issuer === undefined) {
+      await this.writeValue(key, stored.value, serializeLegacy, ctx.issuer);
+      return stored.value;
+    }
+    if (stored.issuer === ctx.issuer) return stored.value;
+
+    try {
+      await this.resetAuthorization();
+    } finally {
+      // The issuer-aware flow may continue after the reset. Stamp any later
+      // writes into the replacement epoch; the connector's generation check
+      // still discards this connection attempt before caching it.
+      this.captureGeneration(await this.generation());
+    }
+    return undefined;
+  }
+
   /** Attempt every key deletion, then report the first backend failure. */
   private async deleteAll(keys: readonly string[]): Promise<void> {
     let firstError: unknown;
@@ -276,35 +344,49 @@ export class KvOAuthProvider implements OAuthClientProvider {
     };
   }
 
-  async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
-    return (
-      await this.readValue(
-        "oauth:client",
-        (raw) => JSON.parse(raw) as OAuthClientInformationMixed,
-      )
-    )?.value;
+  async clientInformation(
+    ctx?: OAuthClientInformationContext,
+  ): Promise<OAuthClientInformationMixed | undefined> {
+    return this.readIssuerBoundValue(
+      "oauth:client",
+      (raw) => JSON.parse(raw) as OAuthClientInformationMixed,
+      (value) => JSON.stringify(value),
+      ctx,
+    );
   }
 
   async saveClientInformation(
     info: OAuthClientInformationMixed,
+    ctx?: OAuthClientInformationContext,
   ): Promise<void> {
-    await this.writeValue("oauth:client", info, (value) =>
-      JSON.stringify(value),
+    await this.writeValue(
+      "oauth:client",
+      info,
+      (value) => JSON.stringify(value),
+      ctx?.issuer,
     );
   }
 
-  async tokens(): Promise<OAuthTokens | undefined> {
-    return (
-      await this.readValue(
-        "oauth:tokens",
-        (raw) => JSON.parse(raw) as OAuthTokens,
-      )
-    )?.value;
+  async tokens(
+    ctx?: OAuthClientInformationContext,
+  ): Promise<OAuthTokens | undefined> {
+    return this.readIssuerBoundValue(
+      "oauth:tokens",
+      (raw) => JSON.parse(raw) as OAuthTokens,
+      (value) => JSON.stringify(value),
+      ctx,
+    );
   }
 
-  async saveTokens(tokens: OAuthTokens): Promise<void> {
-    await this.writeValue("oauth:tokens", tokens, (value) =>
-      JSON.stringify(value),
+  async saveTokens(
+    tokens: OAuthTokens,
+    ctx?: OAuthClientInformationContext,
+  ): Promise<void> {
+    await this.writeValue(
+      "oauth:tokens",
+      tokens,
+      (value) => JSON.stringify(value),
+      ctx?.issuer,
     );
   }
 

package/src/call-admission.ts

@@ -459,7 +459,6 @@ export class ConnectorCallAdmissionController {
 
   private evictIdlePartitions(now: number): void {
     for (const [key, state] of this.partitions) {
-      this.pruneBudget(state, now);
       this.maybeDeletePartition(key, state, now);
     }
   }

package/src/catalog-service.ts

@@ -1,4 +1,9 @@
-import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
+import {
+  compactSchema,
+  lexicalSearchQuery,
+  rankTools,
+  summarizeDescription,
+} from "./catalog.js";
 import {
   mapSettledWithConcurrency,
   resolveDiscoveryConcurrency,
@@ -20,10 +25,11 @@ import {
 } from "./timeout.js";
 import type {
   Connector,
+  JsonSchema,
   ToolDef,
 } from "./types.js";
 
-const DEFAULT_SEARCH_LIMIT = 25;
+export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
 export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
@@ -76,7 +82,7 @@ function discoveryAddresses(value: unknown): unknown[] {
 
 /** Serialize once and count the exact bytes the MCP adapter would emit. */
 export function boundedDiscoveryText(value: unknown, hint: string): string {
-  const text = JSON.stringify(value, null, 2);
+  const text = JSON.stringify(value);
   if (text === undefined) {
     throw new TypeError("Discovery result is not JSON-serializable.");
   }
@@ -90,14 +96,6 @@ export function boundedDiscoveryText(value: unknown, hint: string): string {
   return text;
 }
 
-/** Apply the same final UTF-8 boundary where only the check is needed. */
-export function assertDiscoveryResultSize(
-  value: unknown,
-  hint: string,
-): void {
-  boundedDiscoveryText(value, hint);
-}
-
 export interface CatalogSearchArgs {
   query?: string;
   connector?: string;
@@ -172,6 +170,10 @@ function framingError(code: string, message: string): CallErrorDetails {
   return { code, message, retryable: messageLooksRetryable(message) };
 }
 
+function renderSchema(schema: JsonSchema, format: "compact" | "json"): unknown {
+  return format === "json" ? schema : compactSchema(schema);
+}
+
 /**
  * Request-local catalog operations shared by MCP meta-tools and code mode.
  * Successful catalogs may be reused inside this request; failures are not
@@ -365,6 +367,7 @@ export class CatalogService {
 
   async search(args: CatalogSearchArgs): Promise<CatalogSearchPage> {
     const query = args.query ?? "";
+    const retrievalQuery = lexicalSearchQuery(query);
     const limit = discoverySearchLimit(args.limit);
     const offset = Math.max(0, Math.trunc(args.offset ?? 0));
     const connectors = args.connector
@@ -397,7 +400,11 @@ export class CatalogService {
           throw new Error("Catalog result has no corresponding connector");
         }
         if (catalog.status === "fulfilled") {
-          for (const ranked of rankTools(catalog.value, query, mode)) {
+          for (const ranked of rankTools(
+            catalog.value,
+            retrievalQuery,
+            mode,
+          )) {
             matches.push({
               connector,
               tool: ranked.tool,
@@ -434,17 +441,13 @@ export class CatalogService {
           ...(args.includeSchemas
             ? {
                 inputSchema:
-                  args.includeSchemas === "json"
-                    ? input
-                    : compactSchema(input),
+                  renderSchema(input, args.includeSchemas),
               }
             : {}),
           ...(args.includeSchemas && match.tool.outputSchema
             ? {
                 outputSchema:
-                  args.includeSchemas === "json"
-                    ? match.tool.outputSchema
-                    : compactSchema(match.tool.outputSchema),
+                  renderSchema(match.tool.outputSchema, args.includeSchemas),
               }
             : {}),
           ...(match.tool.annotations
@@ -534,13 +537,10 @@ export class CatalogService {
         ...(connectorGuide(addressResolution.connector)
           ? { guide: connectorSkillName(addressResolution.connector.id) }
           : {}),
-        inputSchema: format === "json" ? input : compactSchema(input),
+        inputSchema: renderSchema(input, format),
         ...(tool.outputSchema
           ? {
-              outputSchema:
-                format === "json"
-                  ? tool.outputSchema
-                  : compactSchema(tool.outputSchema),
+              outputSchema: renderSchema(tool.outputSchema, format),
             }
           : {}),
         ...(tool.annotations ? { annotations: tool.annotations } : {}),

package/src/catalog.ts

@@ -17,6 +17,61 @@ function normalized(text: string): string {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
 }
 
+/**
+ * Conversational framing selected by the #188 research run before the #189
+ * holdout existed. Action-bearing terms such as get/list/search/find/create
+ * deliberately remain: arbitrary connector catalogs need those distinctions.
+ */
+const CONVERSATIONAL_QUERY_WORDS = new Set([
+  "a",
+  "all",
+  "an",
+  "and",
+  "are",
+  "can",
+  "could",
+  "current",
+  "for",
+  "from",
+  "i",
+  "in",
+  "into",
+  "it",
+  "latest",
+  "let",
+  "me",
+  "most",
+  "of",
+  "on",
+  "our",
+  "please",
+  "right",
+  "show",
+  "that",
+  "the",
+  "this",
+  "to",
+  "up",
+  "want",
+  "when",
+  "which",
+  "with",
+  "you",
+]);
+
+/**
+ * Remove conversational framing before the all-term/partial decision. If
+ * every term is framing, retain the original query rather than turning a
+ * search into an unfiltered catalog browse.
+ */
+export function lexicalSearchQuery(query: string): string {
+  const terms = normalized(query).split(/\s+/).filter(Boolean);
+  const contentTerms = terms.filter(
+    (term) => !CONVERSATIONAL_QUERY_WORDS.has(term),
+  );
+  return contentTerms.length > 0 ? contentTerms.join(" ") : query;
+}
+
 interface SearchDocument {
   tool: ToolDef;
   name: string;