Validate maintained provider contracts without credentials

AGENTS.md

@@ -122,11 +122,12 @@ dead, and neither is a state to leave the repository in.
 - **CHANGELOG.** Each release opens with a narrative paragraph — what this
   release is, what breaks, what a deployment can ignore — then
   `### Added` / `### Changed` / `### Fixed`.
-- **Provider drift.** Before tagging a release, run `npm run drift:check` with
-  local provider credentials exported. It diffs each hosted-MCP catalog against
-  its vetted manifest and each hand-written provider's touched endpoints against
-  the provider's published OpenAPI document. Findings are read by a human and
-  become GitHub issues — no credential goes near CI, and nothing files itself.
+- **Provider drift.** Run `npm run providers:check` for the credential-free
+  public check across every maintained provider. It covers official MCP
+  documentation and OpenAPI contracts and never reads a provider credential.
+  Remote MCP schemas remain owned by the live `tools/list` response rather than
+  a vendored copy. Findings are read by a human and become GitHub issues;
+  nothing files itself.
   See
   [`documentation/provider-conventions.md`](./documentation/provider-conventions.md#the-maintainer-run-drift-check).
 - **Releases.** `npm run release:check`, tag `v<version>` matching

CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to this package are documented here.
 
+## 0.22.2 — 2026-09-01
+
+This patch makes the maintained-provider release check credential-free and
+adds explicit official-MCP alternatives beside the existing Cloudflare,
+Notion, and Vercel API connections. Existing declarations still select the
+hand-written API interface by default. Linear, Mixpanel, RevenueCat, and Stripe
+remain MCP-only, and deployments that do not select a new interface need no
+configuration or credential change.
+
+### Added
+
+- **Selectable API and MCP interfaces.** Cloudflare, Notion, and Vercel accept
+  `surface: "mcp"` for their official hosted server while preserving the API
+  default. Each MCP wrapper supplies release-reviewed safety classifications,
+  keeps unknown tools fail-closed, and leaves provider descriptions and input
+  and output schemas untouched.
+- **Credential-free provider validation.** `npm run providers:check` compares
+  every maintained provider with official public evidence: touched OpenAPI
+  operations for the three hand-written interfaces, and endpoint, OAuth, and
+  documented tool inventories for the seven hosted interfaces. It reads no
+  provider credential and generates no runtime tool.
+
+### Changed
+
+- **Public evidence replaces authenticated drift setup.** The lower-level
+  `drift:check` command now defaults to the same specification and documentation
+  checks; the credential helper and `--hosted` mode are removed. Live
+  `tools/list` responses remain authoritative for MCP schemas.
+- **Hosted safety manifests refreshed.** Stripe and RevenueCat classifications
+  now cover their current official tool references. Vercel URL fetching is
+  approval-gated because an application GET route is not guaranteed to be
+  observational.
+
+### Fixed
+
+- **Reviewed Vercel event drift.** Build-log projection accepts the expanded
+  deployment-event variants, including events without a published timestamp,
+  and the touched-endpoint digest records the reviewed contract (#520).
+- **Schema ownership stays intact.** Deterministic coverage now proves the
+  safety wrapper preserves each provider description, input schema, and output
+  schema by reference instead of substituting a vendored definition (#521).
+
 ## 0.22.1 — 2026-08-31
 
 This patch adds a maintained Vercel connection over the public REST API. It is

README.md

@@ -63,8 +63,10 @@ Fifty issues in, one small object out. Your context window notices.
 - **Wrap any HTTP API by hand.** A few lines per tool. No OpenAPI conversion —
   generated tool sprawl is the problem, not the fix.
 - **Use maintained connections** for Cloudflare, Linear, Mixpanel, Notion,
-  RevenueCat, Stripe, and Vercel — known endpoints, auth defaults, and vetted
-  read/write classifications, imported one at a time.
+  RevenueCat, Stripe, and Vercel: known endpoints, auth defaults, and vetted
+  read/write classifications, imported one at a time. Cloudflare, Notion, and
+  Vercel each let the deployment choose their hand-written API interface or
+  official hosted MCP.
 - **Let the agent work in code.** Search, chain, filter, join, and reduce
   inside the sandbox instead of round-tripping every call through the model.
 - **Teach undeclared result shapes by using them.** Successful read-only calls

documentation/cloudflare.md

@@ -1,20 +1,20 @@
 # Cloudflare prebuilt connection
 
 Import `cloudflare()` independently from
-`@zackbart/connecta/providers/cloudflare`. It is a deliberate, hand-written
-surface over Cloudflare's v4 REST API. Fifty-one tools combine ergonomic,
-fully described operations for common work with three guarded escape hatches
-for the rest of Cloudflare's fast-moving control plane. Reads, JSON mutations,
-and raw/multipart uploads remain separate so safety routing does not depend on
-an agent-supplied HTTP method. The connection keeps lean projections, typed
-failures, and a rate-limit budget matching the documented one. It adds no
-provider dependency, imports nothing outside Connecta, and is not reachable
-from Connecta's root entry.
+`@zackbart/connecta/providers/cloudflare`. The deployment chooses one of two
+interfaces. The default is a deliberate, hand-written surface over
+Cloudflare's v4 REST API. Its fifty-one tools combine ergonomic, fully
+described operations for common work with three guarded escape hatches for the
+rest of Cloudflare's fast-moving control plane. The other choice is
+Cloudflare's official whole-API hosted MCP, which exposes `search` and
+`execute` with live provider-owned schemas. Both are ordinary connectors and
+neither is reachable from Connecta's root entry.
 
 ```ts
 import { cloudflare } from "@zackbart/connecta/providers/cloudflare";
 
 const edge = cloudflare("cloudflare_prod", {
+  surface: "api", // optional; this is the backward-compatible default
   title: "Production edge",
   purpose: "DNS and cache administration for the production estate",
   zoneId: "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
@@ -23,6 +23,15 @@ const edge = cloudflare("cloudflare_prod", {
 });
 ```
 
+Use Cloudflare's hosted code-mode interface instead:
+
+```ts
+const wholeApi = cloudflare("cloudflare_mcp", {
+  surface: "mcp",
+  purpose: "Cloudflare administration outside the curated REST workflows",
+});
+```
+
 Use the legacy user-scoped Global API Key when an existing deployment needs it:
 
 ```ts
@@ -41,6 +50,29 @@ between a production and a staging instance needs to know which one answers the
 question. Account `instructions` are appended to the maintained guide and
 cannot change the connector's safety classification.
 
+## Choosing an interface
+
+Use the API interface when its projected named tools cover the work. Connecta
+owns those schemas, projections, typed errors, pagination, and the split
+between read-only and mutating escape hatches.
+
+Use `surface: "mcp"` when broad product coverage matters more than projected
+results. Cloudflare's official server covers more than 2,500 API endpoints
+through two code-mode tools. `search` reads the OpenAPI document and is
+read-only. `execute` can run a program containing any authorized HTTP method,
+so Connecta always routes it through approval. A program that happens to use
+only GET cannot be proven observational from the tool schema.
+
+The MCP catalog and schemas come from the live server. The release manifest
+classifies the two known names but does not replace their schemas. OAuth is the
+default. A headless deployment may instead pass `auth` with a scoped API token.
+The credential remains the provider-side permission boundary either way. The
+MCP interface accepts `callAdmission` when the deployment has a concurrency or
+call-rate requirement; it does not reuse the API interface's REST-wide budget.
+
+The remaining sections document the hand-written API interface. MCP tool
+arguments and results are intentionally read from the live server instead.
+
 ## No SDK, on purpose
 
 Cloudflare publishes an official `cloudflare` npm SDK, and this connection does
@@ -61,7 +93,7 @@ claim: the `cloudflare` package must not appear in `dependencies`,
 `peerDependencies`, or `devDependencies`, and every import in the provider
 must be relative.
 
-## Credentials
+## API credentials
 
 The default credential is a scoped Cloudflare API token, sent as
 `Authorization: Bearer <token>`. Create it under My Profile → API Tokens →
@@ -133,7 +165,7 @@ an empty `accountId` would fall back to the default again. A deployment that
 wants zones from one account passes `accountId` explicitly, and the property
 says so.
 
-## Tools
+## API tools
 
 The named surface covers workflows that benefit most from concise schemas and
 projections:
@@ -423,6 +455,14 @@ not by Connecta. `maxConcurrency` is the bound that actually protects a shared
 credential, because a single `execute_code` program can fan out far faster than
 the window notices.
 
+## Contract checks
+
+`npm run providers:check` compares the 49 fixed REST endpoints with
+Cloudflare's published OpenAPI document and the two MCP names, endpoint, and
+OAuth support with Cloudflare's official MCP page. It needs no Cloudflare
+credential. The MCP schemas are not vendored or reconstructed: the live
+`tools/list` response remains the contract agents receive.
+
 ## Conventions
 
 This connection is audited against

documentation/connectors.md

@@ -54,11 +54,29 @@ const analytics = mixpanel("product_analytics", {
 });
 ```
 
-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.
+The constructor may use `remoteMcp()` or `api()` internally. When a provider's
+official MCP and HTTP API expose materially different capabilities or schema
+ownership, the constructor may offer an explicit deployment-time surface
+choice. It must document the difference, keep a backward-compatible default,
+and never let an agent switch surfaces during a run. The choice grants no
+different runtime privileges. Two instances of the same provider are isolated
+in exactly the same way as two hand-written connectors with different ids.
+
+That choice exists only when the two interfaces are genuinely different:
+
+| Provider | Maintained interfaces | Why |
+| --- | --- | --- |
+| Cloudflare | API and MCP | The API interface has 48 projected named tools plus three safety-split hatches. The official MCP compresses more than 2,500 endpoints into `search` and approval-gated `execute`. |
+| Notion | API and MCP | The API interface has stable lean projections. The official MCP adds Notion-owned live schemas, workspace search, files, views, agents, and sessions. |
+| Vercel | API and MCP | The API interface has projected deployment operations. The official MCP owns a broader, independently changing catalog. |
+| Linear | MCP | Vendoring its GraphQL API would create a second schema system rather than a distinct maintained interface. |
+| Mixpanel | MCP | Its hosted service already joins several Mixpanel APIs; flattening those APIs would recreate the catalog problem. |
+| RevenueCat | MCP | Its official server is generated from API v2, so a second wrapper would duplicate the same contract. |
+| Stripe | MCP | Its official server already exposes both named workflows and supported API methods. A second raw API interface would duplicate it. |
+
+This is not a requirement that every provider have two labels. A second choice
+must change capability, result shape, or schema ownership enough to justify a
+second contract. Otherwise it only gives agents two names for the same thing.
 
 A prebuilt connection's vetted annotations fill in downstream silence and
 otherwise preserve explicit annotations. This includes an explicit

documentation/linear.md

@@ -176,6 +176,15 @@ A budget-only rule needs no queue. If you add `maxConcurrency` you are asking
 for a queue, and the admission controller then requires the rest of the queue
 settings at construction.
 
+## Public contract check
+
+`npm run drift:check -- --docs --provider linear` checks Linear's official MCP
+setup page for the read-write endpoint and OAuth support without using a
+credential. Linear does not publish an exact tool inventory there, so the
+command says `setup metadata only` and makes no claim about names or schemas.
+At runtime the live `tools/list` response remains the schema authority and is
+passed through without a vendored replacement.
+
 ## Conventions
 
 This connection is audited against

documentation/mixpanel.md

@@ -85,9 +85,11 @@ A read-only live audit on 2026-08-13 confirmed all three refusals against the
 US hosted endpoint. They are reported upstream as
 [`mixpanel/mixpanel-headless#202`](https://github.com/mixpanel/mixpanel-headless/issues/202).
 The vetted catalog records current schema digests for all 64 tools,
-so a later schema correction or regression appears by tool name in the
-maintainer drift check. The guide can then shrink when the downstream schema
-becomes complete; Connecta does not absorb the defect permanently.
+so a later schema correction or regression increments runtime drift when an
+ordinary catalog refresh observes it. The live definition is still served
+unchanged. The credential-free provider check does not depend on those digests.
+The guide can shrink when the downstream schema becomes complete; Connecta does
+not absorb the defect permanently.
 
 The wrapper classifies the documented observational tools as reads and the
 documented create, update, edit, merge, dismiss, duplicate, and delete tools as
@@ -142,6 +144,14 @@ for a queue, and the admission controller then requires the rest of the queue
 settings at construction. Discovery traffic is outside connector call admission
 either way and still needs restrained use.
 
+## Public contract check
+
+`npm run drift:check -- --docs --provider mixpanel` compares Mixpanel's
+official Available Tools table with the vetted manifest and checks all three
+regional endpoints plus OAuth support. The current table lists 63 tools. It
+omits `Fill-Event-Metadata`, which remains classified from the last
+authenticated review and is reported as `not documented`, not silently removed.
+
 ## Conventions
 
 This connection is audited against