@topolo/mcp 0.9.4 → 0.9.6

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

@@ -301,7 +301,9 @@ var APPLICATIONS = {
         "domains": [
           "bugfix.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "bugfix.topolo.app"
+        ],
         "appId": "bugfix"
       }
     ]
@@ -417,7 +419,9 @@ var APPLICATIONS = {
         "domains": [
           "capacity.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "capacity.topolo.app"
+        ],
         "appId": "capacity"
       }
     ]
@@ -1159,7 +1163,9 @@ var APPLICATIONS = {
         "domains": [
           "observability-watch.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "observability-watch.topolo.app"
+        ],
         "appId": "observability_watch"
       }
     ]
@@ -3899,6 +3905,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 +3924,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 +4006,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 +4035,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 +4054,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 +4077,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 +4110,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 +4143,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 +4171,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 +4201,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 +4224,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 +4242,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 +4264,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 +4295,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 +4333,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 +4342,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 +4402,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 +4465,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 +4569,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 +4605,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 +4617,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 };
   }
@@ -4643,21 +4660,49 @@ async function resolveMcpCredential(environment, selector = process.env.TOPOLO_C
 }
 
 // src/index.ts
-async function main() {
-  const environment = normalizeEnvironment(process.env.TOPOLO_ENV);
-  const resolvedCredential = await resolveMcpCredential(environment);
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { resolve } from "path";
+function readStdioEnvironment() {
+  return process.env.TOPOLO_ENV;
+}
+function createStdioTransport() {
+  return new StdioServerTransport();
+}
+function writeStdioError(message) {
+  process.stderr.write(message);
+}
+function exitStdioProcess(code) {
+  return process.exit(code);
+}
+var DEFAULT_DEPENDENCIES2 = {
+  normalizeEnvironment,
+  environmentValue: readStdioEnvironment,
+  resolveCredential: resolveMcpCredential,
+  readConfig,
+  profileForEnvironment,
+  resolveAgentName,
+  resolveServiceUrls,
+  createTopolo,
+  buildServer,
+  createTransport: createStdioTransport,
+  advertisedToolNames,
+  writeStderr: writeStdioError,
+  exit: exitStdioProcess
+};
+async function runStdioMcp(dependencies = DEFAULT_DEPENDENCIES2) {
+  const environment = dependencies.normalizeEnvironment(dependencies.environmentValue());
+  const resolvedCredential = await dependencies.resolveCredential(environment);
   const credential = resolvedCredential.credential;
   if (!credential) {
-    process.stderr.write(
-      "TopoloMCP: no Topolo credential. Run `topolo auth login`, or set TOPOLO_API_KEY / TOPOLO_ACCESS_TOKEN.\n"
+    throw new TopoloMcpPublicError(
+      "no Topolo credential. Run `topolo auth login`, or set TOPOLO_API_KEY / TOPOLO_ACCESS_TOKEN."
     );
-    process.exit(1);
   }
-  const config = await readConfig();
-  const profile = profileForEnvironment(config, environment);
-  const agentName = resolveAgentName(profile.agentName);
-  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
-  const topolo = createTopolo({
+  const config = await dependencies.readConfig();
+  const profile = dependencies.profileForEnvironment(config, environment);
+  const agentName = dependencies.resolveAgentName(profile.agentName);
+  const serviceUrls = dependencies.resolveServiceUrls(profile.serviceUrls, environment);
+  const topolo = dependencies.createTopolo({
     credential,
     agent: {
       clientName: "topolo-mcp",
@@ -4670,11 +4715,11 @@ async function main() {
     ...resolvedCredential.refreshCredential ? { refreshCredential: resolvedCredential.refreshCredential } : {}
   });
   const scopes = await loadScopes(topolo);
-  const server = buildServer(topolo, scopes);
-  const transport = new StdioServerTransport();
+  const server = dependencies.buildServer(topolo, scopes);
+  const transport = dependencies.createTransport();
   await server.connect(transport);
-  const toolNames = await advertisedToolNames(topolo, scopes);
-  process.stderr.write(
+  const toolNames = await dependencies.advertisedToolNames(topolo, scopes);
+  dependencies.writeStderr(
     `TopoloMCP v${MCP_VERSION} connected (${environment}${resolvedCredential.contextKey ? `, ${resolvedCredential.contextKey}` : ""}). Tools available: ${toolNames.join(", ") || "(none)"}
 `
   );
@@ -4690,15 +4735,31 @@ async function loadScopes(topolo) {
     };
   } catch (err) {
     if (err instanceof TopoloAuthError) {
-      process.stderr.write(`TopoloMCP: credential rejected \u2014 ${err.message}
-`);
-      process.exit(1);
+      throw new TopoloMcpPublicError("credential rejected.");
     }
     throw err;
   }
 }
-main().catch((err) => {
-  process.stderr.write(`TopoloMCP fatal: ${err instanceof Error ? err.message : String(err)}
+function terminateStdioMcp(error, dependencies = DEFAULT_DEPENDENCIES2) {
+  const isPublic = error instanceof TopoloMcpPublicError;
+  const message = publicMcpErrorMessage(error, "Unexpected startup failure.");
+  dependencies.writeStderr(`TopoloMCP${isPublic ? "" : " fatal"}: ${message}
 `);
-  process.exit(1);
-});
+  return dependencies.exit(1);
+}
+function isDirectExecution(moduleUrl, argvEntry) {
+  return Boolean(argvEntry && fileURLToPath2(moduleUrl) === resolve(argvEntry));
+}
+if (isDirectExecution(import.meta.url, process.argv[1])) {
+  void runStdioMcp().catch((error) => terminateStdioMcp(error));
+}
+export {
+  createStdioTransport,
+  exitStdioProcess,
+  isDirectExecution,
+  loadScopes,
+  readStdioEnvironment,
+  runStdioMcp,
+  terminateStdioMcp,
+  writeStdioError
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/mcp",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "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": {
@@ -36,7 +36,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "peerDependencies": {
-    "@topolo/sdk": "^0.9.5"
+    "@topolo/sdk": "^0.9.6"
   },
   "devDependencies": {
     "@topolo/sdk": "file:../topolo-sdk",