@zapier/connectors-sdk 0.1.0-experimental.1 → 0.1.0-experimental.10

package/README.internal.md

@@ -346,32 +346,6 @@ A multi-credential resolver `{ name: "hmac", keySuffixes: ["KEY", "SECRET"] }` w
 
 The author never sees `process.env`, never threads a `Fetch` through their script body, never re-implements auth logic.
 
-## `inputDependencies` — out-of-band dependent-field metadata
-
-Some scripts have input fields whose accepted shape depends on another input field — e.g. Notion's `create_database_item` takes a `databaseId` and a `properties` map whose schema is determined by which database was chosen. JSON Schema can't express that conditional shape, but adapters that drive option-loading or schema-resolution chains need to know about it.
-
-`defineTool` publishes the metadata in two places:
-
-1. `definition.inputDependencies` — programmatic readers reach for it directly on the script's default export.
-2. MCP registration shape — `_meta["zapier:inputDependencies"]` via either `toMcpTool` (wire-format) or `toMcpServerTool` (`McpServer.registerTool` config).
-
-Shape constraints:
-
-- Dependencies are keyed by the dependent input field's name (`databaseId`, `properties`).
-- Each entry names another tool by **string** (`fromTool: "list-databases"`), not by function reference — so the chain stays serializable.
-- Args passed to the resolver tool use `$<fieldName>` syntax to reference other input fields (`fromArgs: { databaseId: "$databaseId" }`). The adapter reads and evaluates these references; the script body does not.
-
-```ts
-inputDependencies: {
-  databaseId: { kind: "options", fromTool: "list-databases", fromArgs: {} },
-  properties: {
-    kind: "schema",
-    fromTool: "get-database-schema",
-    fromArgs: { databaseId: "$databaseId" },
-  },
-} as const,
-```
-
 ## `<bin> mcp` — local-MCP-server execution surface
 
 Reached through the bundled CLI as `npx @zapier/<x>-connector mcp` — no per-app glue. The dispatcher reserves the primary command `mcp` and delegates to the internal `serveMcpStdio` helper:

package/dist/index.cjs

@@ -109,6 +109,7 @@ function defineConnectionResolver(resolver) {
 }
 var zapierConnectionResolver = defineConnectionResolver({
   name: "zapier-connection-id",
+  optionalPackages: ["@zapier/zapier-sdk"],
   resolve: async (connectionId) => {
     const { buildZapierFetch: buildZapierFetch2 } = await Promise.resolve().then(() => (init_build_zapier_fetch(), build_zapier_fetch_exports));
     return buildZapierFetch2(connectionId);
@@ -128,12 +129,16 @@ function defineBearerTokenResolver(opts = {}) {
   });
 }
 
+// src/normalize-connections.ts
+var import_node_module = require("module");
+
 // src/connection-key.ts
 function envFromKey(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
 
 // src/normalize-connections.ts
+var import_meta = {};
 function* walkConnections(definition) {
   if (typeof definition.connection === "string") {
     yield { slotName: void 0, connectionKey: definition.connection };
@@ -267,23 +272,70 @@ function buildRunOptionsFromEnv(definition, env, connectionResolvers) {
   }
   return { connections: wrapped };
 }
-function formatHelpForConnections(definition, connectionResolvers) {
+function isPackageInstalled(name) {
+  try {
+    (0, import_node_module.createRequire)(import_meta.url).resolve(name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function formatHelpForConnections(definition, connectionResolvers, env) {
   const slots = [...walkConnections(definition)];
   if (slots.length === 0) return [];
   const lines = [];
   lines.push(
-    "Connections (set as environment variables; do NOT pass via CLI argument):"
+    "Auth (set as environment variables; do NOT pass via CLI argument):"
   );
+  const notReadySlots = [];
   for (const { slotName, connectionKey } of slots) {
     const resolvers = resolversForKey(connectionResolvers, connectionKey);
-    const heading = slotName ? `  ${slotName} (${connectionKey}):` : `  ${connectionKey}:`;
-    lines.push(heading);
+    if (slotName !== void 0) {
+      lines.push(`  ${slotName} (${connectionKey}):`);
+    }
+    const resolverIndent = slotName !== void 0 ? "    " : "  ";
+    const varIndent = slotName !== void 0 ? "      " : "    ";
+    let slotHasReady = false;
     for (const resolver of resolvers) {
-      lines.push(`    ${resolver.name}:`);
-      for (const envVar of envVarsFor(slotName, connectionKey, resolver)) {
-        lines.push(`      ${envVar}`);
+      const vars = envVarsFor(slotName, connectionKey, resolver);
+      let isReady = false;
+      let missingPkgs = [];
+      if (env !== void 0) {
+        const envVarsOk = vars.every(
+          (k) => typeof env[k] === "string" && env[k] !== ""
+        );
+        if (envVarsOk) isReady = true;
+        missingPkgs = (resolver.optionalPackages ?? []).filter(
+          (pkg) => !isPackageInstalled(pkg)
+        );
+      }
+      const markReady = isReady && !slotHasReady;
+      if (markReady) slotHasReady = true;
+      const resolverSuffix = env !== void 0 && markReady ? "  [READY \u2014 use this]" : "";
+      lines.push(`${resolverIndent}${resolver.name}:${resolverSuffix}`);
+      for (const envVar of vars) {
+        const varSuffix = env !== void 0 ? env[envVar] !== void 0 && env[envVar] !== "" ? "  [set]" : "  [not set]" : "";
+        lines.push(`${varIndent}${envVar}${varSuffix}`);
+      }
+      if (env !== void 0) {
+        for (const pkg of resolver.optionalPackages ?? []) {
+          if (missingPkgs.includes(pkg)) {
+            lines.push(
+              `${varIndent}${pkg}  [not installed \u2014 run \`npm install ${pkg}\` first]`
+            );
+          } else {
+            lines.push(`${varIndent}${pkg}  [installed]`);
+          }
+        }
       }
     }
+    if (env !== void 0 && !slotHasReady) {
+      notReadySlots.push(slotName ?? connectionKey);
+    }
+  }
+  if (env !== void 0 && notReadySlots.length > 0) {
+    const label = notReadySlots.length === slots.length ? "No option is ready" : `No option is ready for slot${notReadySlots.length > 1 ? "s" : ""} ${notReadySlots.join(", ")}`;
+    lines.push(`${label} \u2014 set one of the env vars above.`);
   }
   return lines;
 }
@@ -368,8 +420,8 @@ function ensureConnectionValue(scriptName, slotName, connectionKey, value) {
   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;
+  const hasConnection = opts !== void 0 && "connection" in opts && opts.connection !== void 0;
+  const hasConnections = opts !== void 0 && "connections" in opts && opts.connections !== void 0;
   if (definition.connection === void 0 && definition.connections === void 0) {
     if (hasConnection || hasConnections) {
       throw new Error(
@@ -378,6 +430,11 @@ async function buildContext(definition, opts, connectionResolvers) {
     }
     return {};
   }
+  if (opts === void 0) {
+    throw new Error(
+      `ToolDefinition "${definition.name}": \`RunOptions\` is required \u2014 pass \`{ connection: ... }\` or \`{ connections: ... }\`.`
+    );
+  }
   if (hasConnection && hasConnections) {
     throw new Error(
       `ToolDefinition "${definition.name}": \`RunOptions\` sets both \`connection\` and \`connections\`. Use one or the other.`
@@ -395,7 +452,7 @@ async function buildContext(definition, opts, connectionResolvers) {
       definition.name,
       void 0,
       connectionKey,
-      opts.connection
+      "connection" in opts ? opts.connection : void 0
     );
     const fetch = await resolveSlotFetch(
       definition.name,
@@ -412,12 +469,12 @@ async function buildContext(definition, opts, connectionResolvers) {
       `ToolDefinition "${definition.name}" is multi-connection (slots: ${declaredSlots.join(", ")}) \u2014 call with \`{ connections: { ... } }\`, not \`{ connection: ... }\`.`
     );
   }
-  if (!hasConnections) {
+  const provided = opts.connections;
+  if (provided === void 0) {
     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)
   );
@@ -471,28 +528,18 @@ function toChatCompletionTool(definition) {
 
 // src/surfaces/to-mcp-server-tool.ts
 function toMcpServerTool(definition) {
-  const config = {
+  return {
     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
 var import_zod2 = require("zod");
 function toMcpTool(definition) {
-  const meta = {};
-  if (definition.inputDependencies) {
-    meta["zapier:inputDependencies"] = definition.inputDependencies;
-  }
   return {
     name: definition.name,
     title: definition.title,
@@ -501,8 +548,7 @@ function toMcpTool(definition) {
     outputSchema: import_zod2.z.toJSONSchema(
       definition.outputSchema
     ),
-    annotations: definition.annotations,
-    ...Object.keys(meta).length > 0 ? { _meta: meta } : {}
+    annotations: definition.annotations
   };
 }
 
@@ -516,24 +562,9 @@ function toResponsesTool(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(input, ctx);
   };
   return { ...definition, run: wrappedRun };
 }
@@ -543,6 +574,11 @@ function defineConnector(config) {
   validateConnectionResolvers(scriptsAsAny, connectionResolvers);
   const wrapped = {};
   for (const [key, definition] of Object.entries(scriptsAsAny)) {
+    if (key !== definition.name) {
+      throw new Error(
+        `defineConnector: script key "${key}" must match its tool name \u2014 got name "${definition.name}". Rename the key to "${definition.name}" or update the tool's name field.`
+      );
+    }
     wrapped[key] = wrapScriptWithResolvers(definition, connectionResolvers);
   }
   return {
@@ -612,6 +648,12 @@ function defineTool(config) {
       validateConnectionKey(config.name, value);
     }
   }
+  const authorRun = config.run;
+  const wrappedRun = async (input, ctx) => {
+    const validated = config.inputSchema.parse(input);
+    const result = await authorRun(validated, ctx);
+    return config.outputSchema.parse(result);
+  };
   const base = {
     kind: "tool",
     name: config.name,
@@ -620,9 +662,7 @@ function defineTool(config) {
     inputSchema: config.inputSchema,
     outputSchema: config.outputSchema,
     annotations: config.annotations,
-    statements: config.statements,
-    inputDependencies: config.inputDependencies,
-    run: config.run
+    run: wrappedRun
   };
   if (hasSingular) base.connection = config.connection;
   if (hasPlural) base.connections = config.connections;
@@ -766,10 +806,73 @@ async function runDispatchCliBody(connector, opts) {
     });
     return;
   }
+  if (first === "skill") {
+    if (!opts.meta) {
+      throw new Error(
+        "runDispatchCliBody: `skill` requires `meta` in options (the connector's `import.meta` from `cli.ts`)."
+      );
+    }
+    const cliPath = (0, import_node_url2.fileURLToPath)(opts.meta.url);
+    const connectorDir = path2.dirname(cliPath);
+    const skillPath = path2.join(connectorDir, "SKILL.md");
+    let content;
+    try {
+      content = await fs2.readFile(skillPath, "utf8");
+    } catch {
+      throw new Error(
+        `SKILL.md not found at ${skillPath}. Ensure the connector ships a SKILL.md.`
+      );
+    }
+    opts.stdout.write(resolveRelativeLinks(content, connectorDir));
+    return;
+  }
+  if (first === "reference") {
+    if (!opts.meta) {
+      throw new Error(
+        "runDispatchCliBody: `reference` requires `meta` in options (the connector's `import.meta` from `cli.ts`)."
+      );
+    }
+    const cliPath = (0, import_node_url2.fileURLToPath)(opts.meta.url);
+    const connectorDir = path2.dirname(cliPath);
+    const refsDir = path2.join(connectorDir, "references");
+    const name = args[1];
+    if (!name) {
+      let entries;
+      try {
+        const files = await fs2.readdir(refsDir);
+        entries = files.filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -".md".length));
+      } catch {
+        entries = [];
+      }
+      if (entries.length === 0) {
+        opts.stdout.write(`Available references: <none>
+`);
+      } else {
+        opts.stdout.write(`Available references:
+`);
+        for (const entry of entries) {
+          opts.stdout.write(`  ${entry}
+`);
+        }
+      }
+      return;
+    }
+    const refPath = path2.join(refsDir, `${name}.md`);
+    let content;
+    try {
+      content = await fs2.readFile(refPath, "utf8");
+    } catch {
+      throw new Error(
+        `Reference file not found at ${refPath}. Ensure the connector ships \`references/${name}.md\`.`
+      );
+    }
+    opts.stdout.write(resolveRelativeLinks(content, refsDir));
+    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.`
+      `Unknown command "${first}". Use \`run <script>\` to dispatch a script (available: ${Object.keys(scripts).join(", ") || "<none>"}), \`mcp\` to boot a local MCP server, \`skill\` to print SKILL.md, or \`reference [<name>]\` to print or list reference docs.`
     );
   }
   const scriptName = args[1];
@@ -796,6 +899,17 @@ async function runDispatchCliBody(connector, opts) {
     invocation
   });
 }
+function resolveRelativeLinks(content, baseDir) {
+  return content.replace(
+    /(!?\[([^\]]*)\])\(([^)]+)\)/g,
+    (match, prefix, _alt, url) => {
+      if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("file:") || url.startsWith("#") || url.startsWith("/")) {
+        return match;
+      }
+      return `${prefix}(${path2.resolve(baseDir, url)})`;
+    }
+  );
+}
 async function resolvePackageName(meta) {
   if (!meta?.url) return void 0;
   try {
@@ -814,6 +928,8 @@ function printUsage(scripts, out, packageName) {
     `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)
+       <bin> skill                  (print SKILL.md to stdout)
+       <bin> reference [<name>]     (print references/<name>.md, or list all)
 
 `
   );
@@ -926,12 +1042,13 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   if (helpRequested) {
     io.stdout.write(
       buildHelpText(wrappedScript, connectionResolvers, {
-        invocation: io.invocation
+        invocation: io.invocation,
+        env: io.env
       })
     );
     return;
   }
-  const raw = positional ?? await new Response(io.stdin).text();
+  const raw = positional ?? await readStdinInput(io.stdin, wrappedScript.name);
   if (raw.trim().length === 0) {
     throw new Error(
       `Missing JSON input for "${wrappedScript.name}". Pass it as a positional argument or via stdin.`
@@ -943,6 +1060,14 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const result = await wrappedScript.run(input, runOpts);
   io.stdout.write(JSON.stringify(result, null, 2) + "\n");
 }
+async function readStdinInput(stdin, scriptName) {
+  if (stdin.isTTY) {
+    throw new Error(
+      `Missing JSON input for "${scriptName}". Pass it as a positional argument or pipe it via stdin.`
+    );
+  }
+  return new Response(stdin).text();
+}
 function buildHelpText(definition, connectionResolvers, opts = {}) {
   const lines = [];
   const description = definition.description.split("\n")[0]?.trim() ?? "";
@@ -966,7 +1091,8 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   }
   const connectionsBlock = formatHelpForConnections(
     definition,
-    connectionResolvers
+    connectionResolvers,
+    opts.env
   );
   if (connectionsBlock.length > 0) {
     lines.push(...connectionsBlock);

package/dist/index.d.cts

@@ -30,24 +30,6 @@ type Replace<S extends string, From extends string, To extends string> = S exten
  */
 type EnvFromKey<K extends string> = Uppercase<Replace<K, "-", "_">>;
 
-/**
- * A Zapier policy statement. Carried on the `ToolDefinition` for in-process
- * governance consumers (policy engines that wrap `script.run` before HTTP).
- * Not propagated to MCP `_meta` — only `inputDependencies` is published over
- * the wire (`_meta["zapier:inputDependencies"]`) by `toMcpTool` /
- * `toMcpServerTool`.
- */
-interface Statement {
-    effect: "allow" | "ask" | "deny";
-    permissions: ReadonlyArray<string>;
-    resources: ReadonlyArray<string>;
-    conditions?: ReadonlyArray<{
-        path: ReadonlyArray<string>;
-        operator: string;
-        value: unknown;
-    }>;
-    label?: string;
-}
 /**
  * Single-credential resolver: the resolver's `name` IS the credential
  * descriptor. `resolve` receives the credential as a plain `string` —
@@ -68,6 +50,12 @@ interface Statement {
 interface SingleConnectionResolver<TName extends string = string> {
     readonly name: TName;
     readonly keySuffixes?: undefined;
+    /**
+     * npm package names that must be installed for this resolver to function
+     * at runtime. Declared here so `--help` can check availability and tell
+     * the agent which packages to install before using this resolver.
+     */
+    readonly optionalPackages?: readonly string[];
     resolve: (credential: string) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
 }
 /**
@@ -86,6 +74,12 @@ interface SingleConnectionResolver<TName extends string = string> {
 interface MultiConnectionResolver<TName extends string = string, TSuffixes extends readonly string[] = readonly string[]> {
     readonly name: TName;
     readonly keySuffixes: TSuffixes;
+    /**
+     * npm package names that must be installed for this resolver to function
+     * at runtime. Declared here so `--help` can check availability and tell
+     * the agent which packages to install before using this resolver.
+     */
+    readonly optionalPackages?: readonly string[];
     resolve: (credentials: Record<TSuffixes[number], string>) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
 }
 /** Either resolver shape. */
@@ -160,43 +154,45 @@ interface RunOptionsMulti<TSlots extends string = string, TPerSlot extends Recor
     connections: TPerSlot;
 }
 type RunOptions<TSlots extends string = string, TValue = ConnectionValue, TPerSlot extends Record<TSlots, ConnectionValue> = Record<TSlots, ConnectionValue>> = RunOptionsNone | RunOptionsSingle<TValue> | RunOptionsMulti<TSlots, TPerSlot>;
+/** Author-facing context for a credential-free script. */
+interface ContextNone {
+    fetch?: undefined;
+    connections?: undefined;
+}
 /** Author-facing context for a single-connection script. */
 interface ContextSingle {
     fetch: typeof globalThis.fetch;
+    connections?: never;
 }
 /** Author-facing context for a multi-connection script. */
 interface ContextMulti<TSlots extends string = string> {
+    fetch?: never;
     connections: Record<TSlots, typeof globalThis.fetch>;
 }
-type AnyInputDependencies$1 = Readonly<Record<string, unknown>>;
-/** When authoring omits `inputDependencies`, the definition value is `undefined`. */
-type InputDependenciesValue<T> = [T] extends [undefined] ? undefined : T;
-interface DefineToolConfigBase<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
+interface DefineToolConfigBase<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string> {
     name: TName;
     title: string;
     description: string;
     inputSchema: TIn;
     outputSchema: TOut;
     annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
-    statements?: ReadonlyArray<Statement>;
-    inputDependencies?: TInputDependencies;
 }
-interface DefineToolConfigNone<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+interface DefineToolConfigNone<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string> extends DefineToolConfigBase<TIn, TOut, TName> {
     connection?: never;
     connections?: never;
-    run: (input: z.infer<TIn>) => Promise<z.infer<TOut>>;
+    run: (input: z.infer<TIn>, ctx?: ContextNone) => Promise<unknown>;
 }
-interface DefineToolConfigSingle<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+interface DefineToolConfigSingle<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TName> {
     connection: TKey;
     connections?: never;
-    run: (input: z.infer<TIn>, ctx: ContextSingle) => Promise<z.infer<TOut>>;
+    run: (input: z.infer<TIn>, ctx: ContextSingle) => Promise<unknown>;
 }
-interface DefineToolConfigMulti<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string, TSlots extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+interface DefineToolConfigMulti<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string, TSlots extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TName> {
     connection?: never;
     connections: Record<TSlots, TKey>;
-    run: (input: z.infer<TIn>, ctx: ContextMulti<TSlots>) => Promise<z.infer<TOut>>;
+    run: (input: z.infer<TIn>, ctx: ContextMulti<TSlots>) => Promise<unknown>;
 }
-interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
+interface ToolDefinitionBase<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string> {
     readonly kind: "tool";
     readonly name: TName;
     readonly title: string;
@@ -204,30 +200,26 @@ interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInp
     inputSchema: TIn;
     outputSchema: TOut;
     readonly annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
-    readonly statements: ReadonlyArray<Statement> | undefined;
-    inputDependencies: InputDependenciesValue<TInputDependencies>;
 }
-interface ToolDefinitionNone<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+interface ToolDefinitionNone<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TName extends string = string> extends ToolDefinitionBase<TIn, TOut, TName> {
     readonly connection?: undefined;
     readonly connections?: undefined;
-    /** Author's run; the wrapper passes `input` directly. */
-    run: (input: z.infer<TIn>) => Promise<z.infer<TOut>>;
+    run: (input: z.infer<TIn>, ctx?: ContextNone) => Promise<z.infer<TOut>>;
 }
-interface ToolDefinitionSingle<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+interface ToolDefinitionSingle<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TName extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TName> {
     readonly connection: TKey;
     readonly connections?: undefined;
     run: (input: z.infer<TIn>, ctx: ContextSingle) => Promise<z.infer<TOut>>;
 }
-interface ToolDefinitionMulti<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TSlots extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+interface ToolDefinitionMulti<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TName extends string = string, TSlots extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TName> {
     readonly connection?: undefined;
     readonly connections: Record<TSlots, TKey>;
     run: (input: z.infer<TIn>, ctx: ContextMulti<TSlots>) => Promise<z.infer<TOut>>;
 }
-type ToolDefinition<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TSlots extends string = string, TKey extends string = string> = ToolDefinitionNone<TIn, TOut, TInputDependencies, TName> | ToolDefinitionSingle<TIn, TOut, TInputDependencies, TName, TKey> | ToolDefinitionMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>;
+type ToolDefinition<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TName extends string = string, TSlots extends string = string, TKey extends string = string> = ToolDefinitionNone<TIn, TOut, TName> | ToolDefinitionSingle<TIn, TOut, TName, TKey> | ToolDefinitionMulti<TIn, TOut, TName, TSlots, TKey>;
 /** Wide author-side `run` signature for polymorphic walks. */
 type AnyToolDefinitionRun = (input: any, ctx?: any) => Promise<any>;
-type AnyToolDefinition = Omit<ToolDefinitionBase<z.ZodType, z.ZodType, any, string>, "run" | "inputDependencies"> & {
-    inputDependencies: AnyInputDependencies$1 | undefined;
+type AnyToolDefinition = Omit<ToolDefinitionBase<z.ZodObject<z.ZodRawShape>, z.ZodObject<z.ZodRawShape>, string>, "run"> & {
     run: AnyToolDefinitionRun;
     readonly connection?: string | undefined;
     readonly connections?: Record<string, string> | undefined;
@@ -330,10 +322,9 @@ declare function toChatCompletionTool(definition: AnyToolDefinition): ChatComple
 interface McpRegisterToolConfig {
     title?: string;
     description?: string;
-    inputSchema?: z.ZodType;
-    outputSchema?: z.ZodType;
+    inputSchema?: z.ZodObject<z.ZodRawShape>;
+    outputSchema?: z.ZodObject<z.ZodRawShape>;
     annotations?: ToolAnnotations;
-    _meta?: Record<string, unknown>;
 }
 /**
  * Build the `McpServer.registerTool` config for a `ToolDefinition`.
@@ -389,7 +380,7 @@ declare function toResponsesTool(definition: AnyToolDefinition): ResponsesFuncti
  * consume the wrapped scripts unchanged.
  */
 
-type AnyDef = ToolDefinition<any, any, any, string, string, string>;
+type AnyDef = ToolDefinition<any, any, string, string, string>;
 /**
  * Map a script's `ToolDefinition` to its consumer-facing wrapped form,
  * narrowed against the connector's `connectionResolvers` map. The wrapped
@@ -397,11 +388,11 @@ type AnyDef = ToolDefinition<any, any, any, string, string, string>;
  * `RunOptions.connections.<slot>` is narrowed per the slot's resolver
  * array via `ConnectionValueFor`.
  */
-type WrappedScript<D extends AnyDef, TResolvers extends ConnectionResolversMap> = D extends ToolDefinitionNone<infer TIn, infer TOut, infer _TInputDependencies, infer _TName> ? Omit<D, "run"> & {
+type WrappedScript<D extends AnyDef, TResolvers extends ConnectionResolversMap> = D extends ToolDefinitionNone<infer TIn, infer TOut, infer _TName> ? Omit<D, "run"> & {
     run: (input: z.infer<TIn>, opts?: RunOptionsNone) => Promise<z.infer<TOut>>;
-} : D extends ToolDefinitionSingle<infer TIn, infer TOut, infer _TInputDependencies, infer _TName, infer TKey> ? Omit<D, "run"> & {
+} : D extends ToolDefinitionSingle<infer TIn, infer TOut, infer _TName, infer TKey> ? Omit<D, "run"> & {
     run: (input: z.infer<TIn>, opts: RunOptionsSingle<ConnectionValueForKey<TResolvers, TKey>>) => Promise<z.infer<TOut>>;
-} : D extends ToolDefinitionMulti<infer TIn, infer TOut, infer _TInputDependencies, infer _TName, infer TSlots, infer TKey> ? Omit<D, "run"> & {
+} : D extends ToolDefinitionMulti<infer TIn, infer TOut, infer _TName, infer TSlots, infer TKey> ? Omit<D, "run"> & {
     run: (input: z.infer<TIn>, opts: {
         connection?: never;
         connections: {
@@ -458,10 +449,9 @@ declare function defineConnector<TScripts extends Record<string, AnyDef>, const
  * to `run`. The returned definition mirrors the input one-to-one.
  */
 
-type AnyInputDependencies = Readonly<Record<string, unknown>>;
-declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string>(config: DefineToolConfigNone<TIn, TOut, TInputDependencies, TName>): ToolDefinitionNone<TIn, TOut, TInputDependencies, TName>;
-declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string, const TKey extends string = string>(config: DefineToolConfigSingle<TIn, TOut, TInputDependencies, TName, TKey>): ToolDefinitionSingle<TIn, TOut, TInputDependencies, TName, TKey>;
-declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string, const TSlots extends string = string, const TKey extends string = string>(config: DefineToolConfigMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>): ToolDefinitionMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>;
+declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string>(config: DefineToolConfigNone<TIn, TOut, TName>): ToolDefinitionNone<TIn, TOut, TName>;
+declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string, const TKey extends string = string>(config: DefineToolConfigSingle<TIn, TOut, TName, TKey>): ToolDefinitionSingle<TIn, TOut, TName, TKey>;
+declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string, const TSlots extends string = string, const TKey extends string = string>(config: DefineToolConfigMulti<TIn, TOut, TName, TSlots, TKey>): ToolDefinitionMulti<TIn, TOut, TName, TSlots, TKey>;
 
 /**
  * `handleIfScriptMain(meta, definition, opts?)` — per-script CLI execution
@@ -515,6 +505,13 @@ declare function handleIfScriptMain<D extends AnyToolDefinition>(meta: ImportMet
  *      - `<bin> mcp`                           — boot a local MCP stdio
  *                                                server exposing every
  *                                                script.
+ *      - `<bin> skill`                         — print the connector's
+ *                                                `SKILL.md` to stdout.
+ *      - `<bin> reference [<name>]`            — print
+ *                                                `references/<name>.md` to
+ *                                                stdout, or list all
+ *                                                available references when
+ *                                                called with no name.
  *      - `<bin>`, `<bin> --help`, `<bin> -h`   — usage to stdout.
  *      - `<bin> run <script> --help`           — per-script help (input
  *                                                schema + required env

package/dist/index.d.ts

@@ -30,24 +30,6 @@ type Replace<S extends string, From extends string, To extends string> = S exten
  */
 type EnvFromKey<K extends string> = Uppercase<Replace<K, "-", "_">>;
 
-/**
- * A Zapier policy statement. Carried on the `ToolDefinition` for in-process
- * governance consumers (policy engines that wrap `script.run` before HTTP).
- * Not propagated to MCP `_meta` — only `inputDependencies` is published over
- * the wire (`_meta["zapier:inputDependencies"]`) by `toMcpTool` /
- * `toMcpServerTool`.
- */
-interface Statement {
-    effect: "allow" | "ask" | "deny";
-    permissions: ReadonlyArray<string>;
-    resources: ReadonlyArray<string>;
-    conditions?: ReadonlyArray<{
-        path: ReadonlyArray<string>;
-        operator: string;
-        value: unknown;
-    }>;
-    label?: string;
-}
 /**
  * Single-credential resolver: the resolver's `name` IS the credential
  * descriptor. `resolve` receives the credential as a plain `string` —
@@ -68,6 +50,12 @@ interface Statement {
 interface SingleConnectionResolver<TName extends string = string> {
     readonly name: TName;
     readonly keySuffixes?: undefined;
+    /**
+     * npm package names that must be installed for this resolver to function
+     * at runtime. Declared here so `--help` can check availability and tell
+     * the agent which packages to install before using this resolver.
+     */
+    readonly optionalPackages?: readonly string[];
     resolve: (credential: string) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
 }
 /**
@@ -86,6 +74,12 @@ interface SingleConnectionResolver<TName extends string = string> {
 interface MultiConnectionResolver<TName extends string = string, TSuffixes extends readonly string[] = readonly string[]> {
     readonly name: TName;
     readonly keySuffixes: TSuffixes;
+    /**
+     * npm package names that must be installed for this resolver to function
+     * at runtime. Declared here so `--help` can check availability and tell
+     * the agent which packages to install before using this resolver.
+     */
+    readonly optionalPackages?: readonly string[];
     resolve: (credentials: Record<TSuffixes[number], string>) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
 }
 /** Either resolver shape. */
@@ -160,43 +154,45 @@ interface RunOptionsMulti<TSlots extends string = string, TPerSlot extends Recor
     connections: TPerSlot;
 }
 type RunOptions<TSlots extends string = string, TValue = ConnectionValue, TPerSlot extends Record<TSlots, ConnectionValue> = Record<TSlots, ConnectionValue>> = RunOptionsNone | RunOptionsSingle<TValue> | RunOptionsMulti<TSlots, TPerSlot>;
+/** Author-facing context for a credential-free script. */
+interface ContextNone {
+    fetch?: undefined;
+    connections?: undefined;
+}
 /** Author-facing context for a single-connection script. */
 interface ContextSingle {
     fetch: typeof globalThis.fetch;
+    connections?: never;
 }
 /** Author-facing context for a multi-connection script. */
 interface ContextMulti<TSlots extends string = string> {
+    fetch?: never;
     connections: Record<TSlots, typeof globalThis.fetch>;
 }
-type AnyInputDependencies$1 = Readonly<Record<string, unknown>>;
-/** When authoring omits `inputDependencies`, the definition value is `undefined`. */
-type InputDependenciesValue<T> = [T] extends [undefined] ? undefined : T;
-interface DefineToolConfigBase<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
+interface DefineToolConfigBase<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string> {
     name: TName;
     title: string;
     description: string;
     inputSchema: TIn;
     outputSchema: TOut;
     annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
-    statements?: ReadonlyArray<Statement>;
-    inputDependencies?: TInputDependencies;
 }
-interface DefineToolConfigNone<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+interface DefineToolConfigNone<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string> extends DefineToolConfigBase<TIn, TOut, TName> {
     connection?: never;
     connections?: never;
-    run: (input: z.infer<TIn>) => Promise<z.infer<TOut>>;
+    run: (input: z.infer<TIn>, ctx?: ContextNone) => Promise<unknown>;
 }
-interface DefineToolConfigSingle<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+interface DefineToolConfigSingle<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TName> {
     connection: TKey;
     connections?: never;
-    run: (input: z.infer<TIn>, ctx: ContextSingle) => Promise<z.infer<TOut>>;
+    run: (input: z.infer<TIn>, ctx: ContextSingle) => Promise<unknown>;
 }
-interface DefineToolConfigMulti<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string, TSlots extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+interface DefineToolConfigMulti<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string, TSlots extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TName> {
     connection?: never;
     connections: Record<TSlots, TKey>;
-    run: (input: z.infer<TIn>, ctx: ContextMulti<TSlots>) => Promise<z.infer<TOut>>;
+    run: (input: z.infer<TIn>, ctx: ContextMulti<TSlots>) => Promise<unknown>;
 }
-interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
+interface ToolDefinitionBase<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TName extends string> {
     readonly kind: "tool";
     readonly name: TName;
     readonly title: string;
@@ -204,30 +200,26 @@ interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInp
     inputSchema: TIn;
     outputSchema: TOut;
     readonly annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
-    readonly statements: ReadonlyArray<Statement> | undefined;
-    inputDependencies: InputDependenciesValue<TInputDependencies>;
 }
-interface ToolDefinitionNone<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+interface ToolDefinitionNone<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TName extends string = string> extends ToolDefinitionBase<TIn, TOut, TName> {
     readonly connection?: undefined;
     readonly connections?: undefined;
-    /** Author's run; the wrapper passes `input` directly. */
-    run: (input: z.infer<TIn>) => Promise<z.infer<TOut>>;
+    run: (input: z.infer<TIn>, ctx?: ContextNone) => Promise<z.infer<TOut>>;
 }
-interface ToolDefinitionSingle<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+interface ToolDefinitionSingle<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TName extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TName> {
     readonly connection: TKey;
     readonly connections?: undefined;
     run: (input: z.infer<TIn>, ctx: ContextSingle) => Promise<z.infer<TOut>>;
 }
-interface ToolDefinitionMulti<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TSlots extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+interface ToolDefinitionMulti<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TName extends string = string, TSlots extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TName> {
     readonly connection?: undefined;
     readonly connections: Record<TSlots, TKey>;
     run: (input: z.infer<TIn>, ctx: ContextMulti<TSlots>) => Promise<z.infer<TOut>>;
 }
-type ToolDefinition<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TSlots extends string = string, TKey extends string = string> = ToolDefinitionNone<TIn, TOut, TInputDependencies, TName> | ToolDefinitionSingle<TIn, TOut, TInputDependencies, TName, TKey> | ToolDefinitionMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>;
+type ToolDefinition<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TName extends string = string, TSlots extends string = string, TKey extends string = string> = ToolDefinitionNone<TIn, TOut, TName> | ToolDefinitionSingle<TIn, TOut, TName, TKey> | ToolDefinitionMulti<TIn, TOut, TName, TSlots, TKey>;
 /** Wide author-side `run` signature for polymorphic walks. */
 type AnyToolDefinitionRun = (input: any, ctx?: any) => Promise<any>;
-type AnyToolDefinition = Omit<ToolDefinitionBase<z.ZodType, z.ZodType, any, string>, "run" | "inputDependencies"> & {
-    inputDependencies: AnyInputDependencies$1 | undefined;
+type AnyToolDefinition = Omit<ToolDefinitionBase<z.ZodObject<z.ZodRawShape>, z.ZodObject<z.ZodRawShape>, string>, "run"> & {
     run: AnyToolDefinitionRun;
     readonly connection?: string | undefined;
     readonly connections?: Record<string, string> | undefined;
@@ -330,10 +322,9 @@ declare function toChatCompletionTool(definition: AnyToolDefinition): ChatComple
 interface McpRegisterToolConfig {
     title?: string;
     description?: string;
-    inputSchema?: z.ZodType;
-    outputSchema?: z.ZodType;
+    inputSchema?: z.ZodObject<z.ZodRawShape>;
+    outputSchema?: z.ZodObject<z.ZodRawShape>;
     annotations?: ToolAnnotations;
-    _meta?: Record<string, unknown>;
 }
 /**
  * Build the `McpServer.registerTool` config for a `ToolDefinition`.
@@ -389,7 +380,7 @@ declare function toResponsesTool(definition: AnyToolDefinition): ResponsesFuncti
  * consume the wrapped scripts unchanged.
  */
 
-type AnyDef = ToolDefinition<any, any, any, string, string, string>;
+type AnyDef = ToolDefinition<any, any, string, string, string>;
 /**
  * Map a script's `ToolDefinition` to its consumer-facing wrapped form,
  * narrowed against the connector's `connectionResolvers` map. The wrapped
@@ -397,11 +388,11 @@ type AnyDef = ToolDefinition<any, any, any, string, string, string>;
  * `RunOptions.connections.<slot>` is narrowed per the slot's resolver
  * array via `ConnectionValueFor`.
  */
-type WrappedScript<D extends AnyDef, TResolvers extends ConnectionResolversMap> = D extends ToolDefinitionNone<infer TIn, infer TOut, infer _TInputDependencies, infer _TName> ? Omit<D, "run"> & {
+type WrappedScript<D extends AnyDef, TResolvers extends ConnectionResolversMap> = D extends ToolDefinitionNone<infer TIn, infer TOut, infer _TName> ? Omit<D, "run"> & {
     run: (input: z.infer<TIn>, opts?: RunOptionsNone) => Promise<z.infer<TOut>>;
-} : D extends ToolDefinitionSingle<infer TIn, infer TOut, infer _TInputDependencies, infer _TName, infer TKey> ? Omit<D, "run"> & {
+} : D extends ToolDefinitionSingle<infer TIn, infer TOut, infer _TName, infer TKey> ? Omit<D, "run"> & {
     run: (input: z.infer<TIn>, opts: RunOptionsSingle<ConnectionValueForKey<TResolvers, TKey>>) => Promise<z.infer<TOut>>;
-} : D extends ToolDefinitionMulti<infer TIn, infer TOut, infer _TInputDependencies, infer _TName, infer TSlots, infer TKey> ? Omit<D, "run"> & {
+} : D extends ToolDefinitionMulti<infer TIn, infer TOut, infer _TName, infer TSlots, infer TKey> ? Omit<D, "run"> & {
     run: (input: z.infer<TIn>, opts: {
         connection?: never;
         connections: {
@@ -458,10 +449,9 @@ declare function defineConnector<TScripts extends Record<string, AnyDef>, const
  * to `run`. The returned definition mirrors the input one-to-one.
  */
 
-type AnyInputDependencies = Readonly<Record<string, unknown>>;
-declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string>(config: DefineToolConfigNone<TIn, TOut, TInputDependencies, TName>): ToolDefinitionNone<TIn, TOut, TInputDependencies, TName>;
-declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string, const TKey extends string = string>(config: DefineToolConfigSingle<TIn, TOut, TInputDependencies, TName, TKey>): ToolDefinitionSingle<TIn, TOut, TInputDependencies, TName, TKey>;
-declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string, const TSlots extends string = string, const TKey extends string = string>(config: DefineToolConfigMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>): ToolDefinitionMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>;
+declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string>(config: DefineToolConfigNone<TIn, TOut, TName>): ToolDefinitionNone<TIn, TOut, TName>;
+declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string, const TKey extends string = string>(config: DefineToolConfigSingle<TIn, TOut, TName, TKey>): ToolDefinitionSingle<TIn, TOut, TName, TKey>;
+declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, const TName extends string = string, const TSlots extends string = string, const TKey extends string = string>(config: DefineToolConfigMulti<TIn, TOut, TName, TSlots, TKey>): ToolDefinitionMulti<TIn, TOut, TName, TSlots, TKey>;
 
 /**
  * `handleIfScriptMain(meta, definition, opts?)` — per-script CLI execution
@@ -515,6 +505,13 @@ declare function handleIfScriptMain<D extends AnyToolDefinition>(meta: ImportMet
  *      - `<bin> mcp`                           — boot a local MCP stdio
  *                                                server exposing every
  *                                                script.
+ *      - `<bin> skill`                         — print the connector's
+ *                                                `SKILL.md` to stdout.
+ *      - `<bin> reference [<name>]`            — print
+ *                                                `references/<name>.md` to
+ *                                                stdout, or list all
+ *                                                available references when
+ *                                                called with no name.
  *      - `<bin>`, `<bin> --help`, `<bin> -h`   — usage to stdout.
  *      - `<bin> run <script> --help`           — per-script help (input
  *                                                schema + required env

package/dist/index.js

@@ -4,6 +4,7 @@ function defineConnectionResolver(resolver) {
 }
 var zapierConnectionResolver = defineConnectionResolver({
   name: "zapier-connection-id",
+  optionalPackages: ["@zapier/zapier-sdk"],
   resolve: async (connectionId) => {
     const { buildZapierFetch } = await import("./build-zapier-fetch-DWCYBAF4.js");
     return buildZapierFetch(connectionId);
@@ -23,6 +24,9 @@ function defineBearerTokenResolver(opts = {}) {
   });
 }
 
+// src/normalize-connections.ts
+import { createRequire } from "module";
+
 // src/connection-key.ts
 function envFromKey(name) {
   return name.toUpperCase().replace(/-/g, "_");
@@ -162,23 +166,70 @@ function buildRunOptionsFromEnv(definition, env, connectionResolvers) {
   }
   return { connections: wrapped };
 }
-function formatHelpForConnections(definition, connectionResolvers) {
+function isPackageInstalled(name) {
+  try {
+    createRequire(import.meta.url).resolve(name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function formatHelpForConnections(definition, connectionResolvers, env) {
   const slots = [...walkConnections(definition)];
   if (slots.length === 0) return [];
   const lines = [];
   lines.push(
-    "Connections (set as environment variables; do NOT pass via CLI argument):"
+    "Auth (set as environment variables; do NOT pass via CLI argument):"
   );
+  const notReadySlots = [];
   for (const { slotName, connectionKey } of slots) {
     const resolvers = resolversForKey(connectionResolvers, connectionKey);
-    const heading = slotName ? `  ${slotName} (${connectionKey}):` : `  ${connectionKey}:`;
-    lines.push(heading);
+    if (slotName !== void 0) {
+      lines.push(`  ${slotName} (${connectionKey}):`);
+    }
+    const resolverIndent = slotName !== void 0 ? "    " : "  ";
+    const varIndent = slotName !== void 0 ? "      " : "    ";
+    let slotHasReady = false;
     for (const resolver of resolvers) {
-      lines.push(`    ${resolver.name}:`);
-      for (const envVar of envVarsFor(slotName, connectionKey, resolver)) {
-        lines.push(`      ${envVar}`);
+      const vars = envVarsFor(slotName, connectionKey, resolver);
+      let isReady = false;
+      let missingPkgs = [];
+      if (env !== void 0) {
+        const envVarsOk = vars.every(
+          (k) => typeof env[k] === "string" && env[k] !== ""
+        );
+        if (envVarsOk) isReady = true;
+        missingPkgs = (resolver.optionalPackages ?? []).filter(
+          (pkg) => !isPackageInstalled(pkg)
+        );
+      }
+      const markReady = isReady && !slotHasReady;
+      if (markReady) slotHasReady = true;
+      const resolverSuffix = env !== void 0 && markReady ? "  [READY \u2014 use this]" : "";
+      lines.push(`${resolverIndent}${resolver.name}:${resolverSuffix}`);
+      for (const envVar of vars) {
+        const varSuffix = env !== void 0 ? env[envVar] !== void 0 && env[envVar] !== "" ? "  [set]" : "  [not set]" : "";
+        lines.push(`${varIndent}${envVar}${varSuffix}`);
+      }
+      if (env !== void 0) {
+        for (const pkg of resolver.optionalPackages ?? []) {
+          if (missingPkgs.includes(pkg)) {
+            lines.push(
+              `${varIndent}${pkg}  [not installed \u2014 run \`npm install ${pkg}\` first]`
+            );
+          } else {
+            lines.push(`${varIndent}${pkg}  [installed]`);
+          }
+        }
       }
     }
+    if (env !== void 0 && !slotHasReady) {
+      notReadySlots.push(slotName ?? connectionKey);
+    }
+  }
+  if (env !== void 0 && notReadySlots.length > 0) {
+    const label = notReadySlots.length === slots.length ? "No option is ready" : `No option is ready for slot${notReadySlots.length > 1 ? "s" : ""} ${notReadySlots.join(", ")}`;
+    lines.push(`${label} \u2014 set one of the env vars above.`);
   }
   return lines;
 }
@@ -263,8 +314,8 @@ function ensureConnectionValue(scriptName, slotName, connectionKey, value) {
   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;
+  const hasConnection = opts !== void 0 && "connection" in opts && opts.connection !== void 0;
+  const hasConnections = opts !== void 0 && "connections" in opts && opts.connections !== void 0;
   if (definition.connection === void 0 && definition.connections === void 0) {
     if (hasConnection || hasConnections) {
       throw new Error(
@@ -273,6 +324,11 @@ async function buildContext(definition, opts, connectionResolvers) {
     }
     return {};
   }
+  if (opts === void 0) {
+    throw new Error(
+      `ToolDefinition "${definition.name}": \`RunOptions\` is required \u2014 pass \`{ connection: ... }\` or \`{ connections: ... }\`.`
+    );
+  }
   if (hasConnection && hasConnections) {
     throw new Error(
       `ToolDefinition "${definition.name}": \`RunOptions\` sets both \`connection\` and \`connections\`. Use one or the other.`
@@ -290,7 +346,7 @@ async function buildContext(definition, opts, connectionResolvers) {
       definition.name,
       void 0,
       connectionKey,
-      opts.connection
+      "connection" in opts ? opts.connection : void 0
     );
     const fetch = await resolveSlotFetch(
       definition.name,
@@ -307,12 +363,12 @@ async function buildContext(definition, opts, connectionResolvers) {
       `ToolDefinition "${definition.name}" is multi-connection (slots: ${declaredSlots.join(", ")}) \u2014 call with \`{ connections: { ... } }\`, not \`{ connection: ... }\`.`
     );
   }
-  if (!hasConnections) {
+  const provided = opts.connections;
+  if (provided === void 0) {
     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)
   );
@@ -366,28 +422,18 @@ function toChatCompletionTool(definition) {
 
 // src/surfaces/to-mcp-server-tool.ts
 function toMcpServerTool(definition) {
-  const config = {
+  return {
     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,
@@ -396,8 +442,7 @@ function toMcpTool(definition) {
     outputSchema: z2.toJSONSchema(
       definition.outputSchema
     ),
-    annotations: definition.annotations,
-    ...Object.keys(meta).length > 0 ? { _meta: meta } : {}
+    annotations: definition.annotations
   };
 }
 
@@ -411,24 +456,9 @@ function toResponsesTool(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(input, ctx);
   };
   return { ...definition, run: wrappedRun };
 }
@@ -438,6 +468,11 @@ function defineConnector(config) {
   validateConnectionResolvers(scriptsAsAny, connectionResolvers);
   const wrapped = {};
   for (const [key, definition] of Object.entries(scriptsAsAny)) {
+    if (key !== definition.name) {
+      throw new Error(
+        `defineConnector: script key "${key}" must match its tool name \u2014 got name "${definition.name}". Rename the key to "${definition.name}" or update the tool's name field.`
+      );
+    }
     wrapped[key] = wrapScriptWithResolvers(definition, connectionResolvers);
   }
   return {
@@ -507,6 +542,12 @@ function defineTool(config) {
       validateConnectionKey(config.name, value);
     }
   }
+  const authorRun = config.run;
+  const wrappedRun = async (input, ctx) => {
+    const validated = config.inputSchema.parse(input);
+    const result = await authorRun(validated, ctx);
+    return config.outputSchema.parse(result);
+  };
   const base = {
     kind: "tool",
     name: config.name,
@@ -515,9 +556,7 @@ function defineTool(config) {
     inputSchema: config.inputSchema,
     outputSchema: config.outputSchema,
     annotations: config.annotations,
-    statements: config.statements,
-    inputDependencies: config.inputDependencies,
-    run: config.run
+    run: wrappedRun
   };
   if (hasSingular) base.connection = config.connection;
   if (hasPlural) base.connections = config.connections;
@@ -661,10 +700,73 @@ async function runDispatchCliBody(connector, opts) {
     });
     return;
   }
+  if (first === "skill") {
+    if (!opts.meta) {
+      throw new Error(
+        "runDispatchCliBody: `skill` requires `meta` in options (the connector's `import.meta` from `cli.ts`)."
+      );
+    }
+    const cliPath = fileURLToPath2(opts.meta.url);
+    const connectorDir = path2.dirname(cliPath);
+    const skillPath = path2.join(connectorDir, "SKILL.md");
+    let content;
+    try {
+      content = await fs2.readFile(skillPath, "utf8");
+    } catch {
+      throw new Error(
+        `SKILL.md not found at ${skillPath}. Ensure the connector ships a SKILL.md.`
+      );
+    }
+    opts.stdout.write(resolveRelativeLinks(content, connectorDir));
+    return;
+  }
+  if (first === "reference") {
+    if (!opts.meta) {
+      throw new Error(
+        "runDispatchCliBody: `reference` requires `meta` in options (the connector's `import.meta` from `cli.ts`)."
+      );
+    }
+    const cliPath = fileURLToPath2(opts.meta.url);
+    const connectorDir = path2.dirname(cliPath);
+    const refsDir = path2.join(connectorDir, "references");
+    const name = args[1];
+    if (!name) {
+      let entries;
+      try {
+        const files = await fs2.readdir(refsDir);
+        entries = files.filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -".md".length));
+      } catch {
+        entries = [];
+      }
+      if (entries.length === 0) {
+        opts.stdout.write(`Available references: <none>
+`);
+      } else {
+        opts.stdout.write(`Available references:
+`);
+        for (const entry of entries) {
+          opts.stdout.write(`  ${entry}
+`);
+        }
+      }
+      return;
+    }
+    const refPath = path2.join(refsDir, `${name}.md`);
+    let content;
+    try {
+      content = await fs2.readFile(refPath, "utf8");
+    } catch {
+      throw new Error(
+        `Reference file not found at ${refPath}. Ensure the connector ships \`references/${name}.md\`.`
+      );
+    }
+    opts.stdout.write(resolveRelativeLinks(content, refsDir));
+    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.`
+      `Unknown command "${first}". Use \`run <script>\` to dispatch a script (available: ${Object.keys(scripts).join(", ") || "<none>"}), \`mcp\` to boot a local MCP server, \`skill\` to print SKILL.md, or \`reference [<name>]\` to print or list reference docs.`
     );
   }
   const scriptName = args[1];
@@ -691,6 +793,17 @@ async function runDispatchCliBody(connector, opts) {
     invocation
   });
 }
+function resolveRelativeLinks(content, baseDir) {
+  return content.replace(
+    /(!?\[([^\]]*)\])\(([^)]+)\)/g,
+    (match, prefix, _alt, url) => {
+      if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("file:") || url.startsWith("#") || url.startsWith("/")) {
+        return match;
+      }
+      return `${prefix}(${path2.resolve(baseDir, url)})`;
+    }
+  );
+}
 async function resolvePackageName(meta) {
   if (!meta?.url) return void 0;
   try {
@@ -709,6 +822,8 @@ function printUsage(scripts, out, packageName) {
     `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)
+       <bin> skill                  (print SKILL.md to stdout)
+       <bin> reference [<name>]     (print references/<name>.md, or list all)
 
 `
   );
@@ -821,12 +936,13 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   if (helpRequested) {
     io.stdout.write(
       buildHelpText(wrappedScript, connectionResolvers, {
-        invocation: io.invocation
+        invocation: io.invocation,
+        env: io.env
       })
     );
     return;
   }
-  const raw = positional ?? await new Response(io.stdin).text();
+  const raw = positional ?? await readStdinInput(io.stdin, wrappedScript.name);
   if (raw.trim().length === 0) {
     throw new Error(
       `Missing JSON input for "${wrappedScript.name}". Pass it as a positional argument or via stdin.`
@@ -838,6 +954,14 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const result = await wrappedScript.run(input, runOpts);
   io.stdout.write(JSON.stringify(result, null, 2) + "\n");
 }
+async function readStdinInput(stdin, scriptName) {
+  if (stdin.isTTY) {
+    throw new Error(
+      `Missing JSON input for "${scriptName}". Pass it as a positional argument or pipe it via stdin.`
+    );
+  }
+  return new Response(stdin).text();
+}
 function buildHelpText(definition, connectionResolvers, opts = {}) {
   const lines = [];
   const description = definition.description.split("\n")[0]?.trim() ?? "";
@@ -861,7 +985,8 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   }
   const connectionsBlock = formatHelpForConnections(
     definition,
-    connectionResolvers
+    connectionResolvers,
+    opts.env
   );
   if (connectionsBlock.length > 0) {
     lines.push(...connectionsBlock);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/connectors-sdk",
-  "version": "0.1.0-experimental.1",
+  "version": "0.1.0-experimental.10",
   "description": "SDK for building Zapier connectors. Provides the authoring primitives and execution surfaces for connector scripts.",
   "license": "Elastic-2.0",
   "type": "module",
@@ -24,9 +24,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup"
-  },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@zapier/zapier-sdk": "^0.59.0",
@@ -44,5 +41,8 @@
     "type": "git",
     "url": "https://gitlab.com/zapier/team-agents-platform/connectors.git",
     "directory": "packages/connectors-sdk"
+  },
+  "scripts": {
+    "build": "tsup"
   }
-}
+}