@keemakr/operator-sdk 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/operator-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The keemakr connector contract: defineProvider + ConnectionProvider/ConnectionOperation types + OperationContext (governed fetch) + the connector manifest schema, shared by keemakr-core's built-in adapters and external connector repos. One shape, two consumers.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -22,6 +22,23 @@ export type AuthKind = 'oauth2' | 'api_key' | 'app_password';
 // to 'ready'), so legacy adapters stay connectable until told otherwise.
 export type Maturity = 'ready' | 'coming_soon';
 
+// Who a connector is FOR — the audience axis the end-user client uses to decide
+// whether to surface it, and how. Classify EVERY connector (defineProvider will
+// enforce this) so the client catalog never conflates the three kinds:
+//   'user-account' → the tenant's OWN account; connect/disconnect is the point.
+//                    Shown in the end-user connections hub (Gmail, Slack, Stripe,
+//                    HubSpot, social channels).
+//   'agent-tool'   → infrastructure an AGENT uses to do a task, not a personal
+//                    account. The platform may hold a shared key; a tenant may
+//                    override with their own. NEVER a standalone hub card — it
+//                    surfaces only via the install card of an agent that declares
+//                    it (Apollo, Hunter, Clearbit — enrichment/analytics/scraping).
+//   'internal'     → platform plumbing, or a dormant connector with no operations
+//                    and no consumer. Never shown to end users (e.g. agent-sessions;
+//                    op-less stubs — also keep those at maturity:'coming_soon').
+// See docs/architecture/05 + 15 and the AGENTS.md "Connectors" convention.
+export type ConnectorSurface = 'user-account' | 'agent-tool' | 'internal';
+
 export interface TokenSet {
   accessToken: string;
   refreshToken?: string | null;
@@ -95,6 +112,12 @@ export interface ConnectionProvider {
   // Connect-path maturity. Omitted ⇒ 'ready'. See Maturity above.
   maturity?: Maturity;
 
+  // Audience classification — see ConnectorSurface. Drives whether the end-user
+  // client surfaces this connector and how. Optional in the type for now so
+  // existing/external adapters compile through the SDK bump; defineProvider warns
+  // when omitted and this tightens to required once every built-in declares it.
+  surface?: ConnectorSurface;
+
   // Egress allowlist: the ONLY hosts this connector's operations/test may reach
   // through ctx.fetch. Bare hostname for an exact match ('api.acme.com') or a
   // wildcard for subdomains ('*.acme.com' — does NOT match the apex; list it
@@ -267,6 +290,16 @@ export function defineProvider(p: ConnectionProvider): ConnectionProvider {
   if (typeof p.test !== 'function') {
     throw new Error(`connections: provider '${p.provider}' must implement test()`);
   }
+  if (!p.surface) {
+    // Nudge, not throw (yet): the built-ins all declare `surface`, but external/marketplace
+    // connectors (separate repos) haven't adopted it. Tightening to a hard throw + a required
+    // field is gated on adding `surface` to the connector manifest schema.
+    console.warn(
+      `connections: provider '${p.provider}' does not declare surface ` +
+        `('user-account' | 'agent-tool' | 'internal') — classify it so the client catalog knows ` +
+        `whether and how to show it. See the AGENTS.md "Connectors" convention.`,
+    );
+  }
   if (p.operations && Object.keys(p.operations).length > 0 && !p.allowedDomains?.length) {
     // Warn, don't throw: built-ins are grandfathered on ambient fetch. The
     // marketplace publish gate REQUIRES allowed_domains in the manifest, so

package/src/manifest.ts

@@ -59,9 +59,24 @@ export const connectorManifestSchema = z
     // tenant's credential — which is why remote connectors require explicit
     // per-connection consent before any call.
     runtime_url: z.string().url().max(500).optional(),
+    // Lane 'mcp': the author points at a remote Model Context Protocol server
+    // instead of writing operation bodies. Each declared operation forwards to
+    // that server's `tools/call` over Streamable HTTP, driven through the same
+    // governed fetch as Lane B. `url` is https-only and author-declared (never
+    // tenant-supplied); `auth` is 'injected' only in v1 — core vaults the
+    // tenant's credential and rides it on a transport header, never in the tool
+    // args. ('server_managed', where the MCP server holds its own upstream
+    // OAuth, is reserved for a later, higher-tier release.)
+    mcp: z
+      .object({
+        url: z.string().url().max(500),
+        auth: z.enum(['injected']),
+      })
+      .optional(),
     // Remote connectors have no adapter code in core, so their connect form is
     // declared HERE (vendored connectors keep connectFields in code — the
-    // adapter stays the single source of truth for Lane A).
+    // adapter stays the single source of truth for Lane A). MCP connectors are
+    // the same: no adapter code, so the form lives here too.
     connect_fields: z
       .array(
         z.object({
@@ -91,10 +106,19 @@ export const connectorManifestSchema = z
     changelog: z.string().max(5000).optional(),
   })
   .superRefine((m, ctx) => {
-    if (!m.entrypoint && !m.runtime_url) {
+    const lanes = [m.entrypoint, m.runtime_url, m.mcp].filter((v) => v != null).length;
+    if (lanes === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'declare exactly one lane: an entrypoint (vendored, Lane A), a runtime_url (remote, Lane B), or an mcp endpoint (remote MCP)',
+      });
+    }
+    if (lanes > 1) {
       ctx.addIssue({
         code: 'custom',
-        message: 'declare an entrypoint (vendored, Lane A) or a runtime_url (remote, Lane B)',
+        message:
+          'declare exactly one lane — entrypoint, runtime_url, and mcp are mutually exclusive',
       });
     }
     if (m.runtime_url && !m.runtime_url.startsWith('https://')) {
@@ -116,6 +140,25 @@ export const connectorManifestSchema = z
           'remote connectors must declare connect_fields (there is no adapter code to own the form)',
       });
     }
+    if (m.mcp && !m.mcp.url.startsWith('https://')) {
+      ctx.addIssue({ code: 'custom', path: ['mcp', 'url'], message: 'mcp.url must be https' });
+    }
+    if (m.mcp && m.auth_kind === 'oauth2') {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['auth_kind'],
+        message:
+          'mcp connectors are api_key/app_password only — core injects the vaulted credential on a transport header, it does not broker an author-owned OAuth dance',
+      });
+    }
+    if (m.mcp && (!m.connect_fields || m.connect_fields.length === 0)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['connect_fields'],
+        message:
+          'mcp connectors must declare connect_fields (there is no adapter code to own the form)',
+      });
+    }
   });
 
 export type ConnectorOperationDeclaration = z.infer<typeof connectorOperationDeclaration>;