@zackbart/connecta 0.12.2 → 0.13.0

package/dist/types.d.ts

@@ -189,13 +189,17 @@ export interface Connector {
      */
     callAdmission?: ConnectorCallAdmissionPolicy;
     /**
-     * Optional agent-facing usage guide (markdown) for this connector — preferred
-     * tools, address quirks, pagination conventions, rate-limit etiquette, good
-     * query patterns. Listed by the `skills` meta-tool as `connector:<id>` and
-     * returned verbatim by `skills({ name: "connector:<id>" })`. Keep it concise
-     * and imperative; it is read by agents, not operators.
+     * Optional agent-facing usage guide for this connector. A string preserves
+     * the original markdown-only contract. The structured form can add a short
+     * discovery summary and require review when even a complete compact schema
+     * cannot describe correct use (for example a generic API wrapper or a
+     * cross-operation sequencing rule).
+     *
+     * Listed by `skills` as `connector:<id>` and returned verbatim by
+     * `skills({ name: "connector:<id>" })`. The guide remains deployment-owned
+     * configuration; no runtime registration or shared mutable copy exists.
      */
-    usageGuide?: string;
+    usageGuide?: string | ConnectorUsageGuide;
     /** Optional operator-managed credential slot rendered on /credentials. */
     credential?: ConnectorCredentialConfig;
     /** Optional server-side check used by /credentials' Test action. */
@@ -267,6 +271,22 @@ export interface Connector {
      */
     handleRequest?(request: Request, ctx: ConnectorContext): Promise<Response | null>;
 }
+export interface ConnectorUsageGuide {
+    /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
+    content: string;
+    /**
+     * Bounded discovery hint describing the conventions the guide covers. When
+     * omitted, Connecta derives a summary from the guide's first meaningful line.
+     */
+    summary?: string;
+    /**
+     * Require review before every operation on this connector. Reserve this for
+     * cases whose correct arguments or sequence cannot be expressed by the
+     * downstream tool schema; mutations and truncated schemas are required
+     * automatically and do not need this flag.
+     */
+    required?: boolean;
+}
 /** Result of one sandboxed code execution. */
 export interface ExecuteResult {
     result: unknown;

package/dist/types.d.ts.map

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

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.12.2";
+export declare const CONNECTA_VERSION = "0.13.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.12.2";
+export const CONNECTA_VERSION = "0.13.0";
 //# sourceMappingURL=version.js.map

package/documentation/code-mode.md

@@ -209,7 +209,7 @@ documented functions as the whole surface.
 ```js
 const page = await connecta.search({
   query: "pipeline run job logs",   // 2–4 distinctive action/object terms
-  connector: "ci",                  // optional single-connector filter
+  connector: "ci",                  // load one obvious connector, not every catalog
   safety: "readOnly",               // or "approvalRequired" / "all"
   limit: 8,                         // 1–100, default 8
   offset: 0,
@@ -221,12 +221,12 @@ const page = await connecta.search({
 
 **S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Each entry in `tools` carries `address`, `name`, and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes; capped shapes remain structurally valid with `unknown` types plus `/* truncated */`, and carry `inputSchemaTruncated` or `outputSchemaTruncated`. Use `connecta.describe` (or JSON search) for omitted exact constraints.
 
-**S1a.** `safety: "readOnly"` returns exactly the tools available through `connecta.call`, connector shortcuts, and `connecta.batch`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. This filters rows only: it grants no authority and changes no admission decision.
+**S1a.** `connector` loads only the named catalog; omit it only when the integration is ambiguous, because an unscoped search fans out across every configured connector. `safety: "readOnly"` returns exactly the tools available through `connecta.call`, connector shortcuts, and `connecta.batch`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. These filters grant no authority and change no admission decision.
 
-**S2.** With schemas requested, a match whose input (or output) schema resolves
-to an object shape also carries `inputKeys`, `requiredInputKeys`, and
-`outputKeys`: the same names the rendered schema shows, ready to check before
-building arguments. A schema that is not an object shape — a union, an array, an
+**S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`, and `outputKeys`:
+the same names the rendered schema shows, ready to check before
+building arguments. Match inputs, truncation, safety, and outputs, not lexical
+rank; search distinct operations separately and use `outputKeys`, not guessed roots. A non-object schema — a union, an array, an
 unresolvable `$ref` — carries no lists rather than empty ones, because absent
 means "read the schema" where `[]` would claim the tool takes no fields. The
 lists come from the same walk that renders the compact schema, so a top-level

package/documentation/connectors.md

@@ -1,15 +1,116 @@
 # Connectors
 
 Connectors are the boundary between Connecta's fixed meta-tool surface and
-downstream capabilities. `api()` defines a deliberate HTTP API surface;
-`remoteMcp()` aggregates another MCP endpoint. Both publish the same tool
-definitions and pass through the same catalog, read-only admission, invocation,
-result-size, and activity paths.
+downstream capabilities. Prefer a prebuilt connection when Connecta maintains
+one for the provider. Use `api()` to define a deliberate HTTP API surface and
+`remoteMcp()` to aggregate any other MCP endpoint. All three authoring paths
+produce ordinary `Connector` instances and pass through the same catalog,
+read-only admission, credentials, storage, invocation, result-size, and
+activity paths.
 
 Connector instances are deployment configuration. They are not registered or
 reconfigured at runtime. Request-local clients, transports, abort signals, and
 catalogs must be released with the request that created them.
 
+## Prebuilt connections
+
+A prebuilt connection is an independently imported provider constructor, not a
+registry or a second connector interface. It packages behavior Connecta can
+maintain universally: provider endpoints and authentication defaults, tool
+definitions or downstream catalog behavior, schemas and annotations, lean
+result shapes, typed errors, pagination and retry conventions, and a short
+usage guide where schemas cannot carry the advice.
+
+The deployment still supplies the account-specific identity and policy:
+
+- a unique connector `id`, which owns its address, storage, credential,
+  catalog, admission, and activity namespaces;
+- a human-readable `title` and a concrete `purpose` or audience;
+- supported authentication overrides; and
+- account-specific instructions appended to, rather than replacing, the safe
+  provider guidance.
+
+Imports and registration stay explicit and a la carte:
+
+```ts
+import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
+
+const analytics = mixpanel("product_analytics", {
+  title: "Product analytics",
+  purpose: "Production product decisions for the growth team",
+});
+```
+
+The constructor may use `remoteMcp()` or `api()` internally. Callers should not
+need to care which transport gives the better agent-facing surface, and the
+choice does not grant the connection different runtime privileges. Two
+instances of the same provider are isolated in exactly the same way as two
+hand-written connectors with different ids.
+
+A prebuilt connection's vetted annotations are fill-in only. They classify what
+the downstream leaves unannotated and may always tighten a classification; they
+never overrule an explicit downstream `destructiveHint: true` or
+`readOnlyHint: false`. The fail-closed read-only invariant is unchanged by the
+authoring path.
+
+Prebuilt means preferred when available, not mandatory. A deployment may mix
+prebuilt connections, custom `remoteMcp()` connections, and custom `api()`
+connections. Connecta makes no completeness promise: providers without a
+maintained prebuilt connection continue to use the public primitives without
+loss of support.
+
+```ts
+import { createConnecta, remoteMcp, api } from "@zackbart/connecta";
+import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
+import { quickJsExecutor } from "@zackbart/connecta/quickjs";
+
+export const connecta = createConnecta({
+  executor: quickJsExecutor(),
+  connectors: [
+    // Maintained prebuilt connection.
+    mixpanel("product_analytics", {
+      purpose: "Production product decisions for the growth team",
+    }),
+    // Custom downstream MCP server, no prebuilt connection needed.
+    remoteMcp("linear", {
+      url: "https://mcp.linear.app/mcp",
+      description: "Issue tracking for the platform team",
+    }),
+    // Deliberate in-house HTTP surface, hand-written tool by hand-written tool.
+    api("billing", {
+      description: "Internal billing reads",
+      credential: { label: "Billing API token" },
+      tools: [
+        {
+          name: "get_invoice",
+          description: "Fetch one invoice by id.",
+          annotations: { readOnlyHint: true },
+          inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" } },
+            required: ["id"],
+          },
+          handler: async ({ id }, ctx) => {
+            const response = await fetch(
+              `https://billing.internal.example/invoices/${id}`,
+              { headers: { Authorization: `Bearer ${await ctx.credential?.get()}` } },
+            );
+            return response.json();
+          },
+        },
+      ],
+    }),
+  ],
+});
+```
+
+All three are ordinary `Connector` instances by the time the registry sees
+them. Nothing in the list is privileged by how it was authored.
+
+Maintained provider guides:
+
+- [Mixpanel](./mixpanel.md)
+
 ## MCP version skew
 
 Connecta deliberately sits between protocol generations
@@ -53,6 +154,17 @@ Tool calls must use the shared invocation path. That keeps direct calls, batch
 children, and code-mode host calls aligned on safety, retries, admission,
 timeouts, validation, result guards, and typed failures.
 
+Connector usage guides are configuration too. `usageGuide` accepts the
+historical markdown string or `{ content, summary?, required? }`; the latter
+lets discovery explain what the guide covers without loading it. The summary
+is only a bounded routing hint. Mark a guide `required` only when no complete
+tool schema can describe correct use, such as a generic operation wrapper or a
+mandatory cross-tool sequence. Mutations and truncated compact schemas already
+produce automatic review requirements. Two deployments may reuse the same
+constant and override its summary or requirement in their own config, but
+Connecta stores no runtime template and never lets one deployment's guide apply
+to another.
+
 For remote MCP tools, that path checks the catalog's advertised `inputSchema`
 before provider dispatch. Supported mismatches become bounded, payload-free
 `invalid_args` findings; a schema the local validator cannot evaluate passes

package/documentation/meta-tools.md

@@ -19,6 +19,21 @@ The consolidation removed overlapping routing choices while preserving the
 cheaper direct path for one cold call. The [guest API contract](./code-mode.md)
 is what a program is promised.
 
+The route is chosen before discovery. A result that will be reduced, a call
+whose arguments depend on an earlier result, or work with multiple operations
+starts with one `execute_code` call and keeps discovery, calls, and reduction
+inside it. Distinct operations get distinct short `connecta.search` queries in
+that program. Only one unknown-address read takes the cheaper top-level
+`search_tools` → `call_tool` path; a known address needs only `call_tool`.
+
+That routing is about read-only work, because that is the only work a program
+can do. Anything unannotated, write-capable, or destructive is inadmissible
+inside the sandbox, so multi-step destructive work discovers at the top level
+and runs each step through `call_destructive_tool` — where the host can put the
+question to a human. Telling an agent never to search at the top level for
+multiple calls would close the only route that work has
+([#295](https://github.com/zackbart/connecta/issues/295)).
+
 `execute_code` accepts optional `diagnostics: true` when a caller is measuring
 a workflow. It adds only compact request-local timing and serialized-size
 aggregates; normal calls carry no diagnostics block or response-context cost.
@@ -35,17 +50,23 @@ probing is an operator concern: the operator pages and `/health` own it.
 
 Start an unknown-address lookup with two to four distinctive action/object
 terms, not the full request, and omit `limit` so the default eight-result page
-stays small. Set `safety: "readOnly"` when the result is headed to `call_tool`
-or generated code; `safety: "approvalRequired"` finds the complementary set
-that must cross `call_destructive_tool`. Omitting `safety`, or setting it to
-`"all"`, preserves the complete configured catalog. This is only a discovery
-filter: it neither grants authority nor changes invocation admission.
+stays small. When the integration is obvious, set `connector` to its id: a
+scoped search loads that catalog alone, while an unscoped search must fan out
+across every configured connector. Leave the search unscoped when the right
+integration is genuinely ambiguous. Set `safety: "readOnly"` when the result is
+headed to `call_tool` or generated code; `safety: "approvalRequired"` finds the
+complementary set that must cross `call_destructive_tool`. Omitting `safety`,
+or setting it to `"all"`, preserves the complete configured catalog. This is
+only a discovery filter: it neither grants authority nor changes invocation admission.
 `includeSchemas: "compact"` adds each match's input and any declared output
 shape. Bounded plain-object schemas also expose `inputKeys`,
 `requiredInputKeys`, and `outputKeys`; a truncated shape omits its corresponding
 list rather than repeating a large partial inventory. Matches carry declared
-behavior annotations. When
-that shape is sufficient, call the returned address directly. Reserve schema
+behavior annotations. Lexical rank is only one signal: select a candidate whose
+required inputs are available, whose schema is complete enough for the call,
+and whose safety and declared outputs fit the work. A reducer uses `outputKeys`
+before inspecting the value; it does not assume a collection is named `items`
+or `results`. When that shape is sufficient, call the returned address directly. Reserve schema
 expansion through `connecta.describe` for a search without schemas, an
 ambiguous compact shape, or exact
 constraints that require `format: "json"`.
@@ -60,6 +81,51 @@ types; other shapes become `unknown /* truncated */`. The match also carries
 `includeSchemas: "json"` or use the existing describe path when exact
 constraints matter.
 
+## Connector guide selection
+
+A connector may attach a deployment-owned guide as markdown, preserving the
+original `usageGuide: string` configuration, or as
+`{ content, summary?, required? }`. The structured form does not register a
+connector or create a shared runtime template. `content` remains the markdown
+returned verbatim by `skills`; `summary` is normalized and capped at 120
+characters for discovery. When it is absent, Connecta derives the same bounded
+fallback used by the skills listing: the first meaningful body line, with a
+heading used only when the guide has no body. `required: true` is reserved for generic
+API wrappers and cross-operation conventions a complete downstream schema
+cannot express.
+
+Search and describe results keep the existing `guide: "connector:<id>"`
+pointer and add `guideSummary`. A matching tool also carries
+`guideRequired: true` and `guideRequiredReasons` when Connecta can prove review
+is necessary:
+`connector_required` for the explicit configuration above,
+`approval_required` for an unannotated or write-capable tool, and
+`schema_truncated` when a requested compact input or output shape was capped.
+The boolean is an instruction, not a server-side gate — nothing refuses the
+call, so the agent is told to fetch the guide before making it, for any reason
+listed. `connector_required` and `approval_required` survive exact schema
+expansion; `schema_truncated` is cleared by the describe that returns the exact
+shape, and describe reports whatever reasons remain in the same two fields.
+Otherwise it reads the
+bounded summary: connector-specific sequencing, units, pagination, aliases,
+and generic API conventions still require the guide when they affect the task,
+while a complete and unambiguous one-read schema proceeds directly.
+Guide lookup always uses an exact name returned by `skills({})`, search, or
+describe; callers do not manufacture `connector:<id>` from an unmarked
+connector.
+
+A connector-scoped lexical miss retains that connector's guide metadata under
+`queryAnalysis`. This matters for generic wrappers whose broad tool name does
+not contain endpoint vocabulary: a required guide remains discoverable before
+the caller falls back to an empty-query browse, rather than disappearing with
+the zero-tool page.
+
+The built-in `usage` skill is byte-identical across deployments and says to
+read it at most once per task. Connector guides remain scoped to the deployment
+that listed them, even when two deployments happen to use identical content.
+Deployments without connector guides receive none of the conditional guide
+sentences in their always-loaded tool descriptions.
+
 ## Result representation
 
 For object results, `structuredContent` is the canonical full-fidelity value.
@@ -122,7 +188,13 @@ results explain that no single tool covered every term and recommend splitting
 distinct intents. A true negative says that no matching capability is
 configured and recommends refining, connector-scoping, or browsing; when a
 connector catalog was unavailable, the response includes
-`unavailableConnectorCount` instead of making that stronger claim. Analysis
+`unavailableConnectorCount` instead of making that stronger claim. A search
+explicitly scoped to that unavailable connector also receives `catalogError` —
+the bounded classified failure (`code`, `message`, `retryable`, and any
+`retryAfterMs`) so the caller can tell a transient outage from one a deployment
+operator must clear. It carries nothing else the call-path classifier knows: a
+discovery read is not a call. Unscoped searches keep the count only — one
+connector's failure is not another search's context. Analysis
 from a connector-filtered search includes `connectorScope` and speaks only
 about that connector; `unknownConnector` distinguishes an unconfigured ID from
 a known connector with no match. Analysis covers at most eight distinct terms

package/documentation/mixpanel.md

@@ -0,0 +1,72 @@
+# Mixpanel prebuilt connection
+
+Import `mixpanel()` independently from
+`@zackbart/connecta/providers/mixpanel`. It wraps Mixpanel's hosted MCP server
+with regional endpoint selection, OAuth by default, a provider-rate admission
+budget, a task-oriented usage guide, and a vetted safety classification. It
+adds no provider dependency and is not reachable from Connecta's root entry.
+
+```ts
+import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
+
+const analytics = mixpanel("product_analytics", {
+  title: "Production product analytics",
+  purpose: "Product and growth decisions for the production app",
+  region: "us",
+  instructions: "Use the Core Product project unless the request says otherwise.",
+});
+```
+
+The `id` owns the ordinary connector namespaces; use a different id for every
+Mixpanel account. `purpose` is required because an agent choosing between two
+instances needs to know which account answers the question. Account
+`instructions` are appended to the maintained guide and cannot change the
+connector's safety classification.
+
+`region` accepts `"us"` (the default), `"eu"`, or `"in"` and selects the
+corresponding [official hosted endpoint](https://docs.mixpanel.com/docs/mcp#mcp-server-urls).
+OAuth is the recommended default and keeps each connector instance's flow and
+tokens in its connector-scoped storage. Mixpanel service accounts are also
+supported with an explicit header override:
+
+```ts
+mixpanel("automation_analytics", {
+  purpose: "Headless release-health reporting",
+  auth: {
+    type: "headers",
+    headers: { Authorization: `Bearer Basic ${env.MIXPANEL_SA_TOKEN}` },
+  },
+});
+```
+
+Keep that encoded service-account value in the runtime's secret store; it is a
+password, not ordinary configuration. Mixpanel currently labels service-account
+MCP authentication beta. Prefer OAuth unless the deployment is intentionally
+headless.
+
+The wrapper classifies the documented observational tools as reads and the
+documented create, update, edit, merge, dismiss, duplicate, and delete tools as
+writes. An unfamiliar tool added by the downstream fails closed onto
+`call_destructive_tool` until a Connecta release reviews it.
+
+That classification is **fill-in only**. It supplies the annotations Mixpanel
+leaves unset and may always tighten one — but it never contradicts an explicit
+downstream annotation. A tool on the read allowlist that arrives carrying
+`destructiveHint: true` or `readOnlyHint: false` keeps exactly what the
+downstream said and stays behind `call_destructive_tool`: the downstream is
+telling you this release's allowlist is stale, and the fail-closed invariant
+does not bend for a maintained connection. Maintained writes that only create
+something new (`Create-Dashboard`, `Create-Cohort`, `Create-Metric`, and the
+rest) leave `destructiveHint` unset; `readOnlyHint: false` already routes them
+through the destructive path, and asserting destruction only inflates the
+approval copy the host shows a human.
+
+Experiments and Feature Flags — 15 of the 63 classified tools — are Mixpanel
+beta surfaces. Expect their names and schemas to move faster than the rest.
+
+The connection also declares a per-runtime call-admission budget matching
+Mixpanel's documented 600 requests per hour — a best-effort approximation of
+the per-user limit, not an enforcement of it. Each runtime keeps its own
+counter, so N Worker isolates or Node processes serving one deployment can each
+admit up to 600. Discovery traffic is outside connector call admission and
+still needs restrained use.

package/ethos.md

@@ -15,9 +15,12 @@ order, and amending it is a design decision, not a drive-by edit.
 - **A deployment is a small config-as-code file.** Changing what agents can
   reach is an edit and a redeploy. One deployment, one tenant, one audience —
   more audiences means more deployments.
-- **Two equal ways in.** `remoteMcp()` proxies a downstream MCP server;
-  `api()` hand-writes a deliberate tool surface over a plain HTTP API. Both
-  come out identical: same addresses, same catalog, same safety rules.
+- **Curated when available, open when not.** Prefer an explicitly imported
+  prebuilt connection when Connecta maintains one: it carries the provider's
+  known-good endpoint, authentication defaults, tool ergonomics, and concise
+  usage guidance. `remoteMcp()` and `api()` remain equal, first-class
+  primitives for custom and unsupported integrations. Every path produces the
+  same `Connector`: same addresses, same catalog, same safety rules.
 - **Seven tools, an executor required.** The primary surface is a program, so
   every deployment runs an executor — a Dynamic Worker on Cloudflare, QuickJS
   behind its optional-peer subpath on Node — and one without refuses to boot
@@ -66,6 +69,8 @@ proposing one without a new argument is not.
 | Multi-tenancy / account model | refused | one deployment per tenant; deploy again instead |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | Runtime connector registration | refused | config-as-code is the security model |
+| Prebuilt connections as the preferred authoring path | accepted | an a-la-carte provider constructor, imported and constructed in the deployment file, encodes maintained defaults for providers connecta actually uses — preferred *when maintained*, with no promise of one per provider; it returns exactly one ordinary `Connector` with no extra privileges — never a bundle, a group, a preset, or a registry — its tools are hand-written or proxied from a downstream MCP catalog, never generated from a schema document; its vetted annotations classify what the downstream leaves unannotated and never overrule an explicit one; `remoteMcp()` and `api()` stay first-class ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Provider registry / integration marketplace | refused | prebuilt connections are imports, not listings; discovery happens in documentation, never at runtime ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Protocol sessions & server push | refused | stateless per request |
 | Resources & prompts aggregation | refused | tools only; connecta's own Apps shell is the one `resources/read` carve-out ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Elicitation passthrough | refused | no route through a stateless aggregator |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "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.",
@@ -64,6 +64,10 @@
     "./auth/clerk": {
       "types": "./dist/auth/clerk.d.ts",
       "import": "./dist/auth/clerk.js"
+    },
+    "./providers/mixpanel": {
+      "types": "./dist/providers/mixpanel.d.ts",
+      "import": "./dist/providers/mixpanel.js"
     }
   },
   "scripts": {