@zapier/connectors-sdk 0.1.0-experimental.1

package/dist/index.js

@@ -0,0 +1,933 @@
+// src/connection-resolvers.ts
+function defineConnectionResolver(resolver) {
+  return resolver;
+}
+var zapierConnectionResolver = defineConnectionResolver({
+  name: "zapier-connection-id",
+  resolve: async (connectionId) => {
+    const { buildZapierFetch } = await import("./build-zapier-fetch-DWCYBAF4.js");
+    return buildZapierFetch(connectionId);
+  }
+});
+function defineBearerTokenResolver(opts = {}) {
+  const { scheme = "Bearer", name = "token" } = opts;
+  return defineConnectionResolver({
+    name,
+    resolve: (token) => (input, init = {}) => globalThis.fetch(input, {
+      ...init,
+      headers: {
+        ...init.headers ?? {},
+        Authorization: `${scheme} ${token}`
+      }
+    })
+  });
+}
+
+// src/connection-key.ts
+function envFromKey(name) {
+  return name.toUpperCase().replace(/-/g, "_");
+}
+
+// src/normalize-connections.ts
+function* walkConnections(definition) {
+  if (typeof definition.connection === "string") {
+    yield { slotName: void 0, connectionKey: definition.connection };
+    return;
+  }
+  if (definition.connections) {
+    for (const [slotName, connectionKey] of Object.entries(
+      definition.connections
+    )) {
+      yield { slotName, connectionKey };
+    }
+  }
+}
+function resolverArray(entry) {
+  return Array.isArray(entry) ? entry : [entry];
+}
+function bagKeysFor(resolver) {
+  const head = envFromKey(resolver.name);
+  if (resolver.keySuffixes === void 0) return [head];
+  return resolver.keySuffixes.map((s) => `${head}_${s}`);
+}
+function envVarsFor(slotName, connectionKey, resolver) {
+  const slotPrefix = slotName ? `${envFromKey(slotName)}_` : "";
+  const prefix = `${slotPrefix}${envFromKey(connectionKey)}_`;
+  return bagKeysFor(resolver).map((k) => `${prefix}${k}`);
+}
+function slotErrorLabel(slotName) {
+  return slotName ? `connections.${slotName}` : "connection";
+}
+function validateConnectionResolvers(scriptsByName, connectionResolvers) {
+  const referenced = /* @__PURE__ */ new Set();
+  for (const definition of Object.values(scriptsByName)) {
+    for (const { connectionKey } of walkConnections(definition)) {
+      referenced.add(connectionKey);
+    }
+  }
+  const missing = [];
+  for (const key of referenced) {
+    if (!(key in connectionResolvers)) missing.push(key);
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `connectionResolvers is missing entries for connection key(s): ${missing.map((k) => `"${k}"`).join(", ")}. Each connection key referenced by a script's \`connection:\` / \`connections.<slot>:\` field must have a resolver entry.`
+    );
+  }
+  for (const [key, entry] of Object.entries(connectionResolvers)) {
+    if (!referenced.has(key)) continue;
+    const resolvers = resolverArray(entry);
+    if (resolvers.length === 0) {
+      throw new Error(
+        `connectionResolvers["${key}"] is an empty array. Provide at least one resolver.`
+      );
+    }
+    const seen = /* @__PURE__ */ new Map();
+    for (let i = 0; i < resolvers.length; i++) {
+      const resolver = resolvers[i];
+      const name = resolver.name;
+      const previous = seen.get(name);
+      if (previous !== void 0) {
+        throw new Error(
+          `connectionResolvers["${key}"]: two resolvers share name "${name}" (indexes ${previous} and ${i}). Resolver names must be unique within a connection key \u2014 they compose to the env-var segment.`
+        );
+      }
+      seen.set(name, i);
+    }
+  }
+}
+function resolversForKey(connectionResolvers, connectionKey) {
+  const entry = connectionResolvers[connectionKey];
+  if (entry === void 0) {
+    throw new Error(
+      `connectionResolvers has no entry for connection key "${connectionKey}".`
+    );
+  }
+  return resolverArray(entry);
+}
+function pickResolverFromEnv(resolvers, slotName, connectionKey, env) {
+  for (const resolver of resolvers) {
+    const envVars = envVarsFor(slotName, connectionKey, resolver);
+    if (envVars.every((k) => typeof env[k] === "string" && env[k] !== "")) {
+      return { resolver, envVars };
+    }
+  }
+  return null;
+}
+function envValuesToConnectionValue(resolver, envVars, env) {
+  const head = envFromKey(resolver.name);
+  if (resolver.keySuffixes === void 0) {
+    return { [head]: env[envVars[0]] };
+  }
+  const bag = {};
+  for (let i = 0; i < resolver.keySuffixes.length; i++) {
+    const suffix = resolver.keySuffixes[i];
+    bag[`${head}_${suffix}`] = env[envVars[i]];
+  }
+  return bag;
+}
+function buildRunOptionsFromEnv(definition, env, connectionResolvers) {
+  if (definition.connection === void 0 && definition.connections === void 0) {
+    return {};
+  }
+  if (typeof definition.connection === "string") {
+    const resolvers = resolversForKey(
+      connectionResolvers,
+      definition.connection
+    );
+    const picked = pickResolverFromEnv(
+      resolvers,
+      void 0,
+      definition.connection,
+      env
+    );
+    if (picked === null) {
+      return { connection: void 0 };
+    }
+    return {
+      connection: envValuesToConnectionValue(
+        picked.resolver,
+        picked.envVars,
+        env
+      )
+    };
+  }
+  const wrapped = {};
+  for (const [slotName, connectionKey] of Object.entries(
+    definition.connections
+  )) {
+    const resolvers = resolversForKey(connectionResolvers, connectionKey);
+    const picked = pickResolverFromEnv(resolvers, slotName, connectionKey, env);
+    wrapped[slotName] = picked === null ? void 0 : envValuesToConnectionValue(picked.resolver, picked.envVars, env);
+  }
+  return { connections: wrapped };
+}
+function formatHelpForConnections(definition, connectionResolvers) {
+  const slots = [...walkConnections(definition)];
+  if (slots.length === 0) return [];
+  const lines = [];
+  lines.push(
+    "Connections (set as environment variables; do NOT pass via CLI argument):"
+  );
+  for (const { slotName, connectionKey } of slots) {
+    const resolvers = resolversForKey(connectionResolvers, connectionKey);
+    const heading = slotName ? `  ${slotName} (${connectionKey}):` : `  ${connectionKey}:`;
+    lines.push(heading);
+    for (const resolver of resolvers) {
+      lines.push(`    ${resolver.name}:`);
+      for (const envVar of envVarsFor(slotName, connectionKey, resolver)) {
+        lines.push(`      ${envVar}`);
+      }
+    }
+  }
+  return lines;
+}
+
+// src/resolve-fetch.ts
+function isSingle(resolver) {
+  return resolver.keySuffixes === void 0;
+}
+function isMulti(resolver) {
+  return resolver.keySuffixes !== void 0;
+}
+async function resolveSlotFetch(scriptName, slotName, connectionKey, resolvers, value) {
+  if (typeof value === "function") return value;
+  if (typeof value === "string") {
+    const single = resolvers.find(isSingle);
+    if (!single) {
+      throw new Error(
+        slotContext(scriptName, slotName, connectionKey) + `\`string\` shorthand requires at least one single-credential resolver, but none are registered. Available resolvers: ${describeResolvers(resolvers)}.`
+      );
+    }
+    return single.resolve(value);
+  }
+  const bag = value;
+  const inputKeys = Object.keys(bag).sort();
+  for (const resolver of resolvers) {
+    const expected = [...bagKeysFor(resolver)].sort();
+    if (sameKeys(inputKeys, expected)) {
+      if (isSingle(resolver)) {
+        return resolver.resolve(bag[expected[0]]);
+      }
+      if (isMulti(resolver)) {
+        const head = `${resolver.name.toUpperCase().replace(/-/g, "_")}_`;
+        const stripped = {};
+        for (const k of expected) {
+          stripped[k.slice(head.length)] = bag[k];
+        }
+        return resolver.resolve(
+          stripped
+        );
+      }
+    }
+  }
+  if (Object.keys(bag).length === 0) {
+    throw new Error(
+      slotContext(scriptName, slotName, connectionKey) + `No resolver matched \u2014 the connection record is empty. Provide credentials via env vars OR a record bag. Available resolvers and shapes: ${describeResolvers(resolvers, slotName, connectionKey)}.`
+    );
+  }
+  throw new Error(
+    slotContext(scriptName, slotName, connectionKey) + `No resolver matched the record bag keys [${inputKeys.join(", ")}]. Available resolvers and shapes: ${describeResolvers(resolvers, slotName, connectionKey)}.`
+  );
+}
+function sameKeys(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+function slotContext(scriptName, slotName, connectionKey) {
+  return `ToolDefinition "${scriptName}", ${slotErrorLabel(slotName)} (key: "${connectionKey}"): `;
+}
+function describeResolvers(resolvers, slotName, connectionKey) {
+  if (resolvers.length === 0) return "<none>";
+  return resolvers.map((resolver) => {
+    const bag = bagKeysFor(resolver);
+    const programmatic = `{ ${bag.join(", ")} }`;
+    if (slotName !== void 0 || connectionKey !== void 0) {
+      const envVars = connectionKey === void 0 ? bag : envVarsFor(slotName, connectionKey, resolver);
+      return `"${resolver.name}" -> programmatic ${programmatic} OR env [${envVars.join(", ")}]`;
+    }
+    return `"${resolver.name}" -> programmatic ${programmatic}`;
+  }).join("; ");
+}
+
+// src/build-context.ts
+function ensureConnectionValue(scriptName, slotName, connectionKey, value) {
+  if (value === void 0) {
+    throw new Error(
+      `ToolDefinition "${scriptName}", ${slotErrorLabel(slotName)} (key: "${connectionKey}"): no connection value provided. Set the resolver's required env vars, pass an explicit \`{ ${slotName ? `connections: { ${slotName}: ... }` : "connection: ..."} }\`, or pass a pre-authed Fetch.`
+    );
+  }
+  return value;
+}
+async function buildContext(definition, opts, connectionResolvers) {
+  const hasConnection = "connection" in opts && opts.connection !== void 0;
+  const hasConnections = "connections" in opts && opts.connections !== void 0;
+  if (definition.connection === void 0 && definition.connections === void 0) {
+    if (hasConnection || hasConnections) {
+      throw new Error(
+        `ToolDefinition "${definition.name}" is credential-free \u2014 \`RunOptions\` must not include \`connection\` or \`connections\`.`
+      );
+    }
+    return {};
+  }
+  if (hasConnection && hasConnections) {
+    throw new Error(
+      `ToolDefinition "${definition.name}": \`RunOptions\` sets both \`connection\` and \`connections\`. Use one or the other.`
+    );
+  }
+  if (typeof definition.connection === "string") {
+    if (hasConnections) {
+      throw new Error(
+        `ToolDefinition "${definition.name}" is single-connection \u2014 call with \`{ connection: ... }\`, not \`{ connections: ... }\`.`
+      );
+    }
+    const connectionKey = definition.connection;
+    const resolvers = resolversForKey(connectionResolvers, connectionKey);
+    const value = ensureConnectionValue(
+      definition.name,
+      void 0,
+      connectionKey,
+      opts.connection
+    );
+    const fetch = await resolveSlotFetch(
+      definition.name,
+      void 0,
+      connectionKey,
+      resolvers,
+      value
+    );
+    return { fetch };
+  }
+  const declaredSlots = Object.keys(definition.connections);
+  if (hasConnection) {
+    throw new Error(
+      `ToolDefinition "${definition.name}" is multi-connection (slots: ${declaredSlots.join(", ")}) \u2014 call with \`{ connections: { ... } }\`, not \`{ connection: ... }\`.`
+    );
+  }
+  if (!hasConnections) {
+    throw new Error(
+      `ToolDefinition "${definition.name}" is multi-connection \u2014 \`RunOptions.connections\` is required.`
+    );
+  }
+  const provided = opts.connections;
+  const unknown = Object.keys(provided).filter(
+    (s) => !declaredSlots.includes(s)
+  );
+  if (unknown.length > 0) {
+    throw new Error(
+      `ToolDefinition "${definition.name}": unknown slot(s) in RunOptions: ${unknown.join(
+        ", "
+      )}. Declared: ${declaredSlots.join(", ")}.`
+    );
+  }
+  const fetches = {};
+  for (const [slotName, connectionKey] of Object.entries(
+    definition.connections
+  )) {
+    const resolvers = resolversForKey(connectionResolvers, connectionKey);
+    const value = ensureConnectionValue(
+      definition.name,
+      slotName,
+      connectionKey,
+      provided[slotName]
+    );
+    fetches[slotName] = await resolveSlotFetch(
+      definition.name,
+      slotName,
+      connectionKey,
+      resolvers,
+      value
+    );
+  }
+  return { connections: fetches };
+}
+
+// src/surfaces/openai-tool-fields.ts
+import { z } from "zod";
+function toolDefinitionOpenAIFields(definition) {
+  return {
+    name: definition.name,
+    description: definition.description ?? "",
+    parameters: z.toJSONSchema(definition.inputSchema)
+  };
+}
+
+// src/surfaces/to-chat-completion-tool.ts
+function toChatCompletionTool(definition) {
+  const fields = toolDefinitionOpenAIFields(definition);
+  return {
+    type: "function",
+    function: fields
+  };
+}
+
+// src/surfaces/to-mcp-server-tool.ts
+function toMcpServerTool(definition) {
+  const config = {
+    title: definition.title,
+    description: definition.description,
+    inputSchema: definition.inputSchema,
+    outputSchema: definition.outputSchema,
+    annotations: definition.annotations
+  };
+  if (definition.inputDependencies) {
+    config._meta = {
+      "zapier:inputDependencies": definition.inputDependencies
+    };
+  }
+  return config;
+}
+
+// src/surfaces/to-mcp-tool.ts
+import { z as z2 } from "zod";
+function toMcpTool(definition) {
+  const meta = {};
+  if (definition.inputDependencies) {
+    meta["zapier:inputDependencies"] = definition.inputDependencies;
+  }
+  return {
+    name: definition.name,
+    title: definition.title,
+    description: definition.description,
+    inputSchema: z2.toJSONSchema(definition.inputSchema),
+    outputSchema: z2.toJSONSchema(
+      definition.outputSchema
+    ),
+    annotations: definition.annotations,
+    ...Object.keys(meta).length > 0 ? { _meta: meta } : {}
+  };
+}
+
+// src/surfaces/to-responses-tool.ts
+function toResponsesTool(definition) {
+  return {
+    type: "function",
+    ...toolDefinitionOpenAIFields(definition)
+  };
+}
+
+// src/define-connector.ts
+function wrapScriptWithResolvers(definition, connectionResolvers) {
+  const authorRun = definition.run;
+  const wrappedRun = async (input, opts) => {
+    const validated = definition.inputSchema.parse(input);
+    if (definition.connection === void 0 && definition.connections === void 0) {
+      if (opts !== void 0 && (opts.connection !== void 0 || opts.connections !== void 0)) {
+        throw new Error(
+          `ToolDefinition "${definition.name}" is credential-free \u2014 \`RunOptions\` must not include \`connection\` or \`connections\`.`
+        );
+      }
+      return authorRun(validated);
+    }
+    if (opts === void 0) {
+      throw new Error(
+        `ToolDefinition "${definition.name}": \`RunOptions\` is required \u2014 pass \`{ connection: ... }\` or \`{ connections: ... }\`.`
+      );
+    }
+    const ctx = await buildContext(definition, opts, connectionResolvers);
+    return authorRun(validated, ctx);
+  };
+  return { ...definition, run: wrappedRun };
+}
+function defineConnector(config) {
+  const connectionResolvers = config.connectionResolvers ?? {};
+  const scriptsAsAny = config.scripts;
+  validateConnectionResolvers(scriptsAsAny, connectionResolvers);
+  const wrapped = {};
+  for (const [key, definition] of Object.entries(scriptsAsAny)) {
+    wrapped[key] = wrapScriptWithResolvers(definition, connectionResolvers);
+  }
+  return {
+    scripts: wrapped,
+    connectionResolvers,
+    toMcpTool,
+    toMcpServerTool,
+    toChatCompletionTool,
+    toResponsesTool,
+    buildRunOptionsFromEnv: (script, env) => buildRunOptionsFromEnv(script, env, connectionResolvers)
+  };
+}
+
+// src/define-tool.ts
+var SLOT_KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+var CONNECTION_KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+function validateConnectionKey(scriptName, key) {
+  if (!CONNECTION_KEY_PATTERN.test(key)) {
+    throw new Error(
+      `defineTool("${scriptName}"): connection key "${key}" must be lowercase kebab-case (e.g. "notion", "google-drive").`
+    );
+  }
+}
+function validateSlotName(scriptName, slot) {
+  if (!SLOT_KEY_PATTERN.test(slot)) {
+    throw new Error(
+      `defineTool("${scriptName}"): slot name "${slot}" must be lowercase kebab-case (e.g. "source", "target").`
+    );
+  }
+}
+function defineTool(config) {
+  const hasSingular = "connection" in config && config.connection !== void 0;
+  const hasPlural = "connections" in config && config.connections !== void 0;
+  if (hasSingular && hasPlural) {
+    throw new Error(
+      `defineTool: config sets both \`connection\` (singular) and \`connections\` (plural). Use one or the other.`
+    );
+  }
+  if (hasSingular) {
+    if (typeof config.connection !== "string") {
+      throw new Error(
+        `defineTool("${config.name}"): \`connection\` must be a string (the connection key registered in the connector's \`connectionResolvers\`).`
+      );
+    }
+    validateConnectionKey(config.name, config.connection);
+  }
+  if (hasPlural) {
+    if (typeof config.connections !== "object" || config.connections === null || Array.isArray(config.connections)) {
+      throw new Error(
+        `defineTool("${config.name}"): \`connections\` must be an object mapping slot names to connection keys.`
+      );
+    }
+    const slotKeys = Object.keys(config.connections);
+    if (slotKeys.length === 0) {
+      throw new Error(
+        `defineTool("${config.name}"): \`connections: {}\` is empty. Declare at least one slot.`
+      );
+    }
+    for (const slot of slotKeys) {
+      validateSlotName(config.name, slot);
+      const value = config.connections[slot];
+      if (typeof value !== "string") {
+        throw new Error(
+          `defineTool("${config.name}"): slot "${slot}" must reference a connection key string.`
+        );
+      }
+      validateConnectionKey(config.name, value);
+    }
+  }
+  const base = {
+    kind: "tool",
+    name: config.name,
+    title: config.title,
+    description: config.description,
+    inputSchema: config.inputSchema,
+    outputSchema: config.outputSchema,
+    annotations: config.annotations,
+    statements: config.statements,
+    inputDependencies: config.inputDependencies,
+    run: config.run
+  };
+  if (hasSingular) base.connection = config.connection;
+  if (hasPlural) base.connections = config.connections;
+  return base;
+}
+
+// src/surfaces/handle-if-script-main.ts
+import { z as z3 } from "zod";
+
+// src/surfaces/run-dispatch-cli.ts
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+
+// src/surfaces/serve-mcp-stdio.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+function buildMcpRegistry(scripts, env, connectionResolvers) {
+  const registry = {};
+  for (const script of Object.values(scripts)) {
+    const hasConnections = [...walkConnections(script)].length > 0;
+    registry[script.name] = {
+      script,
+      runOpts: hasConnections ? buildRunOptionsFromEnv(script, env, connectionResolvers) : void 0
+    };
+  }
+  return registry;
+}
+var FALLBACK_SERVER_NAME = "@zapier/connector";
+var FALLBACK_SERVER_VERSION = "0.0.0";
+async function resolveServerInfo(meta) {
+  if (!meta.url) {
+    return { name: FALLBACK_SERVER_NAME, version: FALLBACK_SERVER_VERSION };
+  }
+  try {
+    const cliPath = fileURLToPath(meta.url);
+    const pkgPath = path.join(path.dirname(cliPath), "package.json");
+    const raw = await fs.readFile(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    return {
+      name: typeof pkg.name === "string" ? pkg.name : FALLBACK_SERVER_NAME,
+      version: typeof pkg.version === "string" ? pkg.version : FALLBACK_SERVER_VERSION
+    };
+  } catch {
+    return { name: FALLBACK_SERVER_NAME, version: FALLBACK_SERVER_VERSION };
+  }
+}
+async function serveMcpStdio(meta, connector, opts = {}) {
+  const env = opts.env ?? process.env;
+  const stderr = opts.stderr ?? process.stderr;
+  const scripts = connector.scripts;
+  const connectionResolvers = connector.connectionResolvers;
+  const registry = buildMcpRegistry(scripts, env, connectionResolvers);
+  const serverInfo = opts.serverInfo ?? await resolveServerInfo(meta);
+  const server = new McpServer(serverInfo);
+  for (const { script, runOpts } of Object.values(registry)) {
+    server.registerTool(
+      script.name,
+      toMcpServerTool(script),
+      // `registerTool` runs the zod input parse internally and hands the
+      // parsed value to the callback — matching the wrapped run contract
+      // (which also runs the parse, harmlessly twice). Wide cast on
+      // `input` because the registry walk is polymorphic over every
+      // script's schema.
+      async (input) => {
+        const result = await script.run(input, runOpts);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          structuredContent: result
+        };
+      }
+    );
+  }
+  await server.connect(new StdioServerTransport());
+  stderr.write(`[${serverInfo.name}] MCP server ready on stdio.
+`);
+}
+
+// src/surfaces/run-dispatch-cli.ts
+function asAnyDefinition(value) {
+  return value;
+}
+async function runDispatchCli(meta, connector) {
+  if (!meta.main) return;
+  try {
+    await runDispatchCliBody(connector, {
+      meta,
+      argv: process.argv,
+      env: process.env,
+      stdin: process.stdin,
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  } catch (err) {
+    reportFatalErrorAndExit(err, process.stderr, (code) => process.exit(code));
+  }
+}
+function reportFatalErrorAndExit(err, stderr, exit) {
+  const message = err instanceof Error ? err.stack ?? `${err.name}: ${err.message}` : String(err);
+  stderr.write(`${message}
+`);
+  exit(1);
+}
+async function runDispatchCliBody(connector, opts) {
+  const args = opts.argv.slice(2);
+  const first = args[0];
+  const errOut = opts.stderr ?? opts.stdout;
+  const scripts = connector.scripts;
+  const connectionResolvers = connector.connectionResolvers;
+  const packageName = await resolvePackageName(opts.meta);
+  if (!first || first === "--help" || first === "-h") {
+    printUsage(scripts, opts.stdout, packageName);
+    return;
+  }
+  if (first === "mcp") {
+    const second = args[1];
+    if (second === "--help" || second === "-h") {
+      printMcpHelp(scripts, opts.stdout, packageName);
+      return;
+    }
+    if (args.length > 1) {
+      printUsage(scripts, errOut, packageName);
+      throw new Error(
+        `Unexpected argument(s) after \`mcp\`: ${args.slice(1).map((a) => `"${a}"`).join(
+          ", "
+        )}. Usage: \`<bin> mcp\` (no arguments; run \`<bin> mcp --help\` for details).`
+      );
+    }
+    const serve = opts.serveMcpStdio ?? serveMcpStdio;
+    if (!opts.meta) {
+      throw new Error(
+        "runDispatchCliBody: `mcp` requires `meta` in options (the connector's `import.meta` from `cli.ts`)."
+      );
+    }
+    await serve(opts.meta, connector, {
+      env: opts.env,
+      stderr: opts.stderr
+    });
+    return;
+  }
+  if (first !== "run") {
+    printUsage(scripts, errOut, packageName);
+    throw new Error(
+      `Unknown command "${first}". Use \`run <script>\` to dispatch a script (available: ${Object.keys(scripts).join(", ") || "<none>"}), or \`mcp\` to boot a local MCP server.`
+    );
+  }
+  const scriptName = args[1];
+  if (!scriptName) {
+    printUsage(scripts, errOut, packageName);
+    throw new Error(
+      `Missing script name after \`run\`. Available: ${Object.keys(scripts).join(", ") || "<none>"}.`
+    );
+  }
+  const rest = args.slice(2);
+  const script = scripts[scriptName];
+  if (!script) {
+    printUsage(scripts, errOut, packageName);
+    throw new Error(
+      `Unknown script "${scriptName}". Available: ${Object.keys(scripts).join(", ") || "<none>"}.`
+    );
+  }
+  const invocation = packageName ? { bin: `npx ${packageName}`, scriptName } : void 0;
+  await handleIfScriptMainBody(asAnyDefinition(script), connectionResolvers, {
+    argv: ["node", scriptName, ...rest],
+    env: opts.env,
+    stdin: opts.stdin,
+    stdout: opts.stdout,
+    invocation
+  });
+}
+async function resolvePackageName(meta) {
+  if (!meta?.url) return void 0;
+  try {
+    const cliPath = fileURLToPath2(meta.url);
+    const pkgPath = path2.join(path2.dirname(cliPath), "package.json");
+    const raw = await fs2.readFile(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.name === "string" ? pkg.name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function printUsage(scripts, out, packageName) {
+  const names = Object.keys(scripts);
+  out.write(
+    `Usage: <bin> run <script> [<json-input>]
+       <bin> run <script> --help    (per-script input + required env vars)
+       <bin> mcp                    (run as a local MCP server over stdio)
+
+`
+  );
+  const firstScript = names[0];
+  if (packageName && firstScript) {
+    out.write(`Example: npx ${packageName} run ${firstScript} --help
+
+`);
+  }
+  if (names.length === 0) {
+    out.write(`Available scripts: <none>
+`);
+    return;
+  }
+  out.write(`Available scripts:
+`);
+  for (const name of names) {
+    const description = scripts[name]?.description ?? "";
+    const firstLine = description.split("\n")[0]?.trim() ?? "";
+    out.write(firstLine ? `  ${name} \u2014 ${firstLine}
+` : `  ${name}
+`);
+  }
+  out.write(
+    `
+Credentials are environment-variable only \u2014 run \`<bin> run <script> --help\` to list each script's required env vars.
+`
+  );
+}
+function printMcpHelp(scripts, out, packageName) {
+  out.write(
+    `mcp \u2014 Run as a local Model Context Protocol (MCP) server over stdio.
+
+`
+  );
+  out.write(`Usage:
+  <bin> mcp
+
+`);
+  if (packageName) {
+    out.write(`Example:
+  npx ${packageName} mcp
+
+`);
+  }
+  out.write(
+    `The server exposes every script as a native MCP tool. Credentials are
+env-only \u2014 set the env vars for each script you intend to call, listed
+by \`<bin> run <script> --help\`. Resolution happens once per script at
+server start; credentials never traverse the MCP transport.
+
+`
+  );
+  const names = Object.keys(scripts);
+  if (names.length === 0) {
+    out.write(`Available scripts (exposed as MCP tools): <none>
+`);
+    return;
+  }
+  out.write(`Available scripts (exposed as MCP tools):
+`);
+  for (const name of names) {
+    const description = scripts[name]?.description ?? "";
+    const firstLine = description.split("\n")[0]?.trim() ?? "";
+    out.write(firstLine ? `  ${name} \u2014 ${firstLine}
+` : `  ${name}
+`);
+  }
+}
+
+// src/surfaces/handle-if-script-main.ts
+async function handleIfScriptMain(meta, definition, opts = {}) {
+  if (!meta.main) return;
+  try {
+    const connectionResolvers = opts.connectionResolvers ?? {};
+    validateConnectionResolvers(
+      { [definition.name]: definition },
+      connectionResolvers
+    );
+    const wrapped = wrapScriptWithResolvers(definition, connectionResolvers);
+    await handleIfScriptMainBody(wrapped, connectionResolvers, {
+      argv: process.argv,
+      env: process.env,
+      stdin: process.stdin,
+      stdout: process.stdout
+    });
+  } catch (err) {
+    reportFatalErrorAndExit(err, process.stderr, (code) => process.exit(code));
+  }
+}
+async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
+  const args = io.argv.slice(2);
+  let positional;
+  let helpRequested = false;
+  for (const arg of args) {
+    if (arg === "--help" || arg === "-h") {
+      helpRequested = true;
+    } else if (arg.startsWith("--")) {
+      throw new Error(
+        `Unknown flag "${arg}". The per-script CLI accepts only \`--help\` and a positional JSON-encoded input. Credentials are env-only \u2014 set the resolver's required env vars (run with \`--help\` to list them).`
+      );
+    } else if (positional === void 0) {
+      positional = arg;
+    } else {
+      throw new Error(
+        `Unexpected extra positional argument "${arg}". The per-script CLI accepts a single positional JSON input.`
+      );
+    }
+  }
+  if (helpRequested) {
+    io.stdout.write(
+      buildHelpText(wrappedScript, connectionResolvers, {
+        invocation: io.invocation
+      })
+    );
+    return;
+  }
+  const raw = positional ?? await new Response(io.stdin).text();
+  if (raw.trim().length === 0) {
+    throw new Error(
+      `Missing JSON input for "${wrappedScript.name}". Pass it as a positional argument or via stdin.`
+    );
+  }
+  const input = wrappedScript.inputSchema.parse(JSON.parse(raw));
+  const hasConnections = [...walkConnections(wrappedScript)].length > 0;
+  const runOpts = hasConnections ? buildRunOptionsFromEnv(wrappedScript, io.env, connectionResolvers) : void 0;
+  const result = await wrappedScript.run(input, runOpts);
+  io.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+function buildHelpText(definition, connectionResolvers, opts = {}) {
+  const lines = [];
+  const description = definition.description.split("\n")[0]?.trim() ?? "";
+  lines.push(
+    description ? `${definition.name} \u2014 ${description}` : definition.name
+  );
+  lines.push("");
+  lines.push("Usage:");
+  if (opts.invocation) {
+    lines.push(`  <bin> run ${opts.invocation.scriptName} '<json-input>'`);
+  } else {
+    lines.push(`  <bin> '<json-input>'`);
+  }
+  lines.push("");
+  if (opts.invocation) {
+    lines.push("Example:");
+    lines.push(
+      `  ${formatExampleCommand(definition, connectionResolvers, opts.invocation)}`
+    );
+    lines.push("");
+  }
+  const connectionsBlock = formatHelpForConnections(
+    definition,
+    connectionResolvers
+  );
+  if (connectionsBlock.length > 0) {
+    lines.push(...connectionsBlock);
+    lines.push("");
+  } else {
+    lines.push("(No connections required.)");
+    lines.push("");
+  }
+  const inputBlock = formatHelpForInput(definition);
+  if (inputBlock.length > 0) {
+    lines.push(...inputBlock);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function formatExampleCommand(definition, connectionResolvers, invocation) {
+  const envAssignments = [];
+  for (const { slotName, connectionKey } of walkConnections(definition)) {
+    const entry = connectionResolvers[connectionKey];
+    if (entry === void 0) continue;
+    const firstResolver = resolverArray(entry)[0];
+    if (firstResolver === void 0) continue;
+    for (const envVar of envVarsFor(slotName, connectionKey, firstResolver)) {
+      envAssignments.push(`${envVar}=<value>`);
+    }
+  }
+  const parts = [
+    ...envAssignments,
+    invocation.bin,
+    "run",
+    invocation.scriptName,
+    "'<json-input>'"
+  ];
+  return parts.join(" ");
+}
+function formatHelpForInput(definition) {
+  let schema;
+  try {
+    schema = z3.toJSONSchema(definition.inputSchema);
+  } catch {
+    return [];
+  }
+  const lines = ["Input (JSON Schema):"];
+  const json = JSON.stringify(schema, null, 2);
+  for (const line of json.split("\n")) {
+    lines.push(`  ${line}`);
+  }
+  return lines;
+}
+
+// src/surfaces/to-functions.ts
+function toFunctions(connector) {
+  const out = {};
+  const scripts = connector.scripts;
+  for (const key of Object.keys(scripts)) {
+    out[key] = scripts[key].run;
+  }
+  return out;
+}
+export {
+  defineBearerTokenResolver,
+  defineConnectionResolver,
+  defineConnector,
+  defineTool,
+  handleIfScriptMain,
+  runDispatchCli,
+  toFunctions,
+  zapierConnectionResolver
+};