@topolo/mcp 0.9.4 → 0.9.5

package/README.md

@@ -118,6 +118,7 @@ credentials already carry their own immutable context.
    active stored credential. **Refuse to start** if none is available.
 2. Call `GET /api/me` to load the user's granted scopes + role.
 3. Connect the stdio transport and begin serving MCP requests.
+
 4. Advertise a fixed, bounded discovery/invocation surface. Agents search one
    application at a time and call exact action IDs; the server never expands
    one MCP tool per action or materializes the global catalog.
@@ -126,6 +127,19 @@ Startup is synchronous and fast (< 500 ms typical). If the credential is
 rejected, the process logs the error to stderr and exits non-zero — host
 clients surface that as a failed server launch.
 
+## Data privacy boundary
+
+TopoloMCP is a transport adapter and does not persist customer data. It has no
+database, KV, R2, Durable Object, filesystem-write, analytics, or log-storage
+binding. Credentials remain in the caller-owned environment or the shared CLI
+credential store, and every request is authorized by the target Topolo service.
+
+Only messages raised by TopoloMCP's own input validators are returned verbatim.
+Authentication, SDK, provider, session-construction, and unexpected runtime
+errors are replaced with stable non-sensitive messages before they reach MCP
+responses or stderr. Target services remain responsible for retention, export,
+deletion, encryption, and audit storage for the data they own.
+
 ## Tools
 
 | Tool                         | Required scopes       | Destructive hint |

package/dist/dispatch.js

@@ -50,6 +50,17 @@ function splitService(servicePart) {
   return [servicePart.slice(0, idx), servicePart.slice(idx + 1)];
 }
 
+// src/errors.ts
+var TopoloMcpPublicError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TopoloMcpPublicError";
+  }
+};
+function publicMcpErrorMessage(error, fallback) {
+  return error instanceof TopoloMcpPublicError ? error.message : fallback;
+}
+
 // src/tools.ts
 var APPLICATION_IDS = Object.keys(APPLICATIONS).sort();
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
@@ -58,7 +69,7 @@ function optionalResourceContext(args) {
   const resourceId = typeof args["resourceId"] === "string" ? args["resourceId"].trim() : "";
   if (!resourceType && !resourceId) return void 0;
   if (!resourceType || !resourceId) {
-    throw new Error("resourceType and resourceId must be provided together.");
+    throw new TopoloMcpPublicError("resourceType and resourceId must be provided together.");
   }
   return { resourceType, resourceId };
 }
@@ -140,7 +151,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
-      if (!service) throw new Error("service is required for bounded action discovery.");
+      if (!service) throw new TopoloMcpPublicError("service is required for bounded action discovery.");
       return topolo.client.searchActions({
         service,
         query: typeof args["query"] === "string" ? args["query"] : void 0,
@@ -169,7 +180,7 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const application = args["application"];
       if (typeof application !== "string" || !application.trim()) {
-        throw new Error("`application` must be a non-empty string.");
+        throw new TopoloMcpPublicError("`application` must be a non-empty string.");
       }
       return { application: await topolo.client.getService(application) };
     }
@@ -188,7 +199,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       return { action: await topolo.client.getAction(actionId) };
     }
   },
@@ -211,10 +222,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.readAction(
@@ -244,10 +255,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.callAction(
@@ -277,10 +288,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       return topolo.client.validateActionInput(actionId, input ?? {});
     }
@@ -305,10 +316,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.planAction(
@@ -335,7 +346,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const action = await topolo.client.getAction(actionId);
       return {
         actionId: action.actionId,
@@ -358,7 +369,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
-      if (!service) throw new Error("service is required.");
+      if (!service) throw new TopoloMcpPublicError("service is required.");
       return topolo.client.searchActions({ service, query: "capabilities", limit: 100 });
     }
   },
@@ -376,7 +387,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const application = typeof args["application"] === "string" ? args["application"].trim() : "";
-      if (!application) throw new Error("application is required.");
+      if (!application) throw new TopoloMcpPublicError("application is required.");
       const entry = await topolo.client.getService(application);
       return {
         application: { appId: entry.appId, slug: entry.slug, name: entry.name },
@@ -398,7 +409,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const application = typeof args["application"] === "string" ? args["application"].trim() : "";
-      if (!application) throw new Error("application is required.");
+      if (!application) throw new TopoloMcpPublicError("application is required.");
       return topolo.client.listBindableResources(application);
     }
   },
@@ -429,7 +440,7 @@ var TOOLS = [
         };
       }
       if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
-        throw new Error(
+        throw new TopoloMcpPublicError(
           `Unknown application "${String(application)}". ${formatKnownValues(APPLICATION_IDS, "applications")}`
         );
       }
@@ -467,7 +478,7 @@ var TOOLS = [
       const application = args["application"];
       const failOn = args["failOn"];
       if (failOn !== void 0 && typeof failOn !== "string") {
-        throw new Error("failOn must be one of: missing, needs_review, partial");
+        throw new TopoloMcpPublicError("failOn must be one of: missing, needs_review, partial");
       }
       const gate = failOn ? normalizeFailOn(failOn) : null;
       let report;
@@ -476,7 +487,7 @@ var TOOLS = [
         return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
       }
       if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
-        throw new Error(
+        throw new TopoloMcpPublicError(
           `Unknown application "${String(application)}". ${formatKnownValues(APPLICATION_IDS, "applications")}`
         );
       }
@@ -536,14 +547,14 @@ var TOOLS = [
       const service = args["service"];
       const path = args["path"];
       if (typeof service !== "string" || !service.trim()) {
-        throw new Error("service is required. Call topolo_search_applications first to discover callable services.");
+        throw new TopoloMcpPublicError("service is required. Call topolo_search_applications first to discover callable services.");
       }
       if (typeof path !== "string" || !path) {
-        throw new Error("path is required");
+        throw new TopoloMcpPublicError("path is required");
       }
       const methodRaw = args["method"] ?? "GET";
       if (typeof methodRaw !== "string" || !HTTP_METHODS.includes(methodRaw)) {
-        throw new Error(`Unknown HTTP method "${String(methodRaw)}"`);
+        throw new TopoloMcpPublicError(`Unknown HTTP method "${String(methodRaw)}"`);
       }
       const method = methodRaw;
       const query = args["query"];
@@ -599,7 +610,7 @@ function normalizeFailOn(value) {
   if (normalized === "missing" || normalized === "needs_review" || normalized === "partial") {
     return normalized;
   }
-  throw new Error("failOn must be one of: missing, needs_review, partial");
+  throw new TopoloMcpPublicError("failOn must be one of: missing, needs_review, partial");
 }
 function statusesAtOrWorse(threshold) {
   if (threshold === "missing") return ["missing"];
@@ -694,14 +705,14 @@ async function dispatchTopoloTool(input) {
       return {
         ok: false,
         reason: "auth",
-        error: `Auth error: ${err.message}`,
+        error: "Authentication failed.",
         durationMs: Date.now() - started
       };
     }
     return {
       ok: false,
       reason: "handler",
-      error: err instanceof Error ? err.message : String(err),
+      error: publicMcpErrorMessage(err, "Tool execution failed."),
       durationMs: Date.now() - started
     };
   }

package/dist/http.js

@@ -14217,6 +14217,17 @@ function credentialFingerprint(credential) {
   return (hash >>> 0).toString(16).padStart(8, "0");
 }
 
+// src/errors.ts
+var TopoloMcpPublicError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TopoloMcpPublicError";
+  }
+};
+function publicMcpErrorMessage(error2, fallback) {
+  return error2 instanceof TopoloMcpPublicError ? error2.message : fallback;
+}
+
 // ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.26.0_@cfworker+json-schema@4.1.1_zod@4.4.3/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
 function isZ4Schema(s) {
   const schema = s;
@@ -15872,7 +15883,7 @@ function optionalResourceContext(args) {
   const resourceId = typeof args["resourceId"] === "string" ? args["resourceId"].trim() : "";
   if (!resourceType && !resourceId) return void 0;
   if (!resourceType || !resourceId) {
-    throw new Error("resourceType and resourceId must be provided together.");
+    throw new TopoloMcpPublicError("resourceType and resourceId must be provided together.");
   }
   return { resourceType, resourceId };
 }
@@ -15954,7 +15965,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
-      if (!service) throw new Error("service is required for bounded action discovery.");
+      if (!service) throw new TopoloMcpPublicError("service is required for bounded action discovery.");
       return topolo.client.searchActions({
         service,
         query: typeof args["query"] === "string" ? args["query"] : void 0,
@@ -15983,7 +15994,7 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const application = args["application"];
       if (typeof application !== "string" || !application.trim()) {
-        throw new Error("`application` must be a non-empty string.");
+        throw new TopoloMcpPublicError("`application` must be a non-empty string.");
       }
       return { application: await topolo.client.getService(application) };
     }
@@ -16002,7 +16013,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       return { action: await topolo.client.getAction(actionId) };
     }
   },
@@ -16025,10 +16036,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.readAction(
@@ -16058,10 +16069,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.callAction(
@@ -16091,10 +16102,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       return topolo.client.validateActionInput(actionId, input ?? {});
     }
@@ -16119,10 +16130,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.planAction(
@@ -16149,7 +16160,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const action = await topolo.client.getAction(actionId);
       return {
         actionId: action.actionId,
@@ -16172,7 +16183,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
-      if (!service) throw new Error("service is required.");
+      if (!service) throw new TopoloMcpPublicError("service is required.");
       return topolo.client.searchActions({ service, query: "capabilities", limit: 100 });
     }
   },
@@ -16190,7 +16201,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const application = typeof args["application"] === "string" ? args["application"].trim() : "";
-      if (!application) throw new Error("application is required.");
+      if (!application) throw new TopoloMcpPublicError("application is required.");
       const entry = await topolo.client.getService(application);
       return {
         application: { appId: entry.appId, slug: entry.slug, name: entry.name },
@@ -16212,7 +16223,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const application = typeof args["application"] === "string" ? args["application"].trim() : "";
-      if (!application) throw new Error("application is required.");
+      if (!application) throw new TopoloMcpPublicError("application is required.");
       return topolo.client.listBindableResources(application);
     }
   },
@@ -16243,7 +16254,7 @@ var TOOLS = [
         };
       }
       if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
-        throw new Error(
+        throw new TopoloMcpPublicError(
           `Unknown application "${String(application)}". ${formatKnownValues(APPLICATION_IDS, "applications")}`
         );
       }
@@ -16281,7 +16292,7 @@ var TOOLS = [
       const application = args["application"];
       const failOn = args["failOn"];
       if (failOn !== void 0 && typeof failOn !== "string") {
-        throw new Error("failOn must be one of: missing, needs_review, partial");
+        throw new TopoloMcpPublicError("failOn must be one of: missing, needs_review, partial");
       }
       const gate = failOn ? normalizeFailOn(failOn) : null;
       let report;
@@ -16290,7 +16301,7 @@ var TOOLS = [
         return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
       }
       if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
-        throw new Error(
+        throw new TopoloMcpPublicError(
           `Unknown application "${String(application)}". ${formatKnownValues(APPLICATION_IDS, "applications")}`
         );
       }
@@ -16350,14 +16361,14 @@ var TOOLS = [
       const service = args["service"];
       const path = args["path"];
       if (typeof service !== "string" || !service.trim()) {
-        throw new Error("service is required. Call topolo_search_applications first to discover callable services.");
+        throw new TopoloMcpPublicError("service is required. Call topolo_search_applications first to discover callable services.");
       }
       if (typeof path !== "string" || !path) {
-        throw new Error("path is required");
+        throw new TopoloMcpPublicError("path is required");
       }
       const methodRaw = args["method"] ?? "GET";
       if (typeof methodRaw !== "string" || !HTTP_METHODS.includes(methodRaw)) {
-        throw new Error(`Unknown HTTP method "${String(methodRaw)}"`);
+        throw new TopoloMcpPublicError(`Unknown HTTP method "${String(methodRaw)}"`);
       }
       const method = methodRaw;
       const query = args["query"];
@@ -16413,7 +16424,7 @@ function normalizeFailOn(value) {
   if (normalized === "missing" || normalized === "needs_review" || normalized === "partial") {
     return normalized;
   }
-  throw new Error("failOn must be one of: missing, needs_review, partial");
+  throw new TopoloMcpPublicError("failOn must be one of: missing, needs_review, partial");
 }
 function statusesAtOrWorse(threshold) {
   if (threshold === "missing") return ["missing"];
@@ -16517,9 +16528,9 @@ function buildServer(topolo, scopes, tools = TOOLS) {
         return toolError(`Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`);
       }
       if (err instanceof TopoloAuthError) {
-        return toolError(`Auth error: ${err.message}`);
+        return toolError("Authentication failed.");
       }
-      return toolError(err instanceof Error ? err.message : String(err));
+      return toolError(publicMcpErrorMessage(err, "Tool execution failed."));
     }
   });
   return server;
@@ -16622,11 +16633,11 @@ function createTopoloMcpHttpHandler(options = {}) {
       session = await buildSessionForRequest(credential);
     } catch (err) {
       if (err instanceof TopoloAuthError2) {
-        return jsonRpcError(401, `Credential rejected: ${err.message}`, -32001);
+        return jsonRpcError(401, "Credential rejected.", -32001);
       }
       return jsonRpcError(
         500,
-        `Failed to initialize MCP session: ${err instanceof Error ? err.message : String(err)}`
+        publicMcpErrorMessage(err, "Failed to initialize MCP session.")
       );
     }
     return session.transport.handleRequest(request);

package/dist/index.js

@@ -3899,6 +3899,17 @@ function splitService(servicePart) {
   return [servicePart.slice(0, idx), servicePart.slice(idx + 1)];
 }
 
+// src/errors.ts
+var TopoloMcpPublicError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TopoloMcpPublicError";
+  }
+};
+function publicMcpErrorMessage(error, fallback) {
+  return error instanceof TopoloMcpPublicError ? error.message : fallback;
+}
+
 // src/tools.ts
 var APPLICATION_IDS = Object.keys(APPLICATIONS).sort();
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
@@ -3907,7 +3918,7 @@ function optionalResourceContext(args) {
   const resourceId = typeof args["resourceId"] === "string" ? args["resourceId"].trim() : "";
   if (!resourceType && !resourceId) return void 0;
   if (!resourceType || !resourceId) {
-    throw new Error("resourceType and resourceId must be provided together.");
+    throw new TopoloMcpPublicError("resourceType and resourceId must be provided together.");
   }
   return { resourceType, resourceId };
 }
@@ -3989,7 +4000,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
-      if (!service) throw new Error("service is required for bounded action discovery.");
+      if (!service) throw new TopoloMcpPublicError("service is required for bounded action discovery.");
       return topolo.client.searchActions({
         service,
         query: typeof args["query"] === "string" ? args["query"] : void 0,
@@ -4018,7 +4029,7 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const application = args["application"];
       if (typeof application !== "string" || !application.trim()) {
-        throw new Error("`application` must be a non-empty string.");
+        throw new TopoloMcpPublicError("`application` must be a non-empty string.");
       }
       return { application: await topolo.client.getService(application) };
     }
@@ -4037,7 +4048,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       return { action: await topolo.client.getAction(actionId) };
     }
   },
@@ -4060,10 +4071,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.readAction(
@@ -4093,10 +4104,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.callAction(
@@ -4126,10 +4137,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       return topolo.client.validateActionInput(actionId, input ?? {});
     }
@@ -4154,10 +4165,10 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const input = args["input"];
       if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new Error("input must be an object.");
+        throw new TopoloMcpPublicError("input must be an object.");
       }
       const resource = optionalResourceContext(args);
       return topolo.client.planAction(
@@ -4184,7 +4195,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
-      if (!actionId) throw new Error("actionId is required.");
+      if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
       const action = await topolo.client.getAction(actionId);
       return {
         actionId: action.actionId,
@@ -4207,7 +4218,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
-      if (!service) throw new Error("service is required.");
+      if (!service) throw new TopoloMcpPublicError("service is required.");
       return topolo.client.searchActions({ service, query: "capabilities", limit: 100 });
     }
   },
@@ -4225,7 +4236,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const application = typeof args["application"] === "string" ? args["application"].trim() : "";
-      if (!application) throw new Error("application is required.");
+      if (!application) throw new TopoloMcpPublicError("application is required.");
       const entry = await topolo.client.getService(application);
       return {
         application: { appId: entry.appId, slug: entry.slug, name: entry.name },
@@ -4247,7 +4258,7 @@ var TOOLS = [
     },
     handler: async (topolo, args) => {
       const application = typeof args["application"] === "string" ? args["application"].trim() : "";
-      if (!application) throw new Error("application is required.");
+      if (!application) throw new TopoloMcpPublicError("application is required.");
       return topolo.client.listBindableResources(application);
     }
   },
@@ -4278,7 +4289,7 @@ var TOOLS = [
         };
       }
       if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
-        throw new Error(
+        throw new TopoloMcpPublicError(
           `Unknown application "${String(application)}". ${formatKnownValues(APPLICATION_IDS, "applications")}`
         );
       }
@@ -4316,7 +4327,7 @@ var TOOLS = [
       const application = args["application"];
       const failOn = args["failOn"];
       if (failOn !== void 0 && typeof failOn !== "string") {
-        throw new Error("failOn must be one of: missing, needs_review, partial");
+        throw new TopoloMcpPublicError("failOn must be one of: missing, needs_review, partial");
       }
       const gate = failOn ? normalizeFailOn(failOn) : null;
       let report;
@@ -4325,7 +4336,7 @@ var TOOLS = [
         return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
       }
       if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
-        throw new Error(
+        throw new TopoloMcpPublicError(
           `Unknown application "${String(application)}". ${formatKnownValues(APPLICATION_IDS, "applications")}`
         );
       }
@@ -4385,14 +4396,14 @@ var TOOLS = [
       const service = args["service"];
       const path = args["path"];
       if (typeof service !== "string" || !service.trim()) {
-        throw new Error("service is required. Call topolo_search_applications first to discover callable services.");
+        throw new TopoloMcpPublicError("service is required. Call topolo_search_applications first to discover callable services.");
       }
       if (typeof path !== "string" || !path) {
-        throw new Error("path is required");
+        throw new TopoloMcpPublicError("path is required");
       }
       const methodRaw = args["method"] ?? "GET";
       if (typeof methodRaw !== "string" || !HTTP_METHODS.includes(methodRaw)) {
-        throw new Error(`Unknown HTTP method "${String(methodRaw)}"`);
+        throw new TopoloMcpPublicError(`Unknown HTTP method "${String(methodRaw)}"`);
       }
       const method = methodRaw;
       const query = args["query"];
@@ -4448,7 +4459,7 @@ function normalizeFailOn(value) {
   if (normalized === "missing" || normalized === "needs_review" || normalized === "partial") {
     return normalized;
   }
-  throw new Error("failOn must be one of: missing, needs_review, partial");
+  throw new TopoloMcpPublicError("failOn must be one of: missing, needs_review, partial");
 }
 function statusesAtOrWorse(threshold) {
   if (threshold === "missing") return ["missing"];
@@ -4552,9 +4563,9 @@ function buildServer(topolo, scopes, tools = TOOLS) {
         return toolError(`Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`);
       }
       if (err instanceof TopoloAuthError) {
-        return toolError(`Auth error: ${err.message}`);
+        return toolError("Authentication failed.");
       }
-      return toolError(err instanceof Error ? err.message : String(err));
+      return toolError(publicMcpErrorMessage(err, "Tool execution failed."));
     }
   });
   return server;
@@ -4588,7 +4599,7 @@ var DEFAULT_DEPENDENCIES = {
 function resolvePinnedContextKey(profile, selector) {
   const normalized = selector.trim().toLowerCase();
   if (!normalized) {
-    throw new Error("TOPOLO_CONTEXT must not be empty");
+    throw new TopoloMcpPublicError("TOPOLO_CONTEXT must not be empty");
   }
   const contexts = Object.entries(profile.contexts ?? {});
   const exact = contexts.find(([key]) => key.toLowerCase() === normalized);
@@ -4600,16 +4611,16 @@ function resolvePinnedContextKey(profile, selector) {
   ].some((value) => String(value || "").trim().toLowerCase() === normalized));
   if (matches.length === 1) return matches[0][0];
   if (matches.length > 1) {
-    throw new Error(`TOPOLO_CONTEXT "${selector}" is ambiguous; use an exact context key`);
+    throw new TopoloMcpPublicError(`TOPOLO_CONTEXT "${selector}" is ambiguous; use an exact context key`);
   }
-  throw new Error(`TOPOLO_CONTEXT "${selector}" is not signed in for this environment`);
+  throw new TopoloMcpPublicError(`TOPOLO_CONTEXT "${selector}" is not signed in for this environment`);
 }
 async function resolveMcpCredential(environment, selector = process.env.TOPOLO_CONTEXT, dependencies = DEFAULT_DEPENDENCIES) {
   const environmentCredential = dependencies.resolveCredentialFromEnv();
   const requestedSelector = selector?.trim();
   if (environmentCredential) {
     if (requestedSelector) {
-      throw new Error("TOPOLO_CONTEXT cannot be combined with an environment credential");
+      throw new TopoloMcpPublicError("TOPOLO_CONTEXT cannot be combined with an environment credential");
     }
     return { credential: environmentCredential, contextKey: null };
   }
@@ -4690,15 +4701,14 @@ async function loadScopes(topolo) {
     };
   } catch (err) {
     if (err instanceof TopoloAuthError) {
-      process.stderr.write(`TopoloMCP: credential rejected \u2014 ${err.message}
-`);
+      process.stderr.write("TopoloMCP: credential rejected.\n");
       process.exit(1);
     }
     throw err;
   }
 }
 main().catch((err) => {
-  process.stderr.write(`TopoloMCP fatal: ${err instanceof Error ? err.message : String(err)}
+  process.stderr.write(`TopoloMCP fatal: ${publicMcpErrorMessage(err, "Unexpected startup failure.")}
 `);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/mcp",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "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": {