@zackbart/connecta 0.10.1 → 0.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
@@ -11,6 +11,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "connecta": "./bin/connecta.mjs"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zackbart/connecta.git"
@@ -26,9 +29,16 @@
     "connectors"
   ],
   "files": [
+    "bin",
     "dist",
     "src",
     "assets",
+    "documentation",
+    "examples/node",
+    "examples/worker",
+    "templates",
+    "AGENTS.md",
+    "ethos.md",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",

package/src/catalog-service.ts

@@ -1,9 +1,12 @@
 import {
+  compactDiscoverySchema,
   compactSchema,
   lexicalCorpusStatistics,
+  lexicalQueryTerms,
   lexicalSearchQuery,
   rankTools,
   schemaObjectKeys,
+  summarizeDiscoveryDescription,
   summarizeDescription,
 } from "./catalog.js";
 import {
@@ -25,6 +28,7 @@ import {
   normalizeTimeoutMs,
   withAbortableTimeout,
 } from "./timeout.js";
+import { isExplicitlyReadOnly } from "./tool-safety.js";
 import type {
   Connector,
   JsonSchema,
@@ -35,6 +39,8 @@ 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;
+const MAX_QUERY_ANALYSIS_TERMS = 8;
+const MAX_QUERY_ANALYSIS_TERM_LENGTH = 64;
 
 const encoder = new TextEncoder();
 
@@ -101,6 +107,11 @@ export function boundedDiscoveryText(value: unknown, hint: string): string {
 export interface CatalogSearchArgs {
   query?: string;
   connector?: string;
+  /**
+   * Result classification only; never changes which tools exist or what may
+   * execute. Omitted and "all" preserve the complete configured catalog.
+   */
+  safety?: "readOnly" | "approvalRequired" | "all";
   limit?: number;
   offset?: number;
   fullDescriptions?: boolean;
@@ -109,6 +120,35 @@ export interface CatalogSearchArgs {
   includeSchemaKeys?: boolean;
 }
 
+function discoverySafety(
+  value: unknown,
+): "readOnly" | "approvalRequired" | "all" {
+  if (value === undefined) return "all";
+  if (
+    value !== "readOnly" &&
+    value !== "approvalRequired" &&
+    value !== "all"
+  ) {
+    throw new DiscoveryPolicyError(
+      "invalid_args",
+      'safety must be "readOnly", "approvalRequired", or "all".',
+    );
+  }
+  return value;
+}
+
+function toolsForSafety(
+  tools: ToolDef[],
+  safety: "readOnly" | "approvalRequired" | "all",
+): ToolDef[] {
+  if (safety === "all") return tools;
+  return tools.filter((tool) =>
+    safety === "readOnly"
+      ? isExplicitlyReadOnly(tool)
+      : !isExplicitlyReadOnly(tool),
+  );
+}
+
 export interface CatalogDescribeArgs {
   addresses?: unknown;
   format?: "compact" | "json";
@@ -124,6 +164,8 @@ interface CatalogSearchEntry {
     description?: string;
     inputSchema?: unknown;
     outputSchema?: unknown;
+    inputSchemaTruncated?: true;
+    outputSchemaTruncated?: true;
     inputKeys?: string[];
     requiredInputKeys?: string[];
     outputKeys?: string[];
@@ -165,6 +207,16 @@ export interface CatalogSearchPage {
   hasMore: boolean;
   nextOffset?: number;
   matchMode?: "partial";
+  queryAnalysis?: {
+    representedTerms: string[];
+    otherResultTerms: string[];
+    unmatchedTerms: string[];
+    truncated?: true;
+    connectorScope?: string;
+    unknownConnector?: true;
+    unavailableConnectorCount?: number;
+    guidance?: string;
+  };
 }
 
 export interface CatalogDescription {
@@ -203,6 +255,15 @@ function renderSchema(schema: JsonSchema, format: "compact" | "json"): unknown {
   return format === "json" ? schema : compactSchema(schema);
 }
 
+function renderSearchSchema(
+  schema: JsonSchema,
+  format: "compact" | "json",
+): { schema: unknown; truncated: boolean } {
+  if (format === "json") return { schema, truncated: false };
+  const compact = compactDiscoverySchema(schema);
+  return { schema: compact.text, truncated: compact.truncated };
+}
+
 /**
  * Request-local catalog operations shared by MCP meta-tools and code mode.
  * Successful catalogs may be reused inside this request; failures are not
@@ -397,12 +458,16 @@ export class CatalogService {
   async search(args: CatalogSearchArgs): Promise<CatalogSearchPage> {
     const query = args.query ?? "";
     const retrievalQuery = lexicalSearchQuery(query);
+    const safety = discoverySafety(args.safety);
     const limit = discoverySearchLimit(args.limit);
     const offset = Math.max(0, Math.trunc(args.offset ?? 0));
+    const scopedConnector = args.connector
+      ? this.registry.getConnector(args.connector)
+      : undefined;
     const connectors = args.connector
-      ? [this.registry.getConnector(args.connector)].filter(
-          (connector): connector is Connector => Boolean(connector),
-        )
+      ? scopedConnector
+        ? [scopedConnector]
+        : []
       : this.registry.listConnectors();
     const catalogs = await mapSettledWithConcurrency(
       connectors,
@@ -413,6 +478,14 @@ export class CatalogService {
           `search_tools probe of "${connector.id}"`,
         ),
     );
+    const searchableCatalogs = catalogs.map((catalog) =>
+      catalog.status === "fulfilled"
+        ? {
+            status: "fulfilled" as const,
+            value: toolsForSafety(catalog.value, safety),
+          }
+        : catalog,
+    );
     const matches: Array<{
       connector: Connector;
       tool: ToolDef;
@@ -421,7 +494,7 @@ export class CatalogService {
     }> = [];
     let matchMode: "all" | "partial" = "all";
     const statistics = lexicalCorpusStatistics(
-      catalogs.flatMap((catalog) =>
+      searchableCatalogs.flatMap((catalog) =>
         catalog.status === "fulfilled" ? [catalog.value] : [],
       ),
       retrievalQuery,
@@ -429,7 +502,7 @@ export class CatalogService {
     const collectMatches = (mode: "all" | "partial") => {
       matches.length = 0;
       let orderBase = 0;
-      catalogs.forEach((catalog, connectorIndex) => {
+      searchableCatalogs.forEach((catalog, connectorIndex) => {
         const connector = connectors[connectorIndex];
         if (!connector) {
           throw new Error("Catalog result has no corresponding connector");
@@ -459,9 +532,17 @@ export class CatalogService {
       collectMatches(matchMode);
     }
     matches.sort((a, b) => b.score - a.score || a.order - b.order);
-    const entries = matches.slice(offset, offset + limit).map((match) => {
+    const pageMatches = matches.slice(offset, offset + limit);
+    const entries = pageMatches.map((match) => {
       const input = match.tool.inputSchema ?? { type: "object" };
-      const description = summarizeDescription(
+      const renderedInput = args.includeSchemas
+        ? renderSearchSchema(input, args.includeSchemas)
+        : undefined;
+      const renderedOutput =
+        args.includeSchemas && match.tool.outputSchema
+          ? renderSearchSchema(match.tool.outputSchema, args.includeSchemas)
+          : undefined;
+      const description = summarizeDiscoveryDescription(
         match.tool.description,
         args.fullDescriptions === true,
       );
@@ -476,16 +557,20 @@ export class CatalogService {
           ...(description !== undefined ? { description } : {}),
           ...(args.includeSchemas
             ? {
-                inputSchema:
-                  renderSchema(input, args.includeSchemas),
+                inputSchema: renderedInput?.schema,
               }
             : {}),
+          ...(renderedInput?.truncated
+            ? { inputSchemaTruncated: true as const }
+            : {}),
           ...(args.includeSchemas && match.tool.outputSchema
             ? {
-                outputSchema:
-                  renderSchema(match.tool.outputSchema, args.includeSchemas),
+                outputSchema: renderedOutput?.schema,
               }
             : {}),
+          ...(renderedOutput?.truncated
+            ? { outputSchemaTruncated: true as const }
+            : {}),
           ...(args.includeSchemas && args.includeSchemaKeys
             ? schemaKeyMetadata(input, match.tool.outputSchema)
             : {}),
@@ -499,6 +584,62 @@ export class CatalogService {
       offset + entries.length < matches.length
         ? offset + entries.length
         : undefined;
+    const queryTerms = lexicalQueryTerms(retrievalQuery);
+    const analyzedTerms = queryTerms.slice(0, MAX_QUERY_ANALYSIS_TERMS);
+    const displayTerm = (term: string) =>
+      term.length <= MAX_QUERY_ANALYSIS_TERM_LENGTH
+        ? term
+        : `${term.slice(0, MAX_QUERY_ANALYSIS_TERM_LENGTH - 1)}…`;
+    const pageTools = new Set(pageMatches.map((match) => match.tool));
+    const matchingTools = (term: string) =>
+      new Set([
+        ...(statistics.nameMatches.get(term) ?? []),
+        ...(statistics.descriptionMatches.get(term) ?? []),
+      ]);
+    const representedTerms: string[] = [];
+    const otherResultTerms: string[] = [];
+    const unmatchedTerms: string[] = [];
+    for (const term of analyzedTerms) {
+      const termTools = matchingTools(term);
+      if ([...termTools].some((tool) => pageTools.has(tool))) {
+        representedTerms.push(displayTerm(term));
+      } else if (termTools.size > 0) {
+        otherResultTerms.push(displayTerm(term));
+      } else {
+        unmatchedTerms.push(displayTerm(term));
+      }
+    }
+    const unavailableCatalogs = catalogs.filter(
+      (catalog) => catalog.status === "rejected",
+    ).length;
+    const safetyLabel =
+      safety === "readOnly"
+        ? "read-only "
+        : safety === "approvalRequired"
+          ? "approval-required "
+          : "";
+    const filterRecovery =
+      safety === "all" ? "" : " Change safety to inspect the other tools.";
+    const guidance =
+      queryTerms.length === 0
+        ? undefined
+        : matches.length === 0
+          ? args.connector && !scopedConnector
+            ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
+            : scopedConnector
+              ? unavailableCatalogs > 0
+                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Retry later.`
+                : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
+              : unavailableCatalogs === 0
+                ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+                : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+          : matchMode === "partial"
+            ? scopedConnector
+              ? `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`
+              : unavailableCatalogs === 0
+              ? "No single tool matched every term. Split distinct intents into separate searches."
+              : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches."
+            : undefined;
     return {
       entries,
       total: matches.length,
@@ -509,6 +650,29 @@ export class CatalogService {
       ...(matchMode === "partial" && matches.length > 0
         ? { matchMode }
         : {}),
+      ...(queryTerms.length > 0 && matchMode === "partial"
+        ? {
+            queryAnalysis: {
+              representedTerms,
+              otherResultTerms,
+              unmatchedTerms,
+              ...(queryTerms.length > analyzedTerms.length ||
+              analyzedTerms.some(
+                (term) => term.length > MAX_QUERY_ANALYSIS_TERM_LENGTH,
+              )
+                ? { truncated: true as const }
+                : {}),
+              ...(args.connector ? { connectorScope: args.connector } : {}),
+              ...(args.connector && !scopedConnector
+                ? { unknownConnector: true as const }
+                : {}),
+              ...(unavailableCatalogs > 0
+                ? { unavailableConnectorCount: unavailableCatalogs }
+                : {}),
+              ...(guidance ? { guidance } : {}),
+            },
+          }
+        : {}),
     };
   }
 
@@ -592,7 +756,6 @@ export function groupedSearchResult(page: CatalogSearchPage) {
   const groups: Array<{
     id: string;
     title?: string;
-    description?: string;
     guide?: string;
     tools: CatalogSearchEntry["tool"][];
   }> = [];
@@ -605,9 +768,6 @@ export function groupedSearchResult(page: CatalogSearchPage) {
       const group: (typeof groups)[number] = {
         id: entry.connector.id,
         ...(entry.connector.title ? { title: entry.connector.title } : {}),
-        ...(entry.connector.description !== undefined
-          ? { description: entry.connector.description }
-          : {}),
         ...(entry.guide ? { guide: entry.guide } : {}),
         tools: [],
       };
@@ -624,17 +784,22 @@ export function groupedSearchResult(page: CatalogSearchPage) {
     hasMore: page.hasMore,
     ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
     ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+    ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
   };
 }
 
 export function flatSearchResult(page: CatalogSearchPage) {
   return {
-    tools: page.entries.map((entry) => entry.tool),
+    tools: page.entries.map((entry) => ({
+      ...entry.tool,
+      ...(entry.guide ? { guide: entry.guide } : {}),
+    })),
     total: page.total,
     offset: page.offset,
     limit: page.limit,
     hasMore: page.hasMore,
     ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
     ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+    ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
   };
 }

package/src/catalog.ts

@@ -1,16 +1,35 @@
 import type { JsonSchema, ToolDef } from "./types.js";
 
 const DEFAULT_DESCRIPTION_LENGTH = 240;
+const DISCOVERY_DESCRIPTION_LENGTH = 160;
+export const MAX_COMPACT_DISCOVERY_SCHEMA_BYTES = 1_024;
+const schemaEncoder = new TextEncoder();
+const COMPACT_DISCOVERY_TRUNCATION = " /* truncated */";
 
 export function summarizeDescription(
   text: string | undefined,
   full: boolean,
+): string | undefined {
+  return summarizeToLength(text, full, DEFAULT_DESCRIPTION_LENGTH);
+}
+
+export function summarizeDiscoveryDescription(
+  text: string | undefined,
+  full: boolean,
+): string | undefined {
+  return summarizeToLength(text, full, DISCOVERY_DESCRIPTION_LENGTH);
+}
+
+function summarizeToLength(
+  text: string | undefined,
+  full: boolean,
+  maxLength: number,
 ): string | undefined {
   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()}…`;
+  if (compact.length <= maxLength) return compact;
+  return `${compact.slice(0, maxLength - 1).trimEnd()}…`;
 }
 
 function lexicalTokens(text: string): string[] {
@@ -28,6 +47,11 @@ function normalized(text: string): string {
   return lexicalTokens(text).join(" ");
 }
 
+/** Distinct normalized terms in query order, shared by ranking and feedback. */
+export function lexicalQueryTerms(query: string): string[] {
+  return [...new Set(lexicalTokens(query))];
+}
+
 /**
  * Conversational framing selected by the #188 research run before the #189
  * holdout existed. Action-bearing terms such as get/list/search/find/create
@@ -208,7 +232,7 @@ export function lexicalCorpusStatistics(
   toolSets: ToolDef[][],
   query: string,
 ): LexicalCorpusStatistics {
-  const terms = [...new Set(lexicalTokens(query))];
+  const terms = lexicalQueryTerms(query);
   if (terms.length === 0) {
     return {
       documentCount: toolSets.reduce(
@@ -386,6 +410,10 @@ function renderSchema(
   defs: Record<string, unknown>,
   seen: Set<string>,
   depth: number,
+  options: {
+    propertyDescriptions: boolean;
+    requiredFirst: boolean;
+  },
 ): string {
   if (depth > 4) return "…";
   if (schema === null || typeof schema !== "object") {
@@ -404,10 +432,10 @@ function renderSchema(
   if (Array.isArray(s.allOf)) {
     const { allOf: _members, ...own } = s;
     const parts = declaresShape(own)
-      ? [renderSchema(own, defs, seen, depth)]
+      ? [renderSchema(own, defs, seen, depth, options)]
       : [];
     for (const member of s.allOf) {
-      parts.push(renderSchema(member, defs, seen, depth + 1));
+      parts.push(renderSchema(member, defs, seen, depth + 1, options));
     }
     if (parts.length === 0) return "unknown";
     if (parts.length === 1) return parts[0] as string;
@@ -420,7 +448,7 @@ function renderSchema(
     const target = defs[name];
     if (target === undefined) return name;
     seen.add(name);
-    const rendered = renderSchema(target, defs, seen, depth);
+    const rendered = renderSchema(target, defs, seen, depth, options);
     seen.delete(name);
     return rendered;
   }
@@ -428,7 +456,9 @@ function renderSchema(
   const union = (s.oneOf ?? s.anyOf) as unknown[] | undefined;
   if (Array.isArray(union)) {
     return (
-      union.map((u) => renderSchema(u, defs, seen, depth + 1)).join(" | ") ||
+      union
+        .map((u) => renderSchema(u, defs, seen, depth + 1, options))
+        .join(" | ") ||
       "unknown"
     );
   }
@@ -444,7 +474,7 @@ function renderSchema(
   const type = s.type;
   if (type === "array" || s.items) {
     const items = s.items
-      ? renderSchema(s.items, defs, seen, depth + 1)
+      ? renderSchema(s.items, defs, seen, depth + 1, options)
       : "unknown";
     return `${items}[]`;
   }
@@ -453,17 +483,31 @@ function renderSchema(
     const required = new Set(
       (Array.isArray(s.required) ? s.required : []) as string[],
     );
-    const keys = Object.keys(props);
+    const declaredKeys = Object.keys(props);
+    const keys = options.requiredFirst
+      ? [
+          ...declaredKeys.filter((key) => required.has(key)),
+          ...declaredKeys.filter((key) => !required.has(key)),
+        ]
+      : declaredKeys;
     if (keys.length === 0) return "{}";
     return `{ ${keys
       .map((key) => {
         const optional = required.has(key) ? "" : "?";
-        const rendered = renderSchema(props[key], defs, seen, depth + 1);
+        const rendered = renderSchema(
+          props[key],
+          defs,
+          seen,
+          depth + 1,
+          options,
+        );
         const description = (
           props[key] as Record<string, unknown> | null
         )?.description;
         const comment =
-          typeof description === "string" ? ` // ${description}` : "";
+          options.propertyDescriptions && typeof description === "string"
+            ? ` // ${description}`
+            : "";
         return `${key}${optional}: ${rendered}${comment}`;
       })
       .join(", ")} }`;
@@ -485,7 +529,10 @@ export function compactSchema(schema: JsonSchema): string {
   };
   let rendered: string;
   try {
-    rendered = renderSchema(schema, defs, new Set(), 0);
+    rendered = renderSchema(schema, defs, new Set(), 0, {
+      propertyDescriptions: true,
+      requiredFirst: false,
+    });
   } catch {
     rendered = JSON.stringify(schema);
   }
@@ -493,6 +540,90 @@ export function compactSchema(schema: JsonSchema): string {
   return rendered;
 }
 
+export interface CompactDiscoverySchema {
+  text: string;
+  truncated: boolean;
+}
+
+const compactDiscoverySchemas = new WeakMap<
+  JsonSchema,
+  CompactDiscoverySchema
+>();
+
+/**
+ * A valid, bounded replacement for a discovery shape too large to carry.
+ *
+ * Required object keys come first and every retained key is JSON-quoted, so
+ * arbitrary downstream names remain valid TypeScript property signatures.
+ * Types become `unknown`: pretending a severed nested type is exact would be
+ * worse than making the existing truncation flag's recovery route explicit.
+ */
+function truncatedDiscoverySchema(schema: JsonSchema): string {
+  const keys = schemaObjectKeys(schema);
+  if (!keys) return `unknown${COMPACT_DISCOVERY_TRUNCATION}`;
+  const required = new Set(keys.required);
+  const ordered = [
+    ...keys.properties.filter((key) => required.has(key)),
+    ...keys.properties.filter((key) => !required.has(key)),
+  ];
+  const parts: string[] = [];
+  for (const key of ordered) {
+    const part = `${JSON.stringify(key)}${required.has(key) ? "" : "?"}: unknown`;
+    const candidate = `{ ${[...parts, part].join(", ")} }${COMPACT_DISCOVERY_TRUNCATION}`;
+    if (
+      schemaEncoder.encode(candidate).length >
+      MAX_COMPACT_DISCOVERY_SCHEMA_BYTES
+    ) {
+      break;
+    }
+    parts.push(part);
+  }
+  if (parts.length === 0 && ordered.length > 0) {
+    return `unknown${COMPACT_DISCOVERY_TRUNCATION}`;
+  }
+  return `{ ${parts.join(", ")} }${COMPACT_DISCOVERY_TRUNCATION}`;
+}
+
+/**
+ * Render the schema shape carried by search results.
+ *
+ * Search is a routing step, so repeated property prose does not earn its
+ * context cost there. Required inputs render first, and the result has a hard
+ * UTF-8 budget; exact JSON and the prose-rich compact rendering remain
+ * available through the existing full retrieval paths.
+ */
+export function compactDiscoverySchema(
+  schema: JsonSchema,
+): CompactDiscoverySchema {
+  const cached = compactDiscoverySchemas.get(schema);
+  if (cached) return cached;
+  const defs = {
+    ...(schema.$defs as Record<string, unknown>),
+    ...(schema.definitions as Record<string, unknown>),
+  };
+  let rendered: string;
+  try {
+    rendered = renderSchema(schema, defs, new Set(), 0, {
+      propertyDescriptions: false,
+      requiredFirst: true,
+    });
+  } catch {
+    rendered = JSON.stringify(schema);
+  }
+  const bytes = schemaEncoder.encode(rendered);
+  let result: CompactDiscoverySchema;
+  if (bytes.length <= MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
+    result = { text: rendered, truncated: false };
+  } else {
+    result = {
+      text: truncatedDiscoverySchema(schema),
+      truncated: true,
+    };
+  }
+  compactDiscoverySchemas.set(schema, result);
+  return result;
+}
+
 /** The property and required names a schema resolves to, or undefined. */
 export interface SchemaObjectKeys {
   properties: string[];