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

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

@@ -280,6 +280,39 @@ function isPackageInstalled(name) {
     return false;
   }
 }
+function buildMissingConnectionError(scriptName, missingSlots) {
+  const lines = [];
+  if (missingSlots.length === 1 && missingSlots[0].slotName === void 0) {
+    const { connectionKey, resolvers } = missingSlots[0];
+    lines.push(
+      `"${scriptName}" requires the "${connectionKey}" connection but no credentials were found in the environment.`
+    );
+    lines.push("");
+    lines.push(
+      "Set one of the following environment variables before running:"
+    );
+    lines.push("");
+    for (const resolver of resolvers) {
+      const vars = envVarsFor(void 0, connectionKey, resolver);
+      lines.push(`  ${vars.join("  ")}  (${resolver.name})`);
+    }
+  } else {
+    lines.push(
+      `"${scriptName}" is missing credentials for connection slot(s):`
+    );
+    for (const { slotName, connectionKey, resolvers } of missingSlots) {
+      lines.push("");
+      lines.push(`  ${slotName} (${connectionKey}):`);
+      for (const resolver of resolvers) {
+        const vars = envVarsFor(slotName, connectionKey, resolver);
+        lines.push(`    ${vars.join("  ")}  (${resolver.name})`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push("Run with --help for the full auth guide.");
+  return new Error(lines.join("\n"));
+}
 function formatHelpForConnections(definition, connectionResolvers, env) {
   const slots = [...walkConnections(definition)];
   if (slots.length === 0) return [];
@@ -673,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) {
@@ -701,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,
@@ -713,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);
@@ -739,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) {
@@ -812,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") {
@@ -832,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>
 `);
@@ -857,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") {
@@ -899,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 {
@@ -981,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,6 +1189,22 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const input = wrappedScript.inputSchema.parse(JSON.parse(raw));
   const hasConnections = [...walkConnections(wrappedScript)].length > 0;
   const runOpts = hasConnections ? buildRunOptionsFromEnv(wrappedScript, io.env, connectionResolvers) : void 0;
+  if (runOpts !== void 0) {
+    const missing = [];
+    for (const { slotName, connectionKey } of walkConnections(wrappedScript)) {
+      const value = slotName === void 0 ? "connection" in runOpts ? runOpts.connection : void 0 : "connections" in runOpts ? runOpts.connections[slotName] : void 0;
+      if (value === void 0) {
+        missing.push({
+          slotName,
+          connectionKey,
+          resolvers: resolversForKey(connectionResolvers, connectionKey)
+        });
+      }
+    }
+    if (missing.length > 0) {
+      throw buildMissingConnectionError(wrappedScript.name, missing);
+    }
+  }
   const result = await wrappedScript.run(input, runOpts);
   io.stdout.write(JSON.stringify(result, null, 2) + "\n");
 }

package/dist/index.js

@@ -174,6 +174,39 @@ function isPackageInstalled(name) {
     return false;
   }
 }
+function buildMissingConnectionError(scriptName, missingSlots) {
+  const lines = [];
+  if (missingSlots.length === 1 && missingSlots[0].slotName === void 0) {
+    const { connectionKey, resolvers } = missingSlots[0];
+    lines.push(
+      `"${scriptName}" requires the "${connectionKey}" connection but no credentials were found in the environment.`
+    );
+    lines.push("");
+    lines.push(
+      "Set one of the following environment variables before running:"
+    );
+    lines.push("");
+    for (const resolver of resolvers) {
+      const vars = envVarsFor(void 0, connectionKey, resolver);
+      lines.push(`  ${vars.join("  ")}  (${resolver.name})`);
+    }
+  } else {
+    lines.push(
+      `"${scriptName}" is missing credentials for connection slot(s):`
+    );
+    for (const { slotName, connectionKey, resolvers } of missingSlots) {
+      lines.push("");
+      lines.push(`  ${slotName} (${connectionKey}):`);
+      for (const resolver of resolvers) {
+        const vars = envVarsFor(slotName, connectionKey, resolver);
+        lines.push(`    ${vars.join("  ")}  (${resolver.name})`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push("Run with --help for the full auth guide.");
+  return new Error(lines.join("\n"));
+}
 function formatHelpForConnections(definition, connectionResolvers, env) {
   const slots = [...walkConnections(definition)];
   if (slots.length === 0) return [];
@@ -567,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) {
@@ -595,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,
@@ -607,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);
@@ -633,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) {
@@ -706,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") {
@@ -726,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>
 `);
@@ -751,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") {
@@ -793,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 {
@@ -875,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,6 +1083,22 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const input = wrappedScript.inputSchema.parse(JSON.parse(raw));
   const hasConnections = [...walkConnections(wrappedScript)].length > 0;
   const runOpts = hasConnections ? buildRunOptionsFromEnv(wrappedScript, io.env, connectionResolvers) : void 0;
+  if (runOpts !== void 0) {
+    const missing = [];
+    for (const { slotName, connectionKey } of walkConnections(wrappedScript)) {
+      const value = slotName === void 0 ? "connection" in runOpts ? runOpts.connection : void 0 : "connections" in runOpts ? runOpts.connections[slotName] : void 0;
+      if (value === void 0) {
+        missing.push({
+          slotName,
+          connectionKey,
+          resolvers: resolversForKey(connectionResolvers, connectionKey)
+        });
+      }
+    }
+    if (missing.length > 0) {
+      throw buildMissingConnectionError(wrappedScript.name, missing);
+    }
+  }
   const result = await wrappedScript.run(input, runOpts);
   io.stdout.write(JSON.stringify(result, null, 2) + "\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/connectors-sdk",
-  "version": "0.1.0-experimental.10",
+  "version": "0.1.0-experimental.12",
   "description": "SDK for building Zapier connectors. Provides the authoring primitives and execution surfaces for connector scripts.",
   "license": "Elastic-2.0",
   "type": "module",