@topolo/mcp 0.9.7 → 0.9.8

package/dist/dispatch.js

@@ -271,6 +271,60 @@ var TOOLS = [
       );
     }
   },
+  {
+    name: "topolo_upload_action",
+    title: "Upload content through one Topolo action",
+    description: "Uploads base64 content through an exact action id using its published upload contract. Mutating uploads require confirm:true.",
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        contentBase64: { type: "string", minLength: 4, description: "Canonical base64 content without a data URL prefix." },
+        contentType: { type: "string", minLength: 1 },
+        fileName: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        completionInput: { type: "object", additionalProperties: true },
+        resourceType: { type: "string" },
+        resourceId: { type: "string" },
+        confirm: { type: "boolean" }
+      },
+      required: ["actionId", "contentBase64", "contentType", "fileName"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      const contentBase64 = typeof args["contentBase64"] === "string" ? args["contentBase64"] : "";
+      const contentType = typeof args["contentType"] === "string" ? args["contentType"].trim() : "";
+      const fileName = typeof args["fileName"] === "string" ? args["fileName"].trim() : "";
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
+      if (!isCanonicalBase64(contentBase64)) throw new TopoloMcpPublicError("contentBase64 must be canonical base64.");
+      if (!contentType) throw new TopoloMcpPublicError("contentType is required.");
+      if (!fileName) throw new TopoloMcpPublicError("fileName is required.");
+      const input = args["input"];
+      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
+        throw new TopoloMcpPublicError("input must be an object.");
+      }
+      const completionInput = args["completionInput"];
+      if (completionInput !== void 0 && (!completionInput || typeof completionInput !== "object" || Array.isArray(completionInput))) {
+        throw new TopoloMcpPublicError("completionInput must be an object.");
+      }
+      const resource = optionalResourceContext(args);
+      return topolo.client.uploadActionBase64(
+        actionId,
+        contentBase64,
+        input ?? {},
+        {
+          fileName,
+          contentType,
+          completionInput: completionInput ?? {},
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
+      );
+    }
+  },
   {
     name: "topolo_validate_action",
     title: "Validate Topolo action input",
@@ -574,6 +628,9 @@ var TOOLS = [
     }
   }
 ];
+function isCanonicalBase64(value) {
+  return value.length > 0 && value.length % 4 === 0 && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
 function filterToolsByScopes(tools, scopes) {
   return tools.filter((t) => hasAnyScope(scopes, t.requiredScopes));
 }

package/dist/http.js

@@ -15824,7 +15824,7 @@ var Server = class extends Protocol {
 };
 
 // src/server.ts
-import { TopoloAuthError, TopoloPermissionError } from "@topolo/sdk";
+import { TopoloAuthError, TopoloHttpError, TopoloPermissionError } from "@topolo/sdk";
 
 // src/tools.ts
 import {
@@ -16085,6 +16085,60 @@ var TOOLS = [
       );
     }
   },
+  {
+    name: "topolo_upload_action",
+    title: "Upload content through one Topolo action",
+    description: "Uploads base64 content through an exact action id using its published upload contract. Mutating uploads require confirm:true.",
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        contentBase64: { type: "string", minLength: 4, description: "Canonical base64 content without a data URL prefix." },
+        contentType: { type: "string", minLength: 1 },
+        fileName: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        completionInput: { type: "object", additionalProperties: true },
+        resourceType: { type: "string" },
+        resourceId: { type: "string" },
+        confirm: { type: "boolean" }
+      },
+      required: ["actionId", "contentBase64", "contentType", "fileName"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      const contentBase64 = typeof args["contentBase64"] === "string" ? args["contentBase64"] : "";
+      const contentType = typeof args["contentType"] === "string" ? args["contentType"].trim() : "";
+      const fileName = typeof args["fileName"] === "string" ? args["fileName"].trim() : "";
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
+      if (!isCanonicalBase64(contentBase64)) throw new TopoloMcpPublicError("contentBase64 must be canonical base64.");
+      if (!contentType) throw new TopoloMcpPublicError("contentType is required.");
+      if (!fileName) throw new TopoloMcpPublicError("fileName is required.");
+      const input = args["input"];
+      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
+        throw new TopoloMcpPublicError("input must be an object.");
+      }
+      const completionInput = args["completionInput"];
+      if (completionInput !== void 0 && (!completionInput || typeof completionInput !== "object" || Array.isArray(completionInput))) {
+        throw new TopoloMcpPublicError("completionInput must be an object.");
+      }
+      const resource = optionalResourceContext(args);
+      return topolo.client.uploadActionBase64(
+        actionId,
+        contentBase64,
+        input ?? {},
+        {
+          fileName,
+          contentType,
+          completionInput: completionInput ?? {},
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
+      );
+    }
+  },
   {
     name: "topolo_validate_action",
     title: "Validate Topolo action input",
@@ -16388,6 +16442,9 @@ var TOOLS = [
     }
   }
 ];
+function isCanonicalBase64(value) {
+  return value.length > 0 && value.length % 4 === 0 && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
 function filterToolsByScopes(tools, scopes) {
   return tools.filter((t) => hasAnyScope(scopes, t.requiredScopes));
 }
@@ -16525,16 +16582,36 @@ function buildServer(topolo, scopes, tools = TOOLS) {
       };
     } catch (err) {
       if (err instanceof TopoloPermissionError) {
-        return toolError(`Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`);
+        return toolStructuredError(err, `Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`, {
+          required: err.required
+        });
       }
       if (err instanceof TopoloAuthError) {
-        return toolError("Authentication failed.");
+        return toolStructuredError(err, "Authentication failed.");
+      }
+      if (err instanceof TopoloHttpError) {
+        return toolStructuredError(err, err.message);
       }
       return toolError(publicMcpErrorMessage(err, "Tool execution failed."));
     }
   });
   return server;
 }
+function toolStructuredError(error2, message, extra = {}) {
+  return toolError(JSON.stringify({
+    error: {
+      code: error2.code,
+      status: error2.status,
+      message,
+      service: error2.service,
+      path: error2.path,
+      requestId: error2.requestId,
+      retryAfter: error2.retryAfter,
+      details: error2.body,
+      ...extra
+    }
+  }, null, 2));
+}
 function toolError(message) {
   return {
     isError: true,

package/dist/index.js

@@ -31,19 +31,54 @@ var TopoloSdkError = class extends Error {
   }
 };
 var TopoloAuthError = class extends TopoloSdkError {
-  constructor(message, code = "auth_error") {
+  status;
+  body;
+  service;
+  path;
+  requestId;
+  retryAfter;
+  constructor(message, code = "auth_error", options = {}) {
     super(code, message);
     this.name = "TopoloAuthError";
+    this.status = options.status ?? 401;
+    this.body = options.body;
+    this.service = options.service;
+    this.path = options.path;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
   }
 };
 var TopoloPermissionError = class extends TopoloSdkError {
   required;
-  constructor(message, required) {
+  status;
+  body;
+  service;
+  path;
+  requestId;
+  retryAfter;
+  constructor(message, required, options = {}) {
     super("permission_denied", message);
     this.name = "TopoloPermissionError";
     this.required = required;
+    this.status = options.status ?? 403;
+    this.body = options.body;
+    this.service = options.service;
+    this.path = options.path;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
   }
 };
+function extractHttpErrorCode(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return "http_error";
+  const record = body;
+  if (typeof record.code === "string" && record.code.trim()) return record.code.trim();
+  const nested = record.error;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const code = nested.code;
+    if (typeof code === "string" && code.trim()) return code.trim();
+  }
+  return "http_error";
+}
 var TopoloConfirmationRequiredError = class extends TopoloSdkError {
   constructor(message) {
     super("confirmation_required", message);
@@ -55,13 +90,17 @@ var TopoloHttpError = class extends TopoloSdkError {
   body;
   service;
   path;
-  constructor(service, path, status, body, message) {
-    super("http_error", message ?? `HTTP ${status} from ${service}${path}`);
+  requestId;
+  retryAfter;
+  constructor(service, path, status, body, message, options = {}) {
+    super(extractHttpErrorCode(body), message ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
     this.service = service;
     this.path = path;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
   }
 };
 var APP_API_URLS = {
@@ -271,7 +310,9 @@ var APPLICATIONS = {
         "domains": [
           "brand.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "brand.topolo.app"
+        ],
         "appId": "brand"
       },
       {
@@ -443,7 +484,9 @@ var APPLICATIONS = {
         "domains": [
           "chat.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "chat.topolo.app"
+        ],
         "appId": "chat"
       },
       {
@@ -825,7 +868,9 @@ var APPLICATIONS = {
         "domains": [
           "forms.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "forms.topolo.app"
+        ],
         "appId": "forms"
       },
       {
@@ -1003,7 +1048,9 @@ var APPLICATIONS = {
         "domains": [
           "mail.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "mail.topolo.app"
+        ],
         "appId": "mail"
       },
       {
@@ -1354,7 +1401,9 @@ var APPLICATIONS = {
         "domains": [
           "quro.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "quro.topolo.app"
+        ],
         "appId": null
       }
     ]
@@ -1638,7 +1687,9 @@ var APPLICATIONS = {
         "domains": [
           "survey.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "survey.topolo.app"
+        ],
         "appId": "survey"
       },
       {
@@ -2429,6 +2480,166 @@ function isMultipleOf(value, divisor) {
   const quotient = value / divisor;
   return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * Math.max(1, Math.abs(quotient)) * 4;
 }
+function parseTopoloActionUploadContract(value) {
+  if (!isRecord2(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
+    throw new TopoloSdkError("upload_contract_unavailable", "This action does not publish a supported upload contract.");
+  }
+  const contentTypeField = requiredField(value.contentTypeField, "contentTypeField");
+  const fileNameField = requiredField(value.fileNameField, "fileNameField");
+  const maxBytes = Number(value.maxBytes);
+  const acceptedContentTypes = Array.isArray(value.acceptedContentTypes) ? value.acceptedContentTypes.map((item) => String(item).trim().toLowerCase()).filter(Boolean) : [];
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || acceptedContentTypes.length === 0) {
+    throw new TopoloSdkError("invalid_upload_contract", "The action upload contract must declare maxBytes and acceptedContentTypes.");
+  }
+  if (value.profile === "inline-base64") {
+    return {
+      profile: "inline-base64",
+      contentField: requiredField(value.contentField, "contentField"),
+      contentTypeField,
+      fileNameField,
+      maxBytes,
+      acceptedContentTypes
+    };
+  }
+  const uploadMethod = value.uploadMethod === "PUT" || value.uploadMethod === "POST" ? value.uploadMethod : null;
+  const uploadUrlPath = requiredPath(value.uploadUrlPath, "uploadUrlPath");
+  const complete = value.complete === void 0 ? void 0 : parseCompleteContract(value.complete);
+  if (!uploadMethod) throw new TopoloSdkError("invalid_upload_contract", "The action upload contract has an invalid uploadMethod.");
+  return {
+    profile: "url-session",
+    fileNameField,
+    contentTypeField,
+    sizeField: requiredField(value.sizeField, "sizeField"),
+    maxBytes,
+    acceptedContentTypes,
+    uploadUrlPath,
+    uploadMethod,
+    ...complete ? { complete } : {}
+  };
+}
+function prepareTopoloActionUploadInput(contractValue, content, input, options) {
+  const contract = parseTopoloActionUploadContract(contractValue);
+  if (contract.profile !== "inline-base64") throw unsupportedInlineProfile();
+  const bytes = content instanceof Uint8Array ? content : new Uint8Array(content);
+  if (bytes.byteLength === 0) {
+    throw new TopoloSdkError("invalid_upload_content", "Upload content must not be empty.");
+  }
+  if (bytes.byteLength > contract.maxBytes) {
+    throw new TopoloSdkError("upload_too_large", `Upload content exceeds the ${contract.maxBytes}-byte action limit.`);
+  }
+  return mapUploadInput(contract, bytesToBase64(bytes), input, options);
+}
+function prepareTopoloActionBase64UploadInput(contractValue, contentBase64, input, options) {
+  const contract = parseTopoloActionUploadContract(contractValue);
+  if (contract.profile !== "inline-base64") throw unsupportedInlineProfile();
+  if (!isCanonicalBase64(contentBase64)) {
+    throw new TopoloSdkError("invalid_upload_content", "Upload content must be canonical base64.");
+  }
+  const padding = contentBase64.endsWith("==") ? 2 : contentBase64.endsWith("=") ? 1 : 0;
+  const byteLength = contentBase64.length / 4 * 3 - padding;
+  if (byteLength === 0) throw new TopoloSdkError("invalid_upload_content", "Upload content must not be empty.");
+  if (byteLength > contract.maxBytes) {
+    throw new TopoloSdkError("upload_too_large", `Upload content exceeds the ${contract.maxBytes}-byte action limit.`);
+  }
+  return mapUploadInput(contract, contentBase64, input, options);
+}
+function prepareTopoloUrlSessionUploadInput(contractValue, byteLength, input, options) {
+  const contract = parseTopoloActionUploadContract(contractValue);
+  if (contract.profile !== "url-session") {
+    throw new TopoloSdkError("invalid_upload_contract", "This action does not publish a URL-session upload contract.");
+  }
+  validateUploadMetadata(contract, byteLength, options);
+  return {
+    contract,
+    input: {
+      ...input,
+      [contract.fileNameField]: options.fileName.trim(),
+      [contract.contentTypeField]: options.contentType.trim().toLowerCase(),
+      [contract.sizeField]: byteLength
+    }
+  };
+}
+function topoloUploadResponseValue(response, path) {
+  return path.split(".").reduce((value, segment) => isRecord2(value) ? value[segment] : void 0, response);
+}
+function decodeTopoloActionBase64(contentBase64) {
+  if (!isCanonicalBase64(contentBase64)) {
+    throw new TopoloSdkError("invalid_upload_content", "Upload content must be canonical base64.");
+  }
+  const binary = atob(contentBase64);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function mapUploadInput(contract, contentBase64, input, options) {
+  validateUploadMetadata(contract, Math.max(1, decodedBase64Size(contentBase64)), options);
+  const fileName = options.fileName.trim();
+  const contentType = options.contentType.trim().toLowerCase();
+  return {
+    ...input,
+    [contract.contentField]: contentBase64,
+    [contract.contentTypeField]: contentType,
+    [contract.fileNameField]: fileName
+  };
+}
+function validateUploadMetadata(contract, byteLength, options) {
+  const fileName = options.fileName.trim();
+  const contentType = options.contentType.trim().toLowerCase();
+  if (!fileName) throw new TopoloSdkError("invalid_upload_file_name", "Upload fileName must not be empty.");
+  if (!Number.isSafeInteger(byteLength) || byteLength <= 0) {
+    throw new TopoloSdkError("invalid_upload_content", "Upload content must not be empty.");
+  }
+  if (byteLength > contract.maxBytes) {
+    throw new TopoloSdkError("upload_too_large", `Upload content exceeds the ${contract.maxBytes}-byte action limit.`);
+  }
+  if (!matchesContentType(contentType, contract.acceptedContentTypes)) {
+    throw new TopoloSdkError("unsupported_upload_content_type", `Content type "${contentType}" is not accepted by this action.`);
+  }
+}
+function decodedBase64Size(contentBase64) {
+  const padding = contentBase64.endsWith("==") ? 2 : contentBase64.endsWith("=") ? 1 : 0;
+  return contentBase64.length / 4 * 3 - padding;
+}
+function parseCompleteContract(value) {
+  if (!isRecord2(value)) throw new TopoloSdkError("invalid_upload_contract", "The action upload completion contract is invalid.");
+  return {
+    actionId: requiredPath(value.actionId, "complete.actionId"),
+    inputField: requiredField(value.inputField, "complete.inputField"),
+    responsePath: requiredPath(value.responsePath, "complete.responsePath")
+  };
+}
+function requiredPath(value, name) {
+  const path = typeof value === "string" ? value.trim() : "";
+  if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(path)) {
+    throw new TopoloSdkError("invalid_upload_contract", `The action upload contract has an invalid ${name}.`);
+  }
+  return path;
+}
+function unsupportedInlineProfile() {
+  return new TopoloSdkError("invalid_upload_contract", "This action does not publish an inline-base64 upload contract.");
+}
+function isCanonicalBase64(value) {
+  return value.length > 0 && value.length % 4 === 0 && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
+function requiredField(value, name) {
+  const field = typeof value === "string" ? value.trim() : "";
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(field)) {
+    throw new TopoloSdkError("invalid_upload_contract", `The action upload contract has an invalid ${name}.`);
+  }
+  return field;
+}
+function matchesContentType(contentType, accepted) {
+  return accepted.some((candidate) => candidate === "*/*" || candidate === contentType || candidate.endsWith("/*") && contentType.startsWith(candidate.slice(0, -1)));
+}
+function bytesToBase64(bytes) {
+  let binary = "";
+  const chunkSize = 32768;
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+  }
+  return btoa(binary);
+}
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
 var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
@@ -2505,6 +2716,9 @@ var TopoloClient = class _TopoloClient {
         if (v !== void 0) url.searchParams.set(k, String(v));
       }
     }
+    if (opts.body !== void 0 && opts.rawBody !== void 0) {
+      throw new TopoloSdkError("invalid_request_body", "body and rawBody are mutually exclusive.");
+    }
     const headers = new Headers();
     headers.set("Accept", "application/json");
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
@@ -2539,7 +2753,7 @@ var TopoloClient = class _TopoloClient {
         return await this.fetchImpl(urlStr, {
           method,
           headers: new Headers(headers),
-          body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
+          body: opts.rawBody ?? (opts.body !== void 0 ? JSON.stringify(opts.body) : null),
           signal
         });
       } finally {
@@ -2587,14 +2801,32 @@ var TopoloClient = class _TopoloClient {
         error: message,
         status: res.status
       });
-      if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
+      const errorContext = {
+        status: res.status,
+        body: parsed,
+        service: resolvedService.serviceKey,
+        path: opts.path,
+        requestId: res.headers.get("X-Topolo-Request-Id") || requestId,
+        retryAfter: res.headers.get("Retry-After") || void 0
+      };
+      if (res.status === 401) {
+        throw new TopoloAuthError(describeError(parsed, "Unauthorized"), "auth_error", errorContext);
+      }
       if (res.status === 403) {
         throw new TopoloPermissionError(
           describeError(parsed, "Permission denied"),
-          extractRequired(parsed)
+          extractRequired(parsed),
+          errorContext
         );
       }
-      throw new TopoloHttpError(resolvedService.serviceKey, opts.path, res.status, parsed);
+      throw new TopoloHttpError(
+        resolvedService.serviceKey,
+        opts.path,
+        res.status,
+        parsed,
+        message,
+        errorContext
+      );
     }
     this.emit({
       phase: "response",
@@ -2753,7 +2985,7 @@ var TopoloClient = class _TopoloClient {
     }
     const entries = [];
     for (const item of raw) {
-      if (!isRecord2(item)) continue;
+      if (!isRecord3(item)) continue;
       const s = item;
       const appId = typeof s.app_id === "string" ? s.app_id : typeof s.id === "string" ? s.id : null;
       if (!appId) continue;
@@ -2828,8 +3060,8 @@ var TopoloClient = class _TopoloClient {
       "app_topolo_auth.service_api_key_resources.list",
       { appId: service.appId }
     );
-    const payload = isRecord2(response) && isRecord2(response.data) ? response.data : response;
-    if (!isRecord2(payload) || !Array.isArray(payload.resources)) {
+    const payload = isRecord3(response) && isRecord3(response.data) ? response.data : response;
+    if (!isRecord3(payload) || !Array.isArray(payload.resources)) {
       throw new TopoloSdkError("resource_catalog_unavailable", "TopoloAuth did not return bindable resources.");
     }
     return {
@@ -2935,6 +3167,71 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input, options);
   }
+  async uploadAction(action, content, input, options) {
+    const entry = await this.getAction(action);
+    const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
+    if (contract.profile === "url-session") {
+      const bytes = content instanceof Uint8Array ? content : new Uint8Array(content);
+      return this.executeUrlSessionUpload(entry, contract, bytes, input, options);
+    }
+    const uploadInput = prepareTopoloActionUploadInput(entry.agentContract?.upload, content, input, options);
+    return this.executeResolvedAction(entry, uploadInput, options);
+  }
+  async uploadActionBase64(action, contentBase64, input, options) {
+    const entry = await this.getAction(action);
+    const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
+    if (contract.profile === "url-session") {
+      return this.executeUrlSessionUpload(entry, contract, decodeTopoloActionBase64(contentBase64), input, options);
+    }
+    const uploadInput = prepareTopoloActionBase64UploadInput(entry.agentContract?.upload, contentBase64, input, options);
+    return this.executeResolvedAction(entry, uploadInput, options);
+  }
+  async executeUrlSessionUpload(entry, contract, bytes, input, options) {
+    const prepared = prepareTopoloUrlSessionUploadInput(contract, bytes.byteLength, input, options);
+    const initiation = await this.executeResolvedAction(entry, prepared.input, options);
+    const uploadUrl = topoloUploadResponseValue(initiation, contract.uploadUrlPath);
+    if (typeof uploadUrl !== "string" || !uploadUrl.trim()) {
+      throw new TopoloSdkError("invalid_upload_response", `Upload action response is missing ${contract.uploadUrlPath}.`);
+    }
+    await this.putUrlSessionContent(entry, uploadUrl, contract.uploadMethod, bytes, options);
+    if (!contract.complete) return initiation;
+    const completionValue = topoloUploadResponseValue(initiation, contract.complete.responsePath);
+    if (typeof completionValue !== "string" || !completionValue.trim()) {
+      throw new TopoloSdkError("invalid_upload_response", `Upload action response is missing ${contract.complete.responsePath}.`);
+    }
+    const completion = await this.getAction(contract.complete.actionId);
+    return this.executeResolvedAction(completion, {
+      ...options.completionInput ?? {},
+      [contract.complete.inputField]: completionValue
+    }, options);
+  }
+  async putUrlSessionContent(entry, uploadUrl, method, bytes, options) {
+    const service = entry.appSlug || entry.appId;
+    const resolved = entry.apiBaseUrl ? { serviceKey: normalizeLookupKey(service), baseUrl: requireHttpOrigin(entry.apiBaseUrl) } : await this.resolveRequestService(service);
+    const target = new URL(uploadUrl, resolved.baseUrl.endsWith("/") ? resolved.baseUrl : `${resolved.baseUrl}/`);
+    const body = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    if (target.origin === new URL(resolved.baseUrl).origin) {
+      await this.request({
+        service,
+        baseUrl: resolved.baseUrl,
+        path: target.toString(),
+        method,
+        rawBody: body,
+        headers: { "Content-Type": options.contentType.trim().toLowerCase() },
+        resource: options.resource,
+        confirm: options.confirm
+      });
+      return;
+    }
+    const response = await this.fetchImpl(target, {
+      method,
+      headers: { "Content-Type": options.contentType.trim().toLowerCase() },
+      body
+    });
+    if (!response.ok) {
+      throw new TopoloHttpError(service, target.pathname, response.status, await response.text(), `Upload transport failed with HTTP ${response.status}.`);
+    }
+  }
   async validateActionInput(action, input = {}) {
     const entry = await this.getAction(action);
     return { action: entry, validation: validateTopoloActionInput(entry.inputSchema, input) };
@@ -3093,7 +3390,7 @@ function resolveConfiguredAppId(slug, appIds) {
   return null;
 }
 function normalizeApiKeyResourceMetadata(input) {
-  if (!isRecord2(input)) return null;
+  if (!isRecord3(input)) return null;
   const resourceType = readString(input.resourceType ?? input.resource_type);
   const label = readString(input.label);
   const emptyLabel = readString(input.emptyLabel ?? input.empty_label);
@@ -3127,7 +3424,7 @@ function normalizeApiKeyResourceMetadataList(input) {
   return resources;
 }
 function normalizeBindableResource(input) {
-  if (!isRecord2(input)) return null;
+  if (!isRecord3(input)) return null;
   const resourceType = readString(input.resourceType ?? input.resource_type);
   const resourceId = readString(input.resourceId ?? input.resource_id);
   if (!resourceType || !resourceId) return null;
@@ -3138,13 +3435,13 @@ function normalizeBindableResource(input) {
     slug: readOptionalString(input.slug),
     status: readOptionalString(input.status),
     organizationId: readOptionalString(input.organizationId ?? input.organization_id),
-    metadata: isRecord2(input.metadata) ? input.metadata : {}
+    metadata: isRecord3(input.metadata) ? input.metadata : {}
   };
 }
 function normalizeResourceBindings(input) {
   if (!Array.isArray(input)) return [];
   return input.flatMap((binding) => {
-    if (!isRecord2(binding)) return [];
+    if (!isRecord3(binding)) return [];
     const resourceType = readString(binding.resourceType ?? binding.resource_type);
     const resourceId = readString(binding.resourceId ?? binding.resource_id);
     return resourceType && resourceId ? [{ resourceType, resourceId }] : [];
@@ -3157,7 +3454,7 @@ function readOptionalString(value) {
   const normalized = readString(value);
   return normalized || null;
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
@@ -3229,14 +3526,14 @@ function catalogSearchQuery(options) {
   return query;
 }
 function normalizeCatalogPage(value) {
-  if (!isRecord2(value)) return { nextCursor: null, hasMore: false };
+  if (!isRecord3(value)) return { nextCursor: null, hasMore: false };
   return {
     nextCursor: typeof value.nextCursor === "string" && value.nextCursor ? value.nextCursor : null,
     hasMore: value.hasMore === true
   };
 }
 function normalizeServiceCatalogEntry(item) {
-  if (!isRecord2(item)) return null;
+  if (!isRecord3(item)) return null;
   const appId = typeof item.app_id === "string" ? item.app_id : typeof item.id === "string" ? item.id : null;
   if (!appId) return null;
   const permissions = Array.isArray(item.granted_permissions) ? item.granted_permissions.filter(
@@ -3482,23 +3779,50 @@ var TopoloSdkError2 = class extends Error {
   }
 };
 var TopoloAuthError2 = class extends TopoloSdkError2 {
-  constructor(message, code = "auth_error") {
+  status;
+  body;
+  service;
+  path;
+  requestId;
+  retryAfter;
+  constructor(message, code = "auth_error", options = {}) {
     super(code, message);
     this.name = "TopoloAuthError";
+    this.status = options.status ?? 401;
+    this.body = options.body;
+    this.service = options.service;
+    this.path = options.path;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
   }
 };
+function extractHttpErrorCode2(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return "http_error";
+  const record = body;
+  if (typeof record.code === "string" && record.code.trim()) return record.code.trim();
+  const nested = record.error;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const code = nested.code;
+    if (typeof code === "string" && code.trim()) return code.trim();
+  }
+  return "http_error";
+}
 var TopoloHttpError2 = class extends TopoloSdkError2 {
   status;
   body;
   service;
   path;
-  constructor(service, path, status, body, message) {
-    super("http_error", message ?? `HTTP ${status} from ${service}${path}`);
+  requestId;
+  retryAfter;
+  constructor(service, path, status, body, message, options = {}) {
+    super(extractHttpErrorCode2(body), message ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
     this.service = service;
     this.path = path;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
   }
 };
 var APP_API_URLS2 = {
@@ -4126,6 +4450,60 @@ var TOOLS = [
       );
     }
   },
+  {
+    name: "topolo_upload_action",
+    title: "Upload content through one Topolo action",
+    description: "Uploads base64 content through an exact action id using its published upload contract. Mutating uploads require confirm:true.",
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        contentBase64: { type: "string", minLength: 4, description: "Canonical base64 content without a data URL prefix." },
+        contentType: { type: "string", minLength: 1 },
+        fileName: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        completionInput: { type: "object", additionalProperties: true },
+        resourceType: { type: "string" },
+        resourceId: { type: "string" },
+        confirm: { type: "boolean" }
+      },
+      required: ["actionId", "contentBase64", "contentType", "fileName"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      const contentBase64 = typeof args["contentBase64"] === "string" ? args["contentBase64"] : "";
+      const contentType = typeof args["contentType"] === "string" ? args["contentType"].trim() : "";
+      const fileName = typeof args["fileName"] === "string" ? args["fileName"].trim() : "";
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
+      if (!isCanonicalBase642(contentBase64)) throw new TopoloMcpPublicError("contentBase64 must be canonical base64.");
+      if (!contentType) throw new TopoloMcpPublicError("contentType is required.");
+      if (!fileName) throw new TopoloMcpPublicError("fileName is required.");
+      const input = args["input"];
+      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
+        throw new TopoloMcpPublicError("input must be an object.");
+      }
+      const completionInput = args["completionInput"];
+      if (completionInput !== void 0 && (!completionInput || typeof completionInput !== "object" || Array.isArray(completionInput))) {
+        throw new TopoloMcpPublicError("completionInput must be an object.");
+      }
+      const resource = optionalResourceContext(args);
+      return topolo.client.uploadActionBase64(
+        actionId,
+        contentBase64,
+        input ?? {},
+        {
+          fileName,
+          contentType,
+          completionInput: completionInput ?? {},
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
+      );
+    }
+  },
   {
     name: "topolo_validate_action",
     title: "Validate Topolo action input",
@@ -4429,6 +4807,9 @@ var TOOLS = [
     }
   }
 ];
+function isCanonicalBase642(value) {
+  return value.length > 0 && value.length % 4 === 0 && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
 function filterToolsByScopes(tools, scopes) {
   return tools.filter((t) => hasAnyScope(scopes, t.requiredScopes));
 }
@@ -4566,16 +4947,36 @@ function buildServer(topolo, scopes, tools = TOOLS) {
       };
     } catch (err) {
       if (err instanceof TopoloPermissionError) {
-        return toolError(`Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`);
+        return toolStructuredError(err, `Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`, {
+          required: err.required
+        });
       }
       if (err instanceof TopoloAuthError) {
-        return toolError("Authentication failed.");
+        return toolStructuredError(err, "Authentication failed.");
+      }
+      if (err instanceof TopoloHttpError) {
+        return toolStructuredError(err, err.message);
       }
       return toolError(publicMcpErrorMessage(err, "Tool execution failed."));
     }
   });
   return server;
 }
+function toolStructuredError(error, message, extra = {}) {
+  return toolError(JSON.stringify({
+    error: {
+      code: error.code,
+      status: error.status,
+      message,
+      service: error.service,
+      path: error.path,
+      requestId: error.requestId,
+      retryAfter: error.retryAfter,
+      details: error.body,
+      ...extra
+    }
+  }, null, 2));
+}
 async function advertisedToolNames(topolo, scopes, tools = TOOLS) {
   return (await buildTopoloTools(topolo, scopes, tools)).map((t) => t.name);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/mcp",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "Model Context Protocol server for the Topolo platform. Exposes scope-gated tools that third-party agents (Claude, Codex, etc.) can call natively.",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "dist"
   ],
   "scripts": {
-    "build:sdk": "pnpm --dir ../topolo-sdk build",
+    "build:sdk": "python3 ../../tooling/with-resource-lock.py ../topolo-sdk -- pnpm --dir ../topolo-sdk build",
     "prebuild": "pnpm run build:sdk",
     "build": "tsup",
     "dev": "tsup --watch",
@@ -36,7 +36,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "peerDependencies": {
-    "@topolo/sdk": "^0.9.6"
+    "@topolo/sdk": "^0.9.8"
   },
   "devDependencies": {
     "@topolo/sdk": "file:../topolo-sdk",