mcp-scraper 0.15.1 → 0.16.0

package/README.md

@@ -88,7 +88,7 @@ Build the branded one-click bundle:
 npm run build:mcpb
 ```
 
-The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.14.0`, SHA-256 `01b37c065b803a19ac824b82058b311b115e272d9be01d870094737c74b58753`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, and API-key configuration field from the bundle manifest.
+The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.16.0`, SHA-256 `01623d11e3096cc867afee6c8abc345aaebf0eb15ffafdd875302a80cb90dd31`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, and API-key configuration field from the bundle manifest.
 
 The MCPB install exposes every tool — web-intelligence plus all `browser_*` tools — through the one `mcp-scraper` server.
 
@@ -176,16 +176,18 @@ env = { MCP_SCRAPER_API_KEY = "sk_live_your_key" }
 
 ### Connected-account tools
 
-- `list_service_connections` — list this caller's tenant-owned Nango OAuth and official remote MCP connections, including exact live reads, gated actions, permanently blocked administrative tools, and the credential transport. Connections are never shared between customers.
-- `describe_service_connection_tool` — fetch the exact title, description, read/action classification, and JSON input schema for one tool listed on one tenant-owned connection. Use this before constructing provider-native arguments; it keeps Resend's broad official MCP surface usable without registering 85 additional top-level tools.
+- `list_service_connections` — list this caller's tenant-owned Nango OAuth and official remote MCP connections, including exact live reads, gated actions, permanently blocked administrative tools, credential transport, and schema-discovery metadata. Connections are never shared between customers.
+- `describe_service_connection_tool` — fetch the sanitized live MCP Tool definition for one tool listed on one tenant-owned connection, including its current callability, input schema, optional output schema, safe annotations, and schema hash. Use this before constructing provider-native arguments; provider functions stay behind the generic bridges instead of becoming dozens of permanent top-level tools.
 - `export_connected_service_data` — fetch a bounded Gmail, Google Calendar, Zoom, or Resend time range in one MCP call. Resend's aggregate `resend_data` export walks 12 practical safe collections: sent mail, received mail, logs, contacts, broadcasts, templates, domains, segments, topics, webhooks, contact imports, and contact properties. The six core collections are also individually selectable. The server handles provider pagination, bounded detail retrieval, normalization, per-category warnings, and signed continuation. Small exports return inline; larger exports become private JSONL retained for seven days with a 15-minute signed URL. Attachments remain metadata-only and oversized records are truncated with warnings.
 - `renew_connected_data_download` — issue a fresh 15-minute signed URL for an unexpired private export artifact without pulling the provider again.
-- `read_service_connection` — run one small live read by exact allowlisted name across Nango OAuth or official remote MCP connections. Do not loop it over a time range; use `export_connected_service_data` for email, calendar, recording, transcript, or Resend collections.
-- `call_service_connection_action` — run one exact mutation only after the account action switch is enabled. Resend, GitHub, Gmail, Calendar, Slack, Zoom, Facebook, Google Analytics, X, and YouTube actions remain provider-policy and tenant gated; credential, OAuth-grant, and raw editor-session administration is never exposed.
+- `read_service_connection` — run one small live read by exact allowlisted name across Nango OAuth or official remote MCP connections, including bounded Google Drive inventory, change, Doc, Sheet, and text-file tools. Do not loop it over a time range when `export_connected_service_data` supports that provider's collection.
+- `call_service_connection_action` — run one exact mutation only after the account action switch is enabled. Google Drive, Resend, GitHub, Gmail, Calendar, Slack, Zoom, Facebook, Google Analytics, X, and YouTube actions remain live-inventory, provider-policy, tenant, and audit gated; credential, OAuth-grant, and raw editor-session administration is never exposed.
 - `set_scheduled_action_connections` — bind exact tenant connections and exact tool grants to one scheduled action. Deterministic connection syncs are model-free and one schedule occurrence counts as one metered event even when provider pagination spans many pages.
 
 GitHub uses the same provider-neutral read/action bridges: 27 live reads cover repository discovery, issues, pull requests, commits, releases, and workflows; 20 live mutations remain account- and schedule-gated. The 47 Nango functions and expanded reconnect scopes are deployed. The current test token remains `public_repo` until owners approve its two pending organization requests, so private-repository and workflow parity is not yet claimed.
 
+Google Drive Phase 1 exposes ten bounded reads plus the separately gated `create-drive-folder` and `copy-drive-file` actions through those same bridges and through per-run Mastra toolsets. It is interactive tool support, not the later deterministic bulk-export/`connection_sync` phase; large binary delivery and broader Drive mutations remain unreleased.
+
 ### Browser-agent tools
 
 - `browser_open` — open a direct/no-proxy hosted browser session. Pass a saved profile name to load an authenticated session. Returns a human `watch_url`.

package/dist/bin/api-server.cjs

@@ -27642,7 +27642,7 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.15.1";
+    PACKAGE_VERSION = "0.16.0";
   }
 });
 
@@ -28854,6 +28854,9 @@ var init_mcp_tool_schemas = __esm({
         readTools: import_zod33.z.array(import_zod33.z.string()).describe("Tool names this connection can be read with via read_service_connection."),
         actionTools: import_zod33.z.array(import_zod33.z.string()).describe("Explicitly allowlisted write or mutation tool names callable through call_service_connection_action after actions are enabled for this connection."),
         adminBlockedTools: import_zod33.z.array(import_zod33.z.string()).describe("Credential, OAuth-grant, or other administrative tools permanently blocked from the MCP and scheduler."),
+        mcpEndpoint: import_zod33.z.string().url().nullable().describe("Authenticated connection-scoped MCP endpoint when native provider tools/list projection is available. Null means use describe_service_connection_tool on this root MCP."),
+        schemaDiscovery: import_zod33.z.enum(["connection_tools_list", "compatibility_describe"]).describe("How clients discover this connection's exact live provider schemas."),
+        toolRevision: import_zod33.z.string().nullable().describe("Opaque revision of the resolved live tool catalog, when available. It changes when provider tools or policy change."),
         vaultName: import_zod33.z.string().nullable().describe("Memory vault this connection's digest writes into, if it has run at least once. Search it with memory-search."),
         tableName: import_zod33.z.string().nullable().describe("Table this connection's digest writes structured rows into, if it has run at least once. Query it with table-query.")
       }))
@@ -28870,7 +28873,8 @@ var init_mcp_tool_schemas = __esm({
     };
     DescribeServiceConnectionToolInputSchema = {
       connectionId: import_zod33.z.string().min(1).describe("A tenant-owned connectionId from list_service_connections."),
-      tool: import_zod33.z.string().min(1).describe("One exact name from that connection's readTools or actionTools. Admin-blocked and arbitrary names are rejected.")
+      tool: import_zod33.z.string().min(1).describe("One exact name from that connection's readTools or actionTools. Admin-blocked and arbitrary names are rejected."),
+      fresh: import_zod33.z.boolean().optional().describe("Bypass the short-lived sanitized schema cache. Ownership, connection state, and tool policy are still rechecked; use only when a provider tool catalog just changed.")
     };
     DescribeServiceConnectionToolOutputSchema = {
       ok: import_zod33.z.boolean(),
@@ -28879,8 +28883,33 @@ var init_mcp_tool_schemas = __esm({
         title: NullableString,
         description: NullableString,
         classification: import_zod33.z.enum(["read", "action"]),
-        inputSchema: import_zod33.z.record(import_zod33.z.string(), import_zod33.z.unknown()).describe("JSON Schema for the exact connected-provider tool arguments.")
+        callable: import_zod33.z.boolean().optional().describe("Whether the tool is callable now. A gated action can be described while actions are off and return false."),
+        blockedReason: import_zod33.z.enum(["actions_disabled", "inactive_connection"]).nullable().optional(),
+        transport: import_zod33.z.enum(["nango", "remote_mcp"]).optional(),
+        providerConfigKey: import_zod33.z.string().optional(),
+        protocolVersion: NullableString.optional(),
+        schemaSource: import_zod33.z.literal("live_tools_list").optional(),
+        inputSchema: import_zod33.z.record(import_zod33.z.string(), import_zod33.z.unknown()).describe("JSON Schema for the exact connected-provider tool arguments."),
+        outputSchema: import_zod33.z.record(import_zod33.z.string(), import_zod33.z.unknown()).optional().describe("Provider-native JSON output schema when the live MCP tool publishes one."),
+        annotations: import_zod33.z.object({
+          title: import_zod33.z.string().optional(),
+          readOnlyHint: import_zod33.z.boolean().optional(),
+          destructiveHint: import_zod33.z.boolean().optional(),
+          idempotentHint: import_zod33.z.boolean().optional(),
+          openWorldHint: import_zod33.z.boolean().optional()
+        }).optional(),
+        icons: import_zod33.z.array(import_zod33.z.object({
+          src: import_zod33.z.string(),
+          mimeType: import_zod33.z.string().optional(),
+          sizes: import_zod33.z.array(import_zod33.z.string()).optional(),
+          theme: import_zod33.z.enum(["light", "dark"]).optional()
+        })).optional(),
+        execution: import_zod33.z.object({ taskSupport: import_zod33.z.enum(["forbidden", "optional", "required"]) }).optional(),
+        schemaHash: import_zod33.z.string().optional().describe("SHA-256 of the sanitized live Tool definition."),
+        fetchedAt: import_zod33.z.string().optional()
       }).optional(),
+      retryable: import_zod33.z.boolean().optional(),
+      errorCode: import_zod33.z.string().optional(),
       error: NullableString
     };
     ConnectedDataContinuationSchema = import_zod33.z.object({
@@ -29696,7 +29725,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatCreditsInfo(await executor.creditsInfo(input), input));
   server.registerTool("list_service_connections", {
     title: "List Connected Services",
-    description: "List every third-party service connection this MCP Scraper account has authorized, including Resend, GitHub, Google Analytics, YouTube, Facebook Pages, LinkedIn, X, Meta Marketing, Slack, Gmail, Calendar, Drive, Zoom, Xero, and others. Returns the tenant-scoped connectionId, credential transport, exact readTools and actionTools, and permanently blocked administrative tools. Get a connectionId and exact tool name here before calling read_service_connection or call_service_connection_action. Nango OAuth and official remote MCP connections use the same provider-neutral bridges; mutations still require the account action switch and an exact allowed action. For already-digested history, prefer the returned vaultName or tableName.",
+    description: "List every third-party service connection this MCP Scraper account has authorized, including Resend, GitHub, Google Analytics, YouTube, Facebook Pages, LinkedIn, X, Meta Marketing, Slack, Gmail, Calendar, Google Drive, Zoom, Xero, and others. Returns the tenant-scoped connectionId, credential transport, exact live readTools and gated actionTools, permanently blocked administrative tools, and schema-discovery metadata. Get a connectionId and exact tool name here before calling describe_service_connection_tool, read_service_connection, or call_service_connection_action. Nango OAuth and official remote MCP connections use the same provider-neutral bridges; mutations still require the account action switch and an exact allowed action. For already-digested history, prefer the returned vaultName or tableName.",
     inputSchema: ListServiceConnectionsInputSchema,
     outputSchema: recordOutputSchema("list_service_connections", ListServiceConnectionsOutputSchema),
     annotations: { title: "List Connected Services", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
@@ -29731,14 +29760,14 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => executor.zoomCreateMeeting(input));
   server.registerTool("read_service_connection", {
     title: "Read Connected Service",
-    description: "Call one small live, read-only operation on any connected service, including Resend, GitHub repository, issue, pull-request, release, and workflow reads. Do not loop this tool to fetch a time range or collection: use export_connected_service_data for Gmail, calendar, Zoom, or Resend datasets. Requires a connectionId and an exact name from that connection's readTools in list_service_connections; an unlisted tool is rejected server-side.",
+    description: "Call one small live, read-only operation on any connected service, including Google Drive metadata/search tools, Resend, GitHub, Gmail, Calendar, Zoom, and other approved providers. Call describe_service_connection_tool first when arguments are not already known. Do not loop this tool once per file or record to fetch a corpus: use export_connected_service_data when that provider/dataset supports bulk delivery. Requires a connectionId and an exact name from that connection's live readTools in list_service_connections; an unlisted tool is rejected server-side.",
     inputSchema: ReadServiceConnectionInputSchema,
     outputSchema: recordOutputSchema("read_service_connection", ReadServiceConnectionOutputSchema),
     annotations: { title: "Read Connected Service", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
   }, async (input) => executor.readServiceConnection(input));
   server.registerTool("describe_service_connection_tool", {
     title: "Describe Connected Service Tool",
-    description: "Get the title, description, read/action classification, and exact JSON input schema for one tool exposed by a tenant-owned service connection. Call list_service_connections first, then describe the selected readTools or actionTools name before constructing arguments. Arbitrary names and permanently blocked administrative tools are rejected. This is especially useful for broad official remote MCP connections such as Resend, whose provider-native tools are intentionally exposed through generic bridges instead of dozens of new top-level MCP names.",
+    description: "Fetch the sanitized live MCP Tool definition for one exact tool exposed by a tenant-owned Nango OAuth or official remote MCP connection. Returns provider-native title, description, read/action classification, current callability, input schema, optional output schema, safe annotations, and a schema hash. Call list_service_connections first, then describe a listed readTools or actionTools name before constructing arguments. This is a compatibility tool on MCP Scraper's fixed root MCP; protocol-native connection endpoints discover the same definitions through MCP tools/list, not a custom tools/describe method. Arbitrary names and permanently blocked administrative tools are rejected.",
     inputSchema: DescribeServiceConnectionToolInputSchema,
     outputSchema: recordOutputSchema("describe_service_connection_tool", DescribeServiceConnectionToolOutputSchema),
     annotations: { title: "Describe Connected Service Tool", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
@@ -29759,7 +29788,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => executor.renewConnectedDataDownload(input));
   server.registerTool("call_service_connection_action", {
     title: "Run Connected Service Action",
-    description: "Run one explicitly allowlisted write or mutation on a tenant-owned OAuth or remote MCP connection. First call list_service_connections, use a connection with actionsEnabled true, choose one exact actionTools entry, and supply that action's arguments. The server rejects arbitrary action names, inactive or foreign connections, disabled actions, and every adminBlockedTools entry. This includes Resend sends, broadcasts, contacts and templates plus GitHub issue, pull-request, repository-content, release, and workflow actions when exposed. Sends, deletes, merges, review submissions, workflow execution, and content changes are high impact.",
+    description: "Run one explicitly allowlisted write or mutation on a tenant-owned OAuth or remote MCP connection. First call list_service_connections, use a connection with actionsEnabled true, describe the exact actionTools entry to obtain its live schema, and supply only that action's arguments. The server rejects arbitrary action names, inactive or foreign connections, disabled actions, and every adminBlockedTools entry. This can include Google Drive folder creation or file copies, Resend delivery, and GitHub mutations only when those exact actions are live and approved. Sends, deletes, merges, workflow execution, and content changes are high impact.",
     inputSchema: CallServiceConnectionActionInputSchema,
     outputSchema: recordOutputSchema("call_service_connection_action", CallServiceConnectionActionOutputSchema),
     annotations: { title: "Run Connected Service Action", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
@@ -29824,12 +29853,15 @@ async function readResponseData(res) {
 }
 function httpErrorPayload(path6, res, data) {
   const objectData = data && typeof data === "object" && !Array.isArray(data) ? data : null;
-  const bodyMessage = objectData ? objectData.message ?? objectData.error ?? objectData.error_code : data;
+  const rawCode = objectData?.code ?? objectData?.errorCode ?? objectData?.error_code;
+  const safeCode = typeof rawCode === "string" && /^[a-z0-9][a-z0-9_-]{0,99}$/.test(rawCode) ? rawCode : "mcp_http_error";
+  const bodyMessage = objectData ? objectData.message ?? objectData.error ?? rawCode : data;
   return {
     ...objectData ?? { body: data },
-    error: objectData?.error ?? objectData?.error_code ?? "mcp_http_error",
+    error: safeCode,
+    error_code: safeCode,
     error_type: "http",
-    retryable: res.status === 429 || res.status >= 500,
+    retryable: typeof objectData?.retryable === "boolean" ? objectData.retryable : res.status === 429 || res.status >= 500,
     status: res.status,
     statusText: res.statusText,
     path: path6,
@@ -39522,6 +39554,42 @@ function arrayFromPayload(value, keys) {
   }
   return [];
 }
+function controlErrorStatus(status) {
+  if (status === 400 || status === 403 || status === 404 || status === 409 || status === 429 || status === 502 || status === 503) {
+    return status;
+  }
+  return status >= 500 ? 503 : 502;
+}
+function defaultControlErrorCode(status) {
+  if (status === 400) return "invalid_request";
+  if (status === 403) return "actions_disabled";
+  if (status === 404) return "connection_not_found";
+  if (status === 409) return "connection_inactive";
+  if (status === 429) return "upstream_rate_limited";
+  if (status === 503) return "connection_transport_unavailable";
+  return "connection_control_failed";
+}
+function defaultControlErrorMessage(status) {
+  if (status === 400) return "The connection request was invalid.";
+  if (status === 403) return "Actions are disabled for this service connection.";
+  if (status === 404) return "The service connection was not found.";
+  if (status === 409) return "The service connection is not currently usable.";
+  if (status === 429) return "The connected service is temporarily rate limited.";
+  if (status === 503) return "The service connection transport is temporarily unavailable.";
+  return "The service connection control request failed.";
+}
+function safeControlErrorPayload(body, responseStatus) {
+  const status = controlErrorStatus(responseStatus);
+  const unwrapped = unwrapData(body);
+  const record = isRecord(unwrapped) ? unwrapped : isRecord(body) ? body : null;
+  const candidateCode = record ? firstString(record, ["code", "errorCode", "error_code"], 100) : null;
+  const normalizedCandidateCode = candidateCode ? CONTROL_ERROR_CODE_ALIASES.get(candidateCode) ?? candidateCode : null;
+  const code = normalizedCandidateCode && SAFE_CONTROL_ERROR_CODES.has(normalizedCandidateCode) ? normalizedCandidateCode : defaultControlErrorCode(status);
+  const candidateMessage = record ? firstString(record, ["error", "message"], 500) : null;
+  const message = normalizedCandidateCode && SAFE_CONTROL_ERROR_CODES.has(normalizedCandidateCode) && candidateMessage ? candidateMessage.replace(/[\u0000-\u001f\u007f]/g, " ") : defaultControlErrorMessage(status);
+  const retryable = record && typeof record.retryable === "boolean" ? record.retryable : status === 429 || status >= 500;
+  return { status, code, message, retryable };
+}
 async function controlRequest(path6, init, timeoutMs = 2e4) {
   const response = await fetch(`${controlBaseUrl()}${path6}`, {
     ...init,
@@ -39533,7 +39601,13 @@ async function controlRequest(path6, init, timeoutMs = 2e4) {
     },
     signal: AbortSignal.timeout(timeoutMs)
   }).catch((err) => {
-    throw new NangoControlError(`Scheduled service connection control is unavailable: ${err instanceof Error ? err.message : "network error"}`);
+    const cause = err instanceof Error && err.name === "TimeoutError" ? "request timed out" : "network error";
+    throw new NangoControlError(
+      `Scheduled service connection control is unavailable: ${cause}.`,
+      503,
+      "connection_transport_unavailable",
+      true
+    );
   });
   const text = await response.text();
   let body = {};
@@ -39543,8 +39617,8 @@ async function controlRequest(path6, init, timeoutMs = 2e4) {
     body = {};
   }
   if (!response.ok) {
-    const upstream = isRecord(body) ? cleanString(body.error, 300) : null;
-    throw new NangoControlError(upstream || `Scheduled service connection control failed (${response.status}).`);
+    const error = safeControlErrorPayload(body, response.status);
+    throw new NangoControlError(error.message, error.status, error.code, error.retryable);
   }
   return body;
 }
@@ -39639,6 +39713,9 @@ async function getNangoConnections(identity) {
       actionsEnabled: row.actionsEnabled === true || row.actions_enabled === true,
       readTools: cleanTools(row.readTools ?? row.read_tools),
       actionTools: cleanTools(row.actionTools ?? row.action_tools ?? row.writeTools ?? row.write_tools),
+      mcpEndpoint: null,
+      schemaDiscovery: "compatibility_describe",
+      toolRevision: firstString(row, ["toolRevision", "tool_revision"], 200),
       vaultName: firstString(row, ["vaultName", "vault_name"], 100),
       tableName: firstString(row, ["tableName", "table_name"], 100),
       createdAt: firstString(row, ["createdAt", "created_at"], 100),
@@ -39771,6 +39848,145 @@ async function callScheduleConnectionRead(identity, connectionId, tool, args) {
   const data = unwrapData(body);
   return isRecord(data) ? data.result ?? data : data;
 }
+function sanitizeToolSchema(value) {
+  if (!isRecord(value) || value.type !== "object") return null;
+  try {
+    const serialized = JSON.stringify(value);
+    if (Buffer.byteLength(serialized, "utf8") > 256 * 1024) return null;
+    const cloned = JSON.parse(serialized);
+    return isRecord(cloned) ? cloned : null;
+  } catch {
+    return null;
+  }
+}
+function sanitizeToolAnnotations(value) {
+  if (!isRecord(value)) return void 0;
+  const annotations = {};
+  const title = cleanString(value.title, 200);
+  if (title) annotations.title = title;
+  for (const key of ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"]) {
+    if (typeof value[key] === "boolean") annotations[key] = value[key];
+  }
+  return Object.keys(annotations).length > 0 ? annotations : void 0;
+}
+function sanitizeToolIconSource(value) {
+  const candidate = cleanString(value, 1e4);
+  if (!candidate) return null;
+  if (/^data:image\/(?:png|jpeg|webp|gif|svg\+xml);base64,[a-z0-9+/=]+$/i.test(candidate)) return candidate;
+  return cleanHttpsUrl(candidate);
+}
+function sanitizeToolIcons(value) {
+  if (!Array.isArray(value)) return void 0;
+  const icons = [];
+  for (const item of value.slice(0, 16)) {
+    if (!isRecord(item)) continue;
+    const src = sanitizeToolIconSource(item.src);
+    if (!src) continue;
+    const mimeType = cleanString(item.mimeType ?? item.mime_type, 100);
+    const sizes = cleanStringArray(item.sizes, 16, 32);
+    const theme = item.theme === "light" || item.theme === "dark" ? item.theme : void 0;
+    icons.push({
+      src,
+      ...mimeType ? { mimeType } : {},
+      ...sizes.length > 0 ? { sizes } : {},
+      ...theme ? { theme } : {}
+    });
+  }
+  return icons.length > 0 ? icons : void 0;
+}
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function projectedToolSchemaHash(tool) {
+  return (0, import_node_crypto17.createHash)("sha256").update(canonicalJson(tool)).digest("hex");
+}
+async function describeNangoTool(identity, connectionId, tool, fresh) {
+  const body = await controlRequest("/api/internal/nango/connections/actions/describe", {
+    method: "POST",
+    body: JSON.stringify({
+      identity,
+      connectionId,
+      tool,
+      ...fresh === void 0 ? {} : { fresh }
+    })
+  });
+  const data = unwrapData(body);
+  const rawTool = isRecord(data) && isRecord(data.tool) ? data.tool : data;
+  if (!isRecord(rawTool)) {
+    throw new NangoControlError(
+      "The connection service returned an invalid live tool description.",
+      502,
+      "tool_discovery_failed",
+      true
+    );
+  }
+  let serializedBytes = Number.POSITIVE_INFINITY;
+  try {
+    serializedBytes = Buffer.byteLength(JSON.stringify(rawTool), "utf8");
+  } catch {
+  }
+  const name = cleanString(rawTool.name, 200);
+  const classification = cleanString(rawTool.classification, 20);
+  const transport = cleanString(rawTool.transport, 20);
+  const providerConfigKey = cleanString(rawTool.providerConfigKey ?? rawTool.provider_config_key, 200);
+  const schemaSource = cleanString(rawTool.schemaSource ?? rawTool.schema_source, 50);
+  const upstreamSchemaHash = cleanString(rawTool.schemaHash ?? rawTool.schema_hash, 200);
+  const fetchedAt = cleanString(rawTool.fetchedAt ?? rawTool.fetched_at, 100);
+  const inputSchema = sanitizeToolSchema(rawTool.inputSchema ?? rawTool.input_schema);
+  const outputSchemaValue = rawTool.outputSchema ?? rawTool.output_schema;
+  const outputSchema = outputSchemaValue === void 0 ? void 0 : sanitizeToolSchema(outputSchemaValue);
+  const blockedReasonValue = rawTool.blockedReason ?? rawTool.blocked_reason;
+  const blockedReason = blockedReasonValue === null || blockedReasonValue === void 0 ? null : blockedReasonValue === "actions_disabled" || blockedReasonValue === "inactive_connection" ? blockedReasonValue : void 0;
+  if (serializedBytes > 256 * 1024 || !name || name !== tool || classification !== "read" && classification !== "action" || typeof rawTool.callable !== "boolean" || blockedReason === void 0 || transport !== "nango" && transport !== "remote_mcp" || !providerConfigKey || schemaSource !== "live_tools_list" || !upstreamSchemaHash || !/^[a-f0-9]{64}$/i.test(upstreamSchemaHash) || !fetchedAt || Number.isNaN(Date.parse(fetchedAt)) || !inputSchema || outputSchemaValue !== void 0 && !outputSchema) {
+    throw new NangoControlError(
+      "The connection service returned an invalid live tool description.",
+      502,
+      "tool_discovery_failed",
+      true
+    );
+  }
+  const protocolVersion = rawTool.protocolVersion === null || rawTool.protocol_version === null ? null : cleanString(rawTool.protocolVersion ?? rawTool.protocol_version, 100);
+  const executionValue = rawTool.execution;
+  const taskSupport = isRecord(executionValue) && (executionValue.taskSupport === "forbidden" || executionValue.taskSupport === "optional" || executionValue.taskSupport === "required") ? executionValue.taskSupport : null;
+  const title = cleanString(rawTool.title, 200);
+  const description = cleanString(rawTool.description, 12e3);
+  const annotations = sanitizeToolAnnotations(rawTool.annotations);
+  const icons = sanitizeToolIcons(rawTool.icons);
+  const execution = taskSupport ? { taskSupport } : void 0;
+  const schemaHash = projectedToolSchemaHash({
+    name,
+    inputSchema,
+    ...title ? { title } : {},
+    ...description ? { description } : {},
+    ...outputSchema ? { outputSchema } : {},
+    ...annotations ? { annotations } : {},
+    ...icons ? { icons } : {},
+    ...execution ? { execution } : {}
+  });
+  return {
+    name,
+    title,
+    description,
+    classification,
+    callable: rawTool.callable,
+    blockedReason,
+    transport,
+    providerConfigKey,
+    protocolVersion,
+    schemaSource: "live_tools_list",
+    inputSchema,
+    ...outputSchema ? { outputSchema } : {},
+    ...annotations ? { annotations } : {},
+    ...icons ? { icons } : {},
+    ...execution ? { execution } : {},
+    schemaHash,
+    fetchedAt
+  };
+}
 async function callScheduleConnectionExportPage(identity, input) {
   const body = await controlRequest("/api/internal/nango/connections/export-page", {
     method: "POST",
@@ -39808,10 +40024,11 @@ async function callScheduleConnectionExportPage(identity, input) {
     untrustedContent: true
   };
 }
-var DEFAULT_NANGO_CONTROL_URL, DISABLED_NANGO_TOOLS, CONNECTION_SYNC_REQUIRED_TOOLS, NangoControlError, ScheduleConnectionValidationError;
+var import_node_crypto17, DEFAULT_NANGO_CONTROL_URL, DISABLED_NANGO_TOOLS, CONNECTION_SYNC_REQUIRED_TOOLS, NangoControlError, ScheduleConnectionValidationError, SAFE_CONTROL_ERROR_CODES, CONTROL_ERROR_CODE_ALIASES;
 var init_nango_control = __esm({
   "src/api/nango-control.ts"() {
     "use strict";
+    import_node_crypto17 = require("crypto");
     init_connected_data_export();
     DEFAULT_NANGO_CONTROL_URL = "https://mcp-scraper-scheduler.vercel.app";
     DISABLED_NANGO_TOOLS = {
@@ -39854,10 +40071,14 @@ var init_nango_control = __esm({
     };
     NangoControlError = class extends Error {
       status;
-      constructor(message, status = 502) {
+      code;
+      retryable;
+      constructor(message, status = 502, code = status === 503 ? "connection_transport_unavailable" : "connection_control_failed", retryable = status === 429 || status >= 500) {
         super(message);
         this.name = "NangoControlError";
         this.status = status;
+        this.code = code;
+        this.retryable = retryable;
       }
     };
     ScheduleConnectionValidationError = class extends Error {
@@ -39866,6 +40087,27 @@ var init_nango_control = __esm({
         this.name = "ScheduleConnectionValidationError";
       }
     };
+    SAFE_CONTROL_ERROR_CODES = /* @__PURE__ */ new Set([
+      "invalid_request",
+      "tool_not_allowed",
+      "invalid_schema",
+      "connection_not_found",
+      "connection_inactive",
+      "actions_disabled",
+      "action_not_allowed",
+      "upstream_rate_limited",
+      "tool_discovery_failed",
+      "live_tool_missing",
+      "connection_transport_unavailable",
+      "connection_control_failed"
+    ]);
+    CONTROL_ERROR_CODE_ALIASES = /* @__PURE__ */ new Map([
+      ["connection_not_active", "connection_inactive"],
+      ["actions_not_enabled", "actions_disabled"],
+      ["action_tool_not_allowed", "action_not_allowed"],
+      ["no_action_for_provider", "action_not_allowed"],
+      ["tool_not_available", "live_tool_missing"]
+    ]);
   }
 });
 
@@ -40015,6 +40257,9 @@ async function getResendConnections(identity) {
       readTools: cleanTools2(row.readTools ?? row.read_tools),
       actionTools: cleanTools2(row.actionTools ?? row.action_tools ?? row.writeTools ?? row.write_tools),
       adminBlockedTools: cleanTools2(row.adminBlockedTools ?? row.admin_blocked_tools).length > 0 ? cleanTools2(row.adminBlockedTools ?? row.admin_blocked_tools) : [...RESEND_ADMIN_BLOCKED_TOOLS],
+      mcpEndpoint: null,
+      schemaDiscovery: "compatibility_describe",
+      toolRevision: firstString2(row, ["toolRevision", "tool_revision"], 200),
       vaultName: firstString2(row, ["vaultName", "vault_name"], 100),
       tableName: firstString2(row, ["tableName", "table_name"], 100),
       createdAt: firstString2(row, ["createdAt", "created_at"], 100),
@@ -40412,7 +40657,15 @@ function maybeProvisionInBackground(user, vaultCount) {
 }
 function scheduleConnectionError(c, err, fallback) {
   if (err instanceof ScheduleConnectionValidationError) return c.json({ ok: false, error: err.message }, 400);
-  if (err instanceof NangoControlError) return c.json({ ok: false, error: err.message }, err.status);
+  if (err instanceof NangoControlError) {
+    return c.json({
+      ok: false,
+      error: err.message,
+      code: err.code,
+      errorCode: err.code,
+      retryable: err.retryable
+    }, err.status);
+  }
   if (err instanceof ResendControlError) return c.json({ ok: false, error: err.message }, err.status);
   console.error("[schedule-connections]", err instanceof Error ? err.message : String(err));
   return c.json({ ok: false, error: fallback }, 502);
@@ -41296,11 +41549,12 @@ var init_server = __esm({
       const providerConfigKey = providerConfigKeyFrom(body.providerConfigKey);
       const tool = providerConfigKeyFrom(body.tool);
       if (!connectionId || !tool) return c.json({ ok: false, error: "connectionId and tool are required." }, 400);
+      if (body.fresh !== void 0 && typeof body.fresh !== "boolean") {
+        return c.json({ ok: false, error: "fresh must be a boolean when provided." }, 400);
+      }
       try {
-        if (!await isResendConnection(user.email, connectionId, providerConfigKey)) {
-          return c.json({ ok: false, error: "Typed tool descriptions are not available for this connection transport yet." }, 501);
-        }
-        return c.json({ ok: true, tool: await describeResendTool(user.email, connectionId, tool) });
+        const description = await isResendConnection(user.email, connectionId, providerConfigKey) ? await describeResendTool(user.email, connectionId, tool) : await describeNangoTool(user.email, connectionId, tool, body.fresh);
+        return c.json({ ok: true, tool: description });
       } catch (err) {
         return scheduleConnectionError(c, err, "Unable to describe this connection tool.");
       }