@zapier/connectors-sdk 0.1.0-experimental.11 → 0.1.0-experimental.13

package/README.internal.md

@@ -48,16 +48,16 @@ import {
 
 A **surface** is how a `ToolDefinition` is exposed to a consumer. **Registration surfaces** publish tool metadata; **execution surfaces** run a tool.
 
-| Surface                       | Kind         | Helper                         | Surface shape / behavior                                                                     |
-| ----------------------------- | ------------ | ------------------------------ | -------------------------------------------------------------------------------------------- |
-| MCP `tools/list` (descriptor) | registration | `toMcpTool`                    | Wire-format `Tool` (JSON Schema'd `inputSchema`, optional `_meta`)                           |
-| MCP `McpServer.registerTool`  | registration | `toMcpServerTool`              | `registerTool` config (Zod schemas pass-through, optional `_meta`)                           |
-| OpenAI Chat Completions       | registration | `toChatCompletionTool`         | `{ type: "function", function: { name, description, parameters } }`                          |
-| OpenAI Responses              | registration | `toResponsesTool`              | `{ type: "function", name, description, parameters }`                                        |
-| Per-script CLI                | execution    | `handleIfScriptMain`           | argv/stdin JSON in → wrapped `script.run` → JSON stdout                                      |
-| Connector bin                 | execution    | `runDispatchCli`               | `<bin> run <script> [args…]` → per-script CLI; `<bin> mcp` → local MCP server                |
-| Local MCP server              | execution    | `runDispatchCli` (`<bin> mcp`) | Stdio MCP server registering every script as a native MCP tool (`tools/list` + `tools/call`) |
-| In-process run                | execution    | `script.run` / named export    | Typed input + `RunOptions` → output                                                          |
+| Surface                       | Kind         | Helper                         | Surface shape / behavior                                                                                                                                       |
+| ----------------------------- | ------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| MCP `tools/list` (descriptor) | registration | `toMcpTool`                    | Wire-format `Tool` (JSON Schema'd `inputSchema`, optional `_meta`)                                                                                             |
+| MCP `McpServer.registerTool`  | registration | `toMcpServerTool`              | `registerTool` config (Zod schemas pass-through, optional `_meta`)                                                                                             |
+| OpenAI Chat Completions       | registration | `toChatCompletionTool`         | `{ type: "function", function: { name, description, parameters } }`                                                                                            |
+| OpenAI Responses              | registration | `toResponsesTool`              | `{ type: "function", name, description, parameters }`                                                                                                          |
+| Per-script CLI                | execution    | `handleIfScriptMain`           | argv/stdin JSON in → wrapped `script.run` → JSON stdout                                                                                                        |
+| Connector bin                 | execution    | `runDispatchCli`               | `<bin> run <script> [args…]` → per-script CLI; `<bin> mcp` → local MCP server                                                                                  |
+| Local MCP server              | execution    | `runDispatchCli` (`<bin> mcp`) | Stdio MCP server: every script as a tool (`tools/list` + `tools/call`), plus `SKILL.md` + `references/*.md` as resources (`resources/list` + `resources/read`) |
+| In-process run                | execution    | `script.run` / named export    | Typed input + `RunOptions` → output                                                                                                                            |
 
 ## Authoring a script — `defineTool`
 
@@ -353,7 +353,8 @@ Reached through the bundled CLI as `npx @zapier/<x>-connector mcp` — no per-ap
 1. Builds an in-memory registry keyed by `script.name`, with each entry holding the script and `RunOptions` resolved once via `buildRunOptionsFromEnv` against the connector's resolvers.
 2. Resolves server identity (`name` / `version`) from the `package.json` adjacent to the connector's `cli.ts` (via `meta.url`).
 3. For each script, calls `server.registerTool(script.name, toMcpServerTool(script), cb)` — `McpServer` handles `tools/list` and runs the Zod input parse before dispatching to `script.run(input, runOpts)`. The callback returns the result as both `structuredContent` and a JSON-stringified text part.
-4. Connects via `StdioServerTransport` and writes a one-line ready banner to stderr.
+4. For each bundled doc — `SKILL.md` and each `references/*.md` (discovered recursively) — calls `server.registerResource(...)` with a stable `connector://<slug>/…` URI and `text/markdown` type. Content is re-read from disk on each `resources/read` (link-rewriting included, so it matches the CLI's `skill` / `reference` output). Skipped entirely when `meta.url` is absent or the connector ships no docs, so the `resources` capability is only advertised when there is something to serve.
+5. Connects via `StdioServerTransport` and writes a one-line ready banner to stderr.
 
 ```bash
 NOTION_TOKEN=secret_xxx npx @zapier/notion-connector mcp

package/dist/index.cjs

@@ -706,14 +706,74 @@ function defineTool(config) {
 var import_zod3 = require("zod");
 
 // src/surfaces/run-dispatch-cli.ts
-var fs2 = __toESM(require("fs/promises"), 1);
-var path2 = __toESM(require("path"), 1);
-var import_node_url2 = require("url");
+var fs3 = __toESM(require("fs/promises"), 1);
+var path3 = __toESM(require("path"), 1);
+var import_node_url3 = require("url");
 
-// src/surfaces/serve-mcp-stdio.ts
+// src/surfaces/connector-docs.ts
 var fs = __toESM(require("fs/promises"), 1);
 var path = __toESM(require("path"), 1);
 var import_node_url = require("url");
+var SKILL_FILENAME = "SKILL.md";
+var REFERENCES_DIRNAME = "references";
+function connectorDirFromMeta(meta) {
+  const dir = path.dirname((0, import_node_url.fileURLToPath)(meta.url));
+  return path.basename(dir) === "dist" ? path.dirname(dir) : dir;
+}
+function skillPath(connectorDir) {
+  return path.join(connectorDir, SKILL_FILENAME);
+}
+function referencePath(connectorDir, name) {
+  return path.join(connectorDir, REFERENCES_DIRNAME, `${name}.md`);
+}
+async function loadSkillDoc(connectorDir) {
+  return loadDoc(skillPath(connectorDir), connectorDir);
+}
+async function listReferenceNames(connectorDir) {
+  try {
+    const entries = await fs.readdir(
+      path.join(connectorDir, REFERENCES_DIRNAME),
+      { recursive: true }
+    );
+    return entries.filter((entry) => entry.endsWith(".md")).map((entry) => toPosix(entry).slice(0, -".md".length));
+  } catch {
+    return [];
+  }
+}
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+async function loadReferenceDoc(connectorDir, name) {
+  return loadDoc(
+    referencePath(connectorDir, name),
+    path.join(connectorDir, REFERENCES_DIRNAME)
+  );
+}
+async function loadDoc(filePath, baseDir) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch {
+    return void 0;
+  }
+  return { path: filePath, content: resolveRelativeLinks(raw, baseDir) };
+}
+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}(${path.resolve(baseDir, url)})`;
+    }
+  );
+}
+
+// src/surfaces/serve-mcp-stdio.ts
+var fs2 = __toESM(require("fs/promises"), 1);
+var path2 = __toESM(require("path"), 1);
+var import_node_url2 = require("url");
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 function buildMcpRegistry(scripts, env, connectionResolvers) {
@@ -734,9 +794,9 @@ async function resolveServerInfo(meta) {
     return { name: FALLBACK_SERVER_NAME, version: FALLBACK_SERVER_VERSION };
   }
   try {
-    const cliPath = (0, import_node_url.fileURLToPath)(meta.url);
-    const pkgPath = path.join(path.dirname(cliPath), "package.json");
-    const raw = await fs.readFile(pkgPath, "utf8");
+    const cliPath = (0, import_node_url2.fileURLToPath)(meta.url);
+    const pkgPath = path2.join(path2.dirname(cliPath), "package.json");
+    const raw = await fs2.readFile(pkgPath, "utf8");
     const pkg = JSON.parse(raw);
     return {
       name: typeof pkg.name === "string" ? pkg.name : FALLBACK_SERVER_NAME,
@@ -746,9 +806,8 @@ async function resolveServerInfo(meta) {
     return { name: FALLBACK_SERVER_NAME, version: FALLBACK_SERVER_VERSION };
   }
 }
-async function serveMcpStdio(meta, connector, opts = {}) {
+async function buildMcpServer(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);
@@ -772,10 +831,69 @@ async function serveMcpStdio(meta, connector, opts = {}) {
       }
     );
   }
+  if (meta.url) {
+    await registerDocResources(
+      server,
+      connectorSlug(serverInfo.name),
+      connectorDirFromMeta(meta)
+    );
+  }
+  return { server, serverInfo };
+}
+async function serveMcpStdio(meta, connector, opts = {}) {
+  const stderr = opts.stderr ?? process.stderr;
+  const { server, serverInfo } = await buildMcpServer(meta, connector, opts);
   await server.connect(new import_stdio.StdioServerTransport());
   stderr.write(`[${serverInfo.name}] MCP server ready on stdio.
 `);
 }
+var MARKDOWN_MIME_TYPE = "text/markdown";
+function connectorSlug(serverName) {
+  const basename2 = serverName.split("/").pop() ?? serverName;
+  return basename2.replace(/-connector$/, "") || basename2;
+}
+async function registerDocResources(server, slug, connectorDir) {
+  const skill = await loadSkillDoc(connectorDir);
+  if (skill) {
+    server.registerResource(
+      SKILL_FILENAME,
+      `connector://${slug}/${SKILL_FILENAME}`,
+      {
+        title: "Skill guide",
+        description: "The connector's SKILL.md: when to use it, auth setup, and the script catalog.",
+        mimeType: MARKDOWN_MIME_TYPE
+      },
+      readDoc(() => loadSkillDoc(connectorDir), skill.path)
+    );
+  }
+  for (const name of await listReferenceNames(connectorDir)) {
+    const resourceName = `${REFERENCES_DIRNAME}/${name}.md`;
+    const uriPath = name.split("/").map(encodeURIComponent).join("/");
+    server.registerResource(
+      resourceName,
+      `connector://${slug}/${REFERENCES_DIRNAME}/${uriPath}.md`,
+      {
+        title: `Reference: ${name}`,
+        description: `Durable per-app knowledge from references/${name}.md (API gotchas, encodings, edge cases).`,
+        mimeType: MARKDOWN_MIME_TYPE
+      },
+      readDoc(() => loadReferenceDoc(connectorDir, name), resourceName)
+    );
+  }
+}
+function readDoc(load, label) {
+  return async (uri) => {
+    const doc = await load();
+    if (!doc) {
+      throw new Error(`Resource no longer available: ${label}.`);
+    }
+    return {
+      contents: [
+        { uri: uri.href, mimeType: MARKDOWN_MIME_TYPE, text: doc.content }
+      ]
+    };
+  };
+}
 
 // src/surfaces/run-dispatch-cli.ts
 function asAnyDefinition(value) {
@@ -845,18 +963,14 @@ async function runDispatchCliBody(connector, opts) {
         "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 {
+    const connectorDir = connectorDirFromMeta(opts.meta);
+    const skill = await loadSkillDoc(connectorDir);
+    if (!skill) {
       throw new Error(
-        `SKILL.md not found at ${skillPath}. Ensure the connector ships a SKILL.md.`
+        `SKILL.md not found at ${skillPath(connectorDir)}. Ensure the connector ships a SKILL.md.`
       );
     }
-    opts.stdout.write(resolveRelativeLinks(content, connectorDir));
+    opts.stdout.write(skill.content);
     return;
   }
   if (first === "reference") {
@@ -865,18 +979,10 @@ async function runDispatchCliBody(connector, opts) {
         "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 connectorDir = connectorDirFromMeta(opts.meta);
     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 = [];
-      }
+      const entries = await listReferenceNames(connectorDir);
       if (entries.length === 0) {
         opts.stdout.write(`Available references: <none>
 `);
@@ -890,16 +996,13 @@ async function runDispatchCliBody(connector, opts) {
       }
       return;
     }
-    const refPath = path2.join(refsDir, `${name}.md`);
-    let content;
-    try {
-      content = await fs2.readFile(refPath, "utf8");
-    } catch {
+    const reference = await loadReferenceDoc(connectorDir, name);
+    if (!reference) {
       throw new Error(
-        `Reference file not found at ${refPath}. Ensure the connector ships \`references/${name}.md\`.`
+        `Reference file not found at ${referencePath(connectorDir, name)}. Ensure the connector ships \`references/${name}.md\`.`
       );
     }
-    opts.stdout.write(resolveRelativeLinks(content, refsDir));
+    opts.stdout.write(reference.content);
     return;
   }
   if (first !== "run") {
@@ -932,23 +1035,12 @@ 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 {
-    const cliPath = (0, import_node_url2.fileURLToPath)(meta.url);
-    const pkgPath = path2.join(path2.dirname(cliPath), "package.json");
-    const raw = await fs2.readFile(pkgPath, "utf8");
+    const cliPath = (0, import_node_url3.fileURLToPath)(meta.url);
+    const pkgPath = path3.join(path3.dirname(cliPath), "package.json");
+    const raw = await fs3.readFile(pkgPath, "utf8");
     const pkg = JSON.parse(raw);
     return typeof pkg.name === "string" ? pkg.name : void 0;
   } catch {
@@ -958,8 +1050,8 @@ async function resolvePackageName(meta) {
 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)
+    `Usage: <bin> run <script> [<json-input>] [--filter <jq>]
+       <bin> run <script> --help    (per-script input/output schema, env vars, --filter)
        <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)
@@ -988,7 +1080,7 @@ function printUsage(scripts, out, packageName) {
   }
   out.write(
     `
-Credentials are environment-variable only \u2014 run \`<bin> run <script> --help\` to list each script's required env vars.
+Run \`<bin> run <script> --help\` for a script's input/output schema, its required env vars (credentials are environment-variable only), and the \`--filter <jq>\` flag for trimming output.
 `
   );
 }
@@ -1014,6 +1106,13 @@ 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.
 
+`
+  );
+  out.write(
+    `The connector's docs are exposed as MCP resources (text/markdown): its
+SKILL.md and each references/*.md file, mirroring \`<bin> skill\` and
+\`<bin> reference\`. Clients read them via resources/list + resources/read.
+
 `
   );
   const names = Object.keys(scripts);
@@ -1057,12 +1156,31 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const args = io.argv.slice(2);
   let positional;
   let helpRequested = false;
-  for (const arg of args) {
+  let filter;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (arg === "--help" || arg === "-h") {
       helpRequested = true;
+    } else if (arg === "--filter") {
+      const value = args[i + 1];
+      if (value === void 0 || value.length === 0) {
+        throw new Error(
+          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
+        );
+      }
+      filter = value;
+      i++;
+    } else if (arg.startsWith("--filter=")) {
+      const value = arg.slice("--filter=".length);
+      if (value.length === 0) {
+        throw new Error(
+          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
+        );
+      }
+      filter = value;
     } 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).`
+        `Unknown flag "${arg}". The per-script CLI accepts \`--help\`, \`--filter <jq>\`, 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;
@@ -1107,7 +1225,12 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
     }
   }
   const result = await wrappedScript.run(input, runOpts);
-  io.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  const output = filter === void 0 ? result : await applyJqFilter(result, filter);
+  io.stdout.write(JSON.stringify(output, null, 2) + "\n");
+}
+async function applyJqFilter(value, filter) {
+  const { json: runJq } = await import("jq-wasm");
+  return runJq(value, filter);
 }
 async function readStdinInput(stdin, scriptName) {
   if (stdin.isTTY) {
@@ -1126,11 +1249,19 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   lines.push("");
   lines.push("Usage:");
   if (opts.invocation) {
-    lines.push(`  <bin> run ${opts.invocation.scriptName} '<json-input>'`);
+    lines.push(
+      `  <bin> run ${opts.invocation.scriptName} '<json-input>' [--filter <jq>]`
+    );
   } else {
-    lines.push(`  <bin> '<json-input>'`);
+    lines.push(`  <bin> '<json-input>' [--filter <jq>]`);
   }
   lines.push("");
+  lines.push(
+    "  --filter <jq>  Transform the JSON output through a jq expression."
+  );
+  lines.push("                 Useful for trimming large outputs, e.g.");
+  lines.push("                 --filter '.results | length'.");
+  lines.push("");
   if (opts.invocation) {
     lines.push("Example:");
     lines.push(
@@ -1155,6 +1286,11 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
     lines.push(...inputBlock);
     lines.push("");
   }
+  const outputBlock = formatHelpForOutput(definition);
+  if (outputBlock.length > 0) {
+    lines.push(...outputBlock);
+    lines.push("");
+  }
   return lines.join("\n");
 }
 function formatExampleCommand(definition, connectionResolvers, invocation) {
@@ -1191,6 +1327,20 @@ function formatHelpForInput(definition) {
   }
   return lines;
 }
+function formatHelpForOutput(definition) {
+  let schema;
+  try {
+    schema = import_zod3.z.toJSONSchema(definition.outputSchema);
+  } catch {
+    return [];
+  }
+  const lines = ["Output (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) {

package/dist/index.d.cts

@@ -463,8 +463,9 @@ declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends
  * from `process.env` via `buildRunOptionsFromEnv`, calls the wrapped
  * script, writes JSON.
  *
- * **Credentials are env-only by design.** The CLI takes only positional
- * JSON (the script's `inputSchema`) and `--help`. Passing secrets via
+ * **Credentials are env-only by design.** The CLI takes positional
+ * JSON (the script's `inputSchema`), `--help`, and `--filter <jq>` (a jq
+ * expression that post-processes the JSON output). Passing secrets via
  * argv would leak them through shell history, `ps`, audit logs, and CI
  * runner echo.
  *

package/dist/index.d.ts

@@ -463,8 +463,9 @@ declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends
  * from `process.env` via `buildRunOptionsFromEnv`, calls the wrapped
  * script, writes JSON.
  *
- * **Credentials are env-only by design.** The CLI takes only positional
- * JSON (the script's `inputSchema`) and `--help`. Passing secrets via
+ * **Credentials are env-only by design.** The CLI takes positional
+ * JSON (the script's `inputSchema`), `--help`, and `--filter <jq>` (a jq
+ * expression that post-processes the JSON output). Passing secrets via
  * argv would leak them through shell history, `ps`, audit logs, and CI
  * runner echo.
  *

package/dist/index.js

@@ -600,14 +600,74 @@ function defineTool(config) {
 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";
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
 
-// src/surfaces/serve-mcp-stdio.ts
+// src/surfaces/connector-docs.ts
 import * as fs from "fs/promises";
 import * as path from "path";
 import { fileURLToPath } from "url";
+var SKILL_FILENAME = "SKILL.md";
+var REFERENCES_DIRNAME = "references";
+function connectorDirFromMeta(meta) {
+  const dir = path.dirname(fileURLToPath(meta.url));
+  return path.basename(dir) === "dist" ? path.dirname(dir) : dir;
+}
+function skillPath(connectorDir) {
+  return path.join(connectorDir, SKILL_FILENAME);
+}
+function referencePath(connectorDir, name) {
+  return path.join(connectorDir, REFERENCES_DIRNAME, `${name}.md`);
+}
+async function loadSkillDoc(connectorDir) {
+  return loadDoc(skillPath(connectorDir), connectorDir);
+}
+async function listReferenceNames(connectorDir) {
+  try {
+    const entries = await fs.readdir(
+      path.join(connectorDir, REFERENCES_DIRNAME),
+      { recursive: true }
+    );
+    return entries.filter((entry) => entry.endsWith(".md")).map((entry) => toPosix(entry).slice(0, -".md".length));
+  } catch {
+    return [];
+  }
+}
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+async function loadReferenceDoc(connectorDir, name) {
+  return loadDoc(
+    referencePath(connectorDir, name),
+    path.join(connectorDir, REFERENCES_DIRNAME)
+  );
+}
+async function loadDoc(filePath, baseDir) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch {
+    return void 0;
+  }
+  return { path: filePath, content: resolveRelativeLinks(raw, baseDir) };
+}
+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}(${path.resolve(baseDir, url)})`;
+    }
+  );
+}
+
+// src/surfaces/serve-mcp-stdio.ts
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 function buildMcpRegistry(scripts, env, connectionResolvers) {
@@ -628,9 +688,9 @@ async function resolveServerInfo(meta) {
     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 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 {
       name: typeof pkg.name === "string" ? pkg.name : FALLBACK_SERVER_NAME,
@@ -640,9 +700,8 @@ async function resolveServerInfo(meta) {
     return { name: FALLBACK_SERVER_NAME, version: FALLBACK_SERVER_VERSION };
   }
 }
-async function serveMcpStdio(meta, connector, opts = {}) {
+async function buildMcpServer(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);
@@ -666,10 +725,69 @@ async function serveMcpStdio(meta, connector, opts = {}) {
       }
     );
   }
+  if (meta.url) {
+    await registerDocResources(
+      server,
+      connectorSlug(serverInfo.name),
+      connectorDirFromMeta(meta)
+    );
+  }
+  return { server, serverInfo };
+}
+async function serveMcpStdio(meta, connector, opts = {}) {
+  const stderr = opts.stderr ?? process.stderr;
+  const { server, serverInfo } = await buildMcpServer(meta, connector, opts);
   await server.connect(new StdioServerTransport());
   stderr.write(`[${serverInfo.name}] MCP server ready on stdio.
 `);
 }
+var MARKDOWN_MIME_TYPE = "text/markdown";
+function connectorSlug(serverName) {
+  const basename2 = serverName.split("/").pop() ?? serverName;
+  return basename2.replace(/-connector$/, "") || basename2;
+}
+async function registerDocResources(server, slug, connectorDir) {
+  const skill = await loadSkillDoc(connectorDir);
+  if (skill) {
+    server.registerResource(
+      SKILL_FILENAME,
+      `connector://${slug}/${SKILL_FILENAME}`,
+      {
+        title: "Skill guide",
+        description: "The connector's SKILL.md: when to use it, auth setup, and the script catalog.",
+        mimeType: MARKDOWN_MIME_TYPE
+      },
+      readDoc(() => loadSkillDoc(connectorDir), skill.path)
+    );
+  }
+  for (const name of await listReferenceNames(connectorDir)) {
+    const resourceName = `${REFERENCES_DIRNAME}/${name}.md`;
+    const uriPath = name.split("/").map(encodeURIComponent).join("/");
+    server.registerResource(
+      resourceName,
+      `connector://${slug}/${REFERENCES_DIRNAME}/${uriPath}.md`,
+      {
+        title: `Reference: ${name}`,
+        description: `Durable per-app knowledge from references/${name}.md (API gotchas, encodings, edge cases).`,
+        mimeType: MARKDOWN_MIME_TYPE
+      },
+      readDoc(() => loadReferenceDoc(connectorDir, name), resourceName)
+    );
+  }
+}
+function readDoc(load, label) {
+  return async (uri) => {
+    const doc = await load();
+    if (!doc) {
+      throw new Error(`Resource no longer available: ${label}.`);
+    }
+    return {
+      contents: [
+        { uri: uri.href, mimeType: MARKDOWN_MIME_TYPE, text: doc.content }
+      ]
+    };
+  };
+}
 
 // src/surfaces/run-dispatch-cli.ts
 function asAnyDefinition(value) {
@@ -739,18 +857,14 @@ async function runDispatchCliBody(connector, opts) {
         "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 {
+    const connectorDir = connectorDirFromMeta(opts.meta);
+    const skill = await loadSkillDoc(connectorDir);
+    if (!skill) {
       throw new Error(
-        `SKILL.md not found at ${skillPath}. Ensure the connector ships a SKILL.md.`
+        `SKILL.md not found at ${skillPath(connectorDir)}. Ensure the connector ships a SKILL.md.`
       );
     }
-    opts.stdout.write(resolveRelativeLinks(content, connectorDir));
+    opts.stdout.write(skill.content);
     return;
   }
   if (first === "reference") {
@@ -759,18 +873,10 @@ async function runDispatchCliBody(connector, opts) {
         "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 connectorDir = connectorDirFromMeta(opts.meta);
     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 = [];
-      }
+      const entries = await listReferenceNames(connectorDir);
       if (entries.length === 0) {
         opts.stdout.write(`Available references: <none>
 `);
@@ -784,16 +890,13 @@ async function runDispatchCliBody(connector, opts) {
       }
       return;
     }
-    const refPath = path2.join(refsDir, `${name}.md`);
-    let content;
-    try {
-      content = await fs2.readFile(refPath, "utf8");
-    } catch {
+    const reference = await loadReferenceDoc(connectorDir, name);
+    if (!reference) {
       throw new Error(
-        `Reference file not found at ${refPath}. Ensure the connector ships \`references/${name}.md\`.`
+        `Reference file not found at ${referencePath(connectorDir, name)}. Ensure the connector ships \`references/${name}.md\`.`
       );
     }
-    opts.stdout.write(resolveRelativeLinks(content, refsDir));
+    opts.stdout.write(reference.content);
     return;
   }
   if (first !== "run") {
@@ -826,23 +929,12 @@ 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 {
-    const cliPath = fileURLToPath2(meta.url);
-    const pkgPath = path2.join(path2.dirname(cliPath), "package.json");
-    const raw = await fs2.readFile(pkgPath, "utf8");
+    const cliPath = fileURLToPath3(meta.url);
+    const pkgPath = path3.join(path3.dirname(cliPath), "package.json");
+    const raw = await fs3.readFile(pkgPath, "utf8");
     const pkg = JSON.parse(raw);
     return typeof pkg.name === "string" ? pkg.name : void 0;
   } catch {
@@ -852,8 +944,8 @@ async function resolvePackageName(meta) {
 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)
+    `Usage: <bin> run <script> [<json-input>] [--filter <jq>]
+       <bin> run <script> --help    (per-script input/output schema, env vars, --filter)
        <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)
@@ -882,7 +974,7 @@ function printUsage(scripts, out, packageName) {
   }
   out.write(
     `
-Credentials are environment-variable only \u2014 run \`<bin> run <script> --help\` to list each script's required env vars.
+Run \`<bin> run <script> --help\` for a script's input/output schema, its required env vars (credentials are environment-variable only), and the \`--filter <jq>\` flag for trimming output.
 `
   );
 }
@@ -908,6 +1000,13 @@ 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.
 
+`
+  );
+  out.write(
+    `The connector's docs are exposed as MCP resources (text/markdown): its
+SKILL.md and each references/*.md file, mirroring \`<bin> skill\` and
+\`<bin> reference\`. Clients read them via resources/list + resources/read.
+
 `
   );
   const names = Object.keys(scripts);
@@ -951,12 +1050,31 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const args = io.argv.slice(2);
   let positional;
   let helpRequested = false;
-  for (const arg of args) {
+  let filter;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (arg === "--help" || arg === "-h") {
       helpRequested = true;
+    } else if (arg === "--filter") {
+      const value = args[i + 1];
+      if (value === void 0 || value.length === 0) {
+        throw new Error(
+          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
+        );
+      }
+      filter = value;
+      i++;
+    } else if (arg.startsWith("--filter=")) {
+      const value = arg.slice("--filter=".length);
+      if (value.length === 0) {
+        throw new Error(
+          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
+        );
+      }
+      filter = value;
     } 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).`
+        `Unknown flag "${arg}". The per-script CLI accepts \`--help\`, \`--filter <jq>\`, 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;
@@ -1001,7 +1119,12 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
     }
   }
   const result = await wrappedScript.run(input, runOpts);
-  io.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  const output = filter === void 0 ? result : await applyJqFilter(result, filter);
+  io.stdout.write(JSON.stringify(output, null, 2) + "\n");
+}
+async function applyJqFilter(value, filter) {
+  const { json: runJq } = await import("jq-wasm");
+  return runJq(value, filter);
 }
 async function readStdinInput(stdin, scriptName) {
   if (stdin.isTTY) {
@@ -1020,11 +1143,19 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   lines.push("");
   lines.push("Usage:");
   if (opts.invocation) {
-    lines.push(`  <bin> run ${opts.invocation.scriptName} '<json-input>'`);
+    lines.push(
+      `  <bin> run ${opts.invocation.scriptName} '<json-input>' [--filter <jq>]`
+    );
   } else {
-    lines.push(`  <bin> '<json-input>'`);
+    lines.push(`  <bin> '<json-input>' [--filter <jq>]`);
   }
   lines.push("");
+  lines.push(
+    "  --filter <jq>  Transform the JSON output through a jq expression."
+  );
+  lines.push("                 Useful for trimming large outputs, e.g.");
+  lines.push("                 --filter '.results | length'.");
+  lines.push("");
   if (opts.invocation) {
     lines.push("Example:");
     lines.push(
@@ -1049,6 +1180,11 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
     lines.push(...inputBlock);
     lines.push("");
   }
+  const outputBlock = formatHelpForOutput(definition);
+  if (outputBlock.length > 0) {
+    lines.push(...outputBlock);
+    lines.push("");
+  }
   return lines.join("\n");
 }
 function formatExampleCommand(definition, connectionResolvers, invocation) {
@@ -1085,6 +1221,20 @@ function formatHelpForInput(definition) {
   }
   return lines;
 }
+function formatHelpForOutput(definition) {
+  let schema;
+  try {
+    schema = z3.toJSONSchema(definition.outputSchema);
+  } catch {
+    return [];
+  }
+  const lines = ["Output (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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/connectors-sdk",
-  "version": "0.1.0-experimental.11",
+  "version": "0.1.0-experimental.13",
   "description": "SDK for building Zapier connectors. Provides the authoring primitives and execution surfaces for connector scripts.",
   "license": "Elastic-2.0",
   "type": "module",
@@ -24,6 +24,9 @@
     "README.md",
     "LICENSE"
   ],
+  "dependencies": {
+    "jq-wasm": "1.1.0-jq-1.8.1"
+  },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@zapier/zapier-sdk": "^0.59.0",