@topolo/mcp 0.10.2 → 0.10.3

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// ../topolo-sdk/dist/index.js
+// ../../../development-workflow-acceleration/node_modules/.pnpm/@topolo+sdk@0.10.4/node_modules/@topolo/sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -30,6 +30,90 @@ var TopoloSdkError = class extends Error {
     this.code = code;
   }
 };
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "action_app_identity_unavailable",
+  "action_authentication_required",
+  "action_catalog_summary_unavailable",
+  "action_catalog_unavailable",
+  "action_contract_mismatch",
+  "action_permission_required",
+  "action_runtime_authorization_required",
+  "action_service_not_allowed",
+  "auth_error",
+  "authentication_required",
+  "authorization_pending",
+  "bad_sig",
+  "confirmation_required",
+  "dependency_unavailable",
+  "environment_mismatch",
+  "environment_service_url_required",
+  "expired_token",
+  "forbidden",
+  "http_error",
+  "immutable_drift",
+  "integration_dependency_unavailable",
+  "integration_misconfigured",
+  "invalid_action",
+  "invalid_action_input",
+  "invalid_grant",
+  "invalid_input",
+  "invalid_token",
+  "mcp_error",
+  "membership_required",
+  "network_error",
+  "organization_context_required",
+  "organization_enrollment_required",
+  "permission_denied",
+  "rate_limited",
+  "request_failed",
+  "service_catalog_unavailable",
+  "service_path_origin_mismatch",
+  "service_required",
+  "slow_down",
+  "state_conflict",
+  "unauthorized",
+  "unknown_action",
+  "unknown_service"
+]);
+var ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var TOPOLO_REQUEST_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var CLOUDFLARE_RAY_ID_PATTERN = /^[0-9a-f]{16}-[A-Z]{3}$/;
+var PERMISSION_PATTERN = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
+var RETRY_AFTER_DATE_PATTERN = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+var PUBLIC_DETAIL_SOURCES = /* @__PURE__ */ new Set([
+  "api_key_introspection",
+  "api_key_validation",
+  "auth_context",
+  "auth_validate",
+  "catalog",
+  "credential",
+  "runtime",
+  "service_token_provider",
+  "service_verify_key",
+  "token_validation",
+  "upstream"
+]);
+function canonicalTopoloErrorCode(value) {
+  if (typeof value !== "string") return null;
+  const candidate = value.trim().toLowerCase();
+  if (!ERROR_CODE_PATTERN.test(candidate) || !PUBLIC_ERROR_CODES.has(candidate)) return null;
+  return candidate;
+}
+function canonicalTopoloRequestId(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  return TOPOLO_REQUEST_ID_PATTERN.test(candidate) || CLOUDFLARE_RAY_ID_PATTERN.test(candidate) ? candidate : void 0;
+}
+function canonicalTopoloRetryAfter(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  if (/^\d{1,10}$/.test(candidate) || RETRY_AFTER_DATE_PATTERN.test(candidate)) return candidate;
+  return void 0;
+}
+function canonicalTopoloRequired(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item) => typeof item === "string" && PERMISSION_PATTERN.test(item)))].slice(0, 32);
+}
 var TopoloAuthError = class extends TopoloSdkError {
   status;
   body;
@@ -37,15 +121,19 @@ var TopoloAuthError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(message, code = "auth_error", options = {}) {
-    super(code, message);
+    super(canonicalTopoloErrorCode(code) ?? "auth_error", 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;
+    this.requestId = canonicalTopoloRequestId(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails(
+      options.details === void 0 ? options.body : { details: options.details }
+    );
   }
 };
 var TopoloPermissionError = class extends TopoloSdkError {
@@ -56,28 +144,140 @@ var TopoloPermissionError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(message, required, options = {}) {
-    super("permission_denied", message);
+    super(
+      canonicalTopoloErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
+      message
+    );
     this.name = "TopoloPermissionError";
-    this.required = required;
+    this.required = canonicalTopoloRequired(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;
+    this.requestId = canonicalTopoloRequestId(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails(
+      options.details === void 0 ? options.body : { details: options.details }
+    );
   }
 };
-function extractHttpErrorCode(body) {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return "http_error";
+function extractTopoloServiceErrorCode(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record = body;
-  if (typeof record.code === "string" && record.code.trim()) return record.code.trim();
+  const topLevel = canonicalTopoloErrorCode(record.code);
+  if (topLevel) return topLevel;
   const nested = record.error;
+  const nestedString = canonicalTopoloErrorCode(nested);
+  if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    if (typeof code === "string" && code.trim()) return code.trim();
+    const nestedCode = canonicalTopoloErrorCode(code);
+    if (nestedCode) return nestedCode;
   }
-  return "http_error";
+  return null;
+}
+function serviceErrorCode(body, fallback) {
+  return extractTopoloServiceErrorCode(body) ?? fallback;
+}
+function extractTopoloServiceErrorDetails(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record = body;
+  let candidate = record.details;
+  const nested = record.error;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const nestedRecord = nested;
+    if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
+  }
+  if (candidate === void 0) candidate = record;
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return void 0;
+  const source = candidate;
+  const safe = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (/present$/i.test(key) && typeof value === "boolean") {
+      safe[key] = value;
+      continue;
+    }
+    if (key === "retryable" && typeof value === "boolean") {
+      safe.retryable = value;
+      continue;
+    }
+    if (key === "code") {
+      const sanitized = canonicalTopoloErrorCode(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "source") {
+      const sanitized = typeof value === "string" ? value.trim().toLowerCase() : "";
+      if (PUBLIC_DETAIL_SOURCES.has(sanitized)) safe.source = sanitized;
+      continue;
+    }
+    if (key === "dependency" || key === "platform") {
+      safe[`${key}Present`] = value !== null && value !== void 0;
+      continue;
+    }
+    if (key === "error" && !safe.code) {
+      const sanitized = canonicalTopoloErrorCode(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "required" && Array.isArray(value)) {
+      const required = canonicalTopoloRequired(value);
+      if (required.length) safe.required = required;
+      continue;
+    }
+    if (["missingFields", "fields", "paths"].includes(key) && Array.isArray(value)) {
+      const paths = value.filter((item) => typeof item === "string" && /^[$.a-z0-9_[\]-]{1,160}$/i.test(item));
+      if (paths.length) safe[key] = paths;
+    }
+  }
+  return Object.keys(safe).length ? safe : void 0;
+}
+function publicTopoloErrorMessage(error) {
+  const code = canonicalTopoloErrorCode(
+    typeof error === "string" ? error : error.code ?? extractTopoloServiceErrorCode(error.body)
+  ) ?? "request_failed";
+  if (/(?:organization|org).*(?:enroll|membership|member|admission)/.test(code)) {
+    return "Organization or application enrollment is required.";
+  }
+  if (/(?:organization|org).*(?:context|required|missing|invalid|unknown|not_found)/.test(code)) {
+    return "Organization context is unavailable.";
+  }
+  if (["auth_error", "authentication_required", "unauthorized", "invalid_token", "expired_token"].includes(code)) {
+    return "Authentication failed.";
+  }
+  if (code === "permission_denied" || code === "forbidden") return "Permission denied.";
+  if (code === "confirmation_required") return "Confirmation is required.";
+  return `Topolo request failed (${code}).`;
+}
+function topoloErrorHint(error) {
+  const code = canonicalTopoloErrorCode(
+    typeof error === "string" ? error : error.code ?? extractTopoloServiceErrorCode(error.body)
+  );
+  if (!code) return void 0;
+  if (code === "auth_error" || code === "authentication_required" || code === "unauthorized" || code === "invalid_token" || code === "expired_token") {
+    return "Run `topolo auth login`, then verify the effective Topolo identity and organization.";
+  }
+  if (code === "confirmation_required") {
+    return "Review the unchanged action plan, obtain approval, and retry once with --confirm or confirm:true.";
+  }
+  if (code === "enrollment_required" || code === "membership_required" || /(?:organization|org).*(?:enroll|membership|member|admission)|(?:enroll|membership).*(?:organization|org)/.test(code)) {
+    return "The current identity is not enrolled for this organization or application. Use an enrolled identity or ask an organization administrator to complete enrollment.";
+  }
+  if (/(?:organization|org).*(?:context|required|missing|invalid|unknown|not_found)/.test(code)) {
+    return "Select a signed-in organization context, then verify the effective identity and organization before retrying.";
+  }
+  if (code === "permission_denied" || code === "forbidden") {
+    return "The current identity or resource context is not authorized. Review the structured details and published authorization contract.";
+  }
+  if (code === "environment_mismatch") {
+    return "Use service origins and credentials from one explicit Topolo environment only.";
+  }
+  if (code === "invalid_action_input" || code === "invalid_input") {
+    return "Correct only the reported schema paths, then prepare the action again.";
+  }
+  return void 0;
 }
 var TopoloConfirmationRequiredError = class extends TopoloSdkError {
   constructor(message) {
@@ -92,17 +292,66 @@ var TopoloHttpError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(service, path, status, body, message, options = {}) {
-    super(extractHttpErrorCode(body), message ?? `HTTP ${status} from ${service}${path}`);
+    super(serviceErrorCode(body, "http_error"), 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;
+    this.requestId = canonicalTopoloRequestId(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails(
+      options.details === void 0 ? body : { details: options.details }
+    );
   }
 };
+function hostnameHasSuffix(hostname, suffix) {
+  return hostname === suffix || hostname.endsWith(`.${suffix}`);
+}
+function workersDevAccountMatches(hostname, account) {
+  if (!hostname.endsWith(".workers.dev")) return false;
+  const labels = hostname.slice(0, -".workers.dev".length).split(".");
+  return labels.length >= 2 && labels.at(-1) === account;
+}
+function originMatchesEnvironment(url, environment) {
+  const hostname = url.hostname.toLowerCase();
+  if (environment === "local") {
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+  }
+  if (url.protocol !== "https:") return false;
+  if (environment === "production") {
+    return hostnameHasSuffix(hostname, "topolo.app") || hostnameHasSuffix(hostname, "topolo.io") || workersDevAccountMatches(hostname, "topolo");
+  }
+  if (environment === "staging") {
+    return hostnameHasSuffix(hostname, "stg.topolo.us") || workersDevAccountMatches(hostname, "topolo-staging");
+  }
+  return hostnameHasSuffix(hostname, "topolo.dev") || workersDevAccountMatches(hostname, "topolo-development");
+}
+function assertTopoloServiceUrlEnvironment(service, value, environment) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originMatchesEnvironment(url, environment)) {
+    throw new TopoloSdkError(
+      "environment_mismatch",
+      `Refusing Topolo service "${service}": ${url.origin} does not belong to ${environment}.`
+    );
+  }
+  return url.origin;
+}
+function topoloServiceOrigins(serviceUrls, environment) {
+  return Object.fromEntries(
+    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
+      service,
+      assertTopoloServiceUrlEnvironment(service, value, environment)
+    ])
+  );
+}
 var APP_API_URLS = {
   auth: "https://auth.topolo.app",
   developers: "https://developers.topolo.app"
@@ -2851,6 +3100,7 @@ var TopoloClient = class _TopoloClient {
   credential;
   agent;
   serviceUrls;
+  environment;
   appIds;
   requireConfirmForWrites;
   timeoutMs;
@@ -2879,7 +3129,8 @@ var TopoloClient = class _TopoloClient {
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
     this.credential = options.credential;
     this.agent = options.agent;
-    this.serviceUrls = options.serviceUrls;
+    this.environment = options.environment;
+    this.serviceUrls = options.environment ? topoloServiceOrigins(options.serviceUrls, options.environment) : options.serviceUrls;
     this.appIds = options.appIds;
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
@@ -2908,9 +3159,15 @@ var TopoloClient = class _TopoloClient {
       );
     }
     await this.loadCurrentCredential();
-    const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: requireHttpOrigin(opts.baseUrl) } : await this.resolveRequestService(opts.service);
+    const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: this.validatedServiceOrigin(opts.service, opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    if (url.origin !== new URL(baseUrl).origin) {
+      throw new TopoloSdkError(
+        "service_path_origin_mismatch",
+        `Refusing Topolo request path because it changes the resolved ${resolvedService.serviceKey || opts.service} service origin.`
+      );
+    }
     if (opts.query) {
       for (const [k, v] of Object.entries(opts.query)) {
         if (v !== void 0) url.searchParams.set(k, String(v));
@@ -2981,7 +3238,7 @@ var TopoloClient = class _TopoloClient {
         url: urlStr,
         requestId,
         durationMs: Date.now() - startedAt,
-        error: err instanceof Error ? err.message : String(err)
+        error: "network_error"
       });
       throw err;
     }
@@ -2990,6 +3247,7 @@ var TopoloClient = class _TopoloClient {
     if (!res.ok) {
       const durationMs = Date.now() - startedAt;
       const message = describeError(parsed, `HTTP ${res.status}`);
+      const publicCode = extractTopoloServiceErrorCode(parsed) ?? "http_error";
       this.emit({
         phase: "error",
         method,
@@ -2998,7 +3256,7 @@ var TopoloClient = class _TopoloClient {
         url: urlStr,
         requestId,
         durationMs,
-        error: message,
+        error: publicCode,
         status: res.status
       });
       const errorContext = {
@@ -3006,17 +3264,21 @@ var TopoloClient = class _TopoloClient {
         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
+        requestId: canonicalTopoloRequestId(res.headers.get("X-Topolo-Request-Id")) ?? requestId,
+        retryAfter: canonicalTopoloRetryAfter(res.headers.get("Retry-After"))
       };
       if (res.status === 401) {
-        throw new TopoloAuthError(describeError(parsed, "Unauthorized"), "auth_error", errorContext);
+        throw new TopoloAuthError(
+          describeError(parsed, "Unauthorized"),
+          extractTopoloServiceErrorCode(parsed) ?? "auth_error",
+          errorContext
+        );
       }
       if (res.status === 403) {
         throw new TopoloPermissionError(
           describeError(parsed, "Permission denied"),
           extractRequired(parsed),
-          errorContext
+          { ...errorContext, code: extractTopoloServiceErrorCode(parsed) ?? "permission_denied" }
         );
       }
       throw new TopoloHttpError(
@@ -3066,6 +3328,17 @@ var TopoloClient = class _TopoloClient {
     });
     return this.refreshInFlight;
   }
+  validatedServiceOrigin(service, value) {
+    const origin = requireHttpOrigin(value);
+    return this.environment ? assertTopoloServiceUrlEnvironment(service, origin, this.environment) : origin;
+  }
+  validatedActionEntry(entry) {
+    if (!entry.apiBaseUrl) return entry;
+    return {
+      ...entry,
+      apiBaseUrl: this.validatedServiceOrigin(entry.appSlug || entry.appId, entry.apiBaseUrl)
+    };
+  }
   async resolveRequestService(service) {
     const serviceKey = normalizeLookupKey(service);
     if (!serviceKey) {
@@ -3073,17 +3346,20 @@ var TopoloClient = class _TopoloClient {
     }
     if (serviceKey === "auth" || serviceKey === "developers") {
       const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-      if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
+      if (overrideUrl) return { serviceKey, baseUrl: this.validatedServiceOrigin(serviceKey, overrideUrl) };
       if (serviceKey === "developers") {
         const derived = deriveDevelopersFromAuth(resolveConfiguredServiceUrl("auth", this.serviceUrls));
-        if (derived) return { serviceKey, baseUrl: derived };
+        if (derived) return { serviceKey, baseUrl: this.validatedServiceOrigin(serviceKey, derived) };
       }
-      return { serviceKey, baseUrl: DEFAULT_APP_URLS[serviceKey] };
+      return {
+        serviceKey,
+        baseUrl: this.validatedServiceOrigin(serviceKey, DEFAULT_APP_URLS[serviceKey])
+      };
     }
     const live = await this.resolveLiveCallableService(serviceKey);
     if (live) {
       const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-      return overrideUrl ? { ...live, baseUrl: overrideUrl } : live;
+      return overrideUrl ? { ...live, baseUrl: this.validatedServiceOrigin(serviceKey, overrideUrl) } : { ...live, baseUrl: this.validatedServiceOrigin(serviceKey, live.baseUrl) };
     }
     throw new TopoloSdkError(
       "unknown_service",
@@ -3097,10 +3373,10 @@ var TopoloClient = class _TopoloClient {
       serviceKey,
       overrides: this.serviceUrls
     });
-    if (baseUrl) return { serviceKey, baseUrl };
+    if (baseUrl) return { serviceKey, baseUrl: this.validatedServiceOrigin(serviceKey, baseUrl) };
     const actionPage = await this.searchActions({ service: match.appId, limit: 1 }).catch(() => null);
     const actionBaseUrl = actionPage?.actions.find((action) => action.apiBaseUrl)?.apiBaseUrl ?? null;
-    return actionBaseUrl ? { serviceKey, baseUrl: requireHttpOrigin(actionBaseUrl) } : null;
+    return actionBaseUrl ? { serviceKey, baseUrl: this.validatedServiceOrigin(serviceKey, actionBaseUrl) } : null;
   }
   /**
    * Resolve a service-slug → opaque app-id via caller config or TopoloAuth.
@@ -3120,7 +3396,7 @@ var TopoloClient = class _TopoloClient {
     if (!normalized) return null;
     const configuredAppId = resolveConfiguredAppId(normalized, this.appIds);
     if (configuredAppId) return configuredAppId;
-    const authBase = resolveServiceUrl("developers", this.serviceUrls);
+    const authBase = this.validatedServiceOrigin("developers", resolveServiceUrl("developers", this.serviceUrls));
     const cacheKey = `${authBase}|${normalized}`;
     const now = Date.now();
     const cached = _TopoloClient.appIdCache.get(cacheKey);
@@ -3296,7 +3572,7 @@ var TopoloClient = class _TopoloClient {
         "TopoloAuth did not return an action catalog for the current credential."
       );
     }
-    const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry));
+    const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry)).map((entry) => this.validatedActionEntry(entry));
     return {
       actions: entries,
       page: normalizeCatalogPage(
@@ -3361,7 +3637,7 @@ var TopoloClient = class _TopoloClient {
     const raw = res.data?.action ?? res.action;
     const match = normalizeActionCatalogEntry(raw);
     if (!match) throw new TopoloSdkError("unknown_action", `Unknown or unavailable Topolo action "${action}".`);
-    return match;
+    return this.validatedActionEntry(match);
   }
   async callAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
@@ -3438,6 +3714,25 @@ var TopoloClient = class _TopoloClient {
   }
   async planAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
+    return this.planResolvedAction(entry, input, options);
+  }
+  async prepareAction(action, input, options = {}) {
+    const entry = await this.getAction(action);
+    const example = (entry.agentContract?.examples ?? []).find((candidate) => Boolean(candidate?.input) && typeof candidate.input === "object" && !Array.isArray(candidate.input) && validateTopoloActionInput(entry.inputSchema, candidate.input).valid) ?? null;
+    const selectedInput = input ?? example?.input ?? {};
+    const plan = this.planResolvedAction(entry, selectedInput, options);
+    return {
+      action: entry,
+      example,
+      input: selectedInput,
+      inputSource: input ? "provided" : example ? "example" : "empty",
+      missingFields: [...new Set(
+        plan.validation.errors.filter((issue) => issue.code === "required").map((issue) => issue.path)
+      )],
+      plan
+    };
+  }
+  planResolvedAction(entry, input, options) {
     const validation = validateTopoloActionInput(entry.inputSchema, input);
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     const confirmationRequired = agentAccess === "confirm" || entry.requiresConfirmation || entry.destructive;
@@ -3895,7 +4190,16 @@ function pickString(value) {
 function extractRequired(body) {
   if (body && typeof body === "object") {
     const maybe = body;
-    if (Array.isArray(maybe.required)) return maybe.required.map(String);
+    if (Array.isArray(maybe.required)) return canonicalTopoloRequired(maybe.required);
+    for (const nested of [maybe.details, maybe.error]) {
+      if (!nested || typeof nested !== "object" || Array.isArray(nested)) continue;
+      const record = nested;
+      if (Array.isArray(record.required)) return canonicalTopoloRequired(record.required);
+      if (record.details && typeof record.details === "object" && !Array.isArray(record.details)) {
+        const required = record.details.required;
+        if (Array.isArray(required)) return canonicalTopoloRequired(required);
+      }
+    }
   }
   return [];
 }
@@ -3943,6 +4247,72 @@ function compactActionPlan(plan) {
     nextActionIds: plan.nextActionIds
   };
 }
+function requiredContextText(value, field) {
+  if (typeof value !== "string" || !value.trim() || value.trim().toLowerCase() === "unknown") {
+    throw new TopoloSdkError("invalid_identity_context", `Effective Topolo ${field} is incomplete.`);
+  }
+  return value.trim();
+}
+function createTopoloAgentExecutionContext(input) {
+  if (input.contextKey !== null && input.contextKey !== "personal" && !/^org:[^:]+$/.test(input.contextKey)) {
+    throw new TopoloSdkError("invalid_identity_context", "Effective Topolo context key is invalid.");
+  }
+  const user = Object.freeze({
+    id: requiredContextText(input.identity.user.id, "user id"),
+    email: requiredContextText(input.identity.user.email, "user email"),
+    name: input.identity.user.name?.trim() || null,
+    role: requiredContextText(input.identity.user.role, "user role")
+  });
+  const organization = input.identity.organization ? Object.freeze({
+    id: requiredContextText(input.identity.organization.id, "organization id"),
+    slug: requiredContextText(input.identity.organization.slug, "organization slug"),
+    name: requiredContextText(input.identity.organization.name, "organization name")
+  }) : null;
+  if (input.contextKey === "personal" && organization) {
+    throw new TopoloSdkError("identity_context_mismatch", "Personal Topolo context resolved an organization.");
+  }
+  if (input.contextKey?.startsWith("org:")) {
+    const expectedOrganizationId = input.contextKey.slice("org:".length);
+    if (!organization || organization.id !== expectedOrganizationId) {
+      throw new TopoloSdkError("identity_context_mismatch", "Pinned Topolo organization does not match the effective identity.");
+    }
+  }
+  return Object.freeze({
+    environment: input.environment,
+    contextKey: input.contextKey,
+    user,
+    organization,
+    serviceOrigins: Object.freeze(topoloServiceOrigins(input.serviceUrls, input.environment))
+  });
+}
+function compactActionPreparationCore(preparation) {
+  const example = preparation.example ? { title: preparation.example.title ?? null, input: preparation.example.input } : null;
+  const effectiveInput = preparation.inputSource === "example" ? { source: "example" } : { source: preparation.inputSource, value: preparation.input };
+  return {
+    action: {
+      id: preparation.action.actionId,
+      title: preparation.action.title,
+      docsUrl: preparation.action.agentContract?.docsUrl ?? null
+    },
+    example,
+    input: effectiveInput,
+    missingFields: preparation.missingFields,
+    valid: preparation.plan.validation.valid,
+    errors: preparation.plan.validation.errors,
+    request: preparation.plan.request,
+    confirmation: {
+      required: preparation.plan.confirmationRequired,
+      provided: preparation.plan.confirmationProvided
+    },
+    executable: preparation.plan.executable,
+    verification: preparation.plan.verification,
+    rollbackActionId: preparation.plan.rollbackActionId
+  };
+}
+function compactActionPreparation(preparation, context) {
+  const compact = compactActionPreparationCore(preparation);
+  return context ? { context, ...compact } : compact;
+}
 function compactApplicationAudit(report) {
   return {
     version: report.version,
@@ -4081,7 +4451,7 @@ function createTopolo(options) {
   };
 }
 
-// ../topolo-sdk/dist/node/credential-store.js
+// ../../../development-workflow-acceleration/node_modules/.pnpm/@topolo+sdk@0.10.4/node_modules/@topolo/sdk/dist/node/credential-store.js
 import { mkdir, readFile, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir, platform } from "os";
@@ -4094,6 +4464,90 @@ var TopoloSdkError2 = class extends Error {
     this.code = code;
   }
 };
+var PUBLIC_ERROR_CODES2 = /* @__PURE__ */ new Set([
+  "action_app_identity_unavailable",
+  "action_authentication_required",
+  "action_catalog_summary_unavailable",
+  "action_catalog_unavailable",
+  "action_contract_mismatch",
+  "action_permission_required",
+  "action_runtime_authorization_required",
+  "action_service_not_allowed",
+  "auth_error",
+  "authentication_required",
+  "authorization_pending",
+  "bad_sig",
+  "confirmation_required",
+  "dependency_unavailable",
+  "environment_mismatch",
+  "environment_service_url_required",
+  "expired_token",
+  "forbidden",
+  "http_error",
+  "immutable_drift",
+  "integration_dependency_unavailable",
+  "integration_misconfigured",
+  "invalid_action",
+  "invalid_action_input",
+  "invalid_grant",
+  "invalid_input",
+  "invalid_token",
+  "mcp_error",
+  "membership_required",
+  "network_error",
+  "organization_context_required",
+  "organization_enrollment_required",
+  "permission_denied",
+  "rate_limited",
+  "request_failed",
+  "service_catalog_unavailable",
+  "service_path_origin_mismatch",
+  "service_required",
+  "slow_down",
+  "state_conflict",
+  "unauthorized",
+  "unknown_action",
+  "unknown_service"
+]);
+var ERROR_CODE_PATTERN2 = /^[a-z][a-z0-9_]{0,63}$/;
+var TOPOLO_REQUEST_ID_PATTERN2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var CLOUDFLARE_RAY_ID_PATTERN2 = /^[0-9a-f]{16}-[A-Z]{3}$/;
+var PERMISSION_PATTERN2 = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
+var RETRY_AFTER_DATE_PATTERN2 = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+var PUBLIC_DETAIL_SOURCES2 = /* @__PURE__ */ new Set([
+  "api_key_introspection",
+  "api_key_validation",
+  "auth_context",
+  "auth_validate",
+  "catalog",
+  "credential",
+  "runtime",
+  "service_token_provider",
+  "service_verify_key",
+  "token_validation",
+  "upstream"
+]);
+function canonicalTopoloErrorCode2(value) {
+  if (typeof value !== "string") return null;
+  const candidate = value.trim().toLowerCase();
+  if (!ERROR_CODE_PATTERN2.test(candidate) || !PUBLIC_ERROR_CODES2.has(candidate)) return null;
+  return candidate;
+}
+function canonicalTopoloRequestId2(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  return TOPOLO_REQUEST_ID_PATTERN2.test(candidate) || CLOUDFLARE_RAY_ID_PATTERN2.test(candidate) ? candidate : void 0;
+}
+function canonicalTopoloRetryAfter2(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  if (/^\d{1,10}$/.test(candidate) || RETRY_AFTER_DATE_PATTERN2.test(candidate)) return candidate;
+  return void 0;
+}
+function canonicalTopoloRequired2(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item) => typeof item === "string" && PERMISSION_PATTERN2.test(item)))].slice(0, 32);
+}
 var TopoloAuthError2 = class extends TopoloSdkError2 {
   status;
   body;
@@ -4101,27 +4555,91 @@ var TopoloAuthError2 = class extends TopoloSdkError2 {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(message, code = "auth_error", options = {}) {
-    super(code, message);
+    super(canonicalTopoloErrorCode2(code) ?? "auth_error", 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;
+    this.requestId = canonicalTopoloRequestId2(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter2(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails2(
+      options.details === void 0 ? options.body : { details: options.details }
+    );
   }
 };
-function extractHttpErrorCode2(body) {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return "http_error";
+function extractTopoloServiceErrorCode2(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record = body;
-  if (typeof record.code === "string" && record.code.trim()) return record.code.trim();
+  const topLevel = canonicalTopoloErrorCode2(record.code);
+  if (topLevel) return topLevel;
   const nested = record.error;
+  const nestedString = canonicalTopoloErrorCode2(nested);
+  if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    if (typeof code === "string" && code.trim()) return code.trim();
+    const nestedCode = canonicalTopoloErrorCode2(code);
+    if (nestedCode) return nestedCode;
   }
-  return "http_error";
+  return null;
+}
+function serviceErrorCode2(body, fallback) {
+  return extractTopoloServiceErrorCode2(body) ?? fallback;
+}
+function extractTopoloServiceErrorDetails2(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record = body;
+  let candidate = record.details;
+  const nested = record.error;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const nestedRecord = nested;
+    if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
+  }
+  if (candidate === void 0) candidate = record;
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return void 0;
+  const source = candidate;
+  const safe = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (/present$/i.test(key) && typeof value === "boolean") {
+      safe[key] = value;
+      continue;
+    }
+    if (key === "retryable" && typeof value === "boolean") {
+      safe.retryable = value;
+      continue;
+    }
+    if (key === "code") {
+      const sanitized = canonicalTopoloErrorCode2(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "source") {
+      const sanitized = typeof value === "string" ? value.trim().toLowerCase() : "";
+      if (PUBLIC_DETAIL_SOURCES2.has(sanitized)) safe.source = sanitized;
+      continue;
+    }
+    if (key === "dependency" || key === "platform") {
+      safe[`${key}Present`] = value !== null && value !== void 0;
+      continue;
+    }
+    if (key === "error" && !safe.code) {
+      const sanitized = canonicalTopoloErrorCode2(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "required" && Array.isArray(value)) {
+      const required = canonicalTopoloRequired2(value);
+      if (required.length) safe.required = required;
+      continue;
+    }
+    if (["missingFields", "fields", "paths"].includes(key) && Array.isArray(value)) {
+      const paths = value.filter((item) => typeof item === "string" && /^[$.a-z0-9_[\]-]{1,160}$/i.test(item));
+      if (paths.length) safe[key] = paths;
+    }
+  }
+  return Object.keys(safe).length ? safe : void 0;
 }
 var TopoloHttpError2 = class extends TopoloSdkError2 {
   status;
@@ -4130,15 +4648,19 @@ var TopoloHttpError2 = class extends TopoloSdkError2 {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(service, path, status, body, message, options = {}) {
-    super(extractHttpErrorCode2(body), message ?? `HTTP ${status} from ${service}${path}`);
+    super(serviceErrorCode2(body, "http_error"), 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;
+    this.requestId = canonicalTopoloRequestId2(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter2(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails2(
+      options.details === void 0 ? body : { details: options.details }
+    );
   }
 };
 var APP_API_URLS2 = {
@@ -4244,8 +4766,9 @@ var TopoloOAuth = class {
     return parsed;
   }
 };
-var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
+var TOPOLO_ENVIRONMENT_SERVICE_URLS = {
   production: {
+    auth: "https://auth.topolo.app",
     developers: "https://developers.topolo.app"
   },
   staging: {
@@ -4259,6 +4782,52 @@ var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
   },
   local: {}
 };
+function hostnameHasSuffix2(hostname, suffix) {
+  return hostname === suffix || hostname.endsWith(`.${suffix}`);
+}
+function workersDevAccountMatches2(hostname, account) {
+  if (!hostname.endsWith(".workers.dev")) return false;
+  const labels = hostname.slice(0, -".workers.dev".length).split(".");
+  return labels.length >= 2 && labels.at(-1) === account;
+}
+function originMatchesEnvironment2(url, environment) {
+  const hostname = url.hostname.toLowerCase();
+  if (environment === "local") {
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+  }
+  if (url.protocol !== "https:") return false;
+  if (environment === "production") {
+    return hostnameHasSuffix2(hostname, "topolo.app") || hostnameHasSuffix2(hostname, "topolo.io") || workersDevAccountMatches2(hostname, "topolo");
+  }
+  if (environment === "staging") {
+    return hostnameHasSuffix2(hostname, "stg.topolo.us") || workersDevAccountMatches2(hostname, "topolo-staging");
+  }
+  return hostnameHasSuffix2(hostname, "topolo.dev") || workersDevAccountMatches2(hostname, "topolo-development");
+}
+function assertTopoloServiceUrlEnvironment2(service, value, environment) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError2("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originMatchesEnvironment2(url, environment)) {
+    throw new TopoloSdkError2(
+      "environment_mismatch",
+      `Refusing Topolo service "${service}": ${url.origin} does not belong to ${environment}.`
+    );
+  }
+  return url.origin;
+}
+function topoloServiceOrigins2(serviceUrls, environment) {
+  return Object.fromEntries(
+    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
+      service,
+      assertTopoloServiceUrlEnvironment2(service, value, environment)
+    ])
+  );
+}
+var ENVIRONMENT_DEFAULT_SERVICE_URLS = TOPOLO_ENVIRONMENT_SERVICE_URLS;
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
@@ -4339,9 +4908,9 @@ function writeProfileConfig(config, environment, profile) {
 }
 async function resolveCredential(environment = selectedEnvironment()) {
   const prefix = envVarPrefix(environment);
-  const apiKey = process.env[`${prefix}_API_KEY`] ?? process.env.TOPOLO_API_KEY;
+  const apiKey = process.env[`${prefix}_API_KEY`] ?? (environment === "production" ? process.env.TOPOLO_API_KEY : void 0);
   if (apiKey) return { kind: "api_key", apiKey };
-  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? process.env.TOPOLO_ACCESS_TOKEN;
+  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? (environment === "production" ? process.env.TOPOLO_ACCESS_TOKEN : void 0);
   if (accessToken) return { kind: "access_token", accessToken };
   const config = await readConfig();
   return profileForEnvironment(config, environment).credential ?? null;
@@ -4349,7 +4918,7 @@ async function resolveCredential(environment = selectedEnvironment()) {
 var REFRESH_SKEW_SECONDS = 60;
 async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
   const prefix = envVarPrefix(environment);
-  if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
+  if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || environment === "production" && process.env.TOPOLO_API_KEY || environment === "production" && process.env.TOPOLO_ACCESS_TOKEN) {
     return resolveCredential(environment);
   }
   const config = await readConfig();
@@ -4359,9 +4928,16 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
   if (!cred.refreshToken || !profile.oauthClientId) return cred;
   const now = Math.floor(Date.now() / 1e3);
   if (!options.force && cred.expiresAt && cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
+  if (environment === "local" && !serviceUrls?.auth) {
+    throw new TopoloSdkError2(
+      "environment_service_url_required",
+      "Local Topolo credential refresh requires an explicit local Auth service origin."
+    );
+  }
   try {
     const oauth = new TopoloOAuth({
-      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+      serviceUrls
     });
     const tokens = await oauth.refreshToken({
       clientId: profile.oauthClientId,
@@ -4402,9 +4978,16 @@ async function refreshContextCredentialIfNeeded(environment, key, options = {})
   if (!credential.refreshToken || !oauthClientId) return credential;
   const now = Math.floor(Date.now() / 1e3);
   if (!options.force && credential.expiresAt && credential.expiresAt - REFRESH_SKEW_SECONDS > now) return credential;
+  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
+  if (environment === "local" && !serviceUrls?.auth) {
+    throw new TopoloSdkError2(
+      "environment_service_url_required",
+      "Local Topolo context refresh requires an explicit local Auth service origin."
+    );
+  }
   try {
     const oauth = new TopoloOAuth({
-      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+      serviceUrls
     });
     const tokens = await oauth.refreshToken({
       clientId: oauthClientId,
@@ -4451,7 +5034,8 @@ function resolveServiceUrls(configUrls, environment = selectedEnvironment()) {
       merged[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
     }
   }
-  return Object.keys(merged).length > 0 ? merged : void 0;
+  const origins = topoloServiceOrigins2(merged, environment);
+  return Object.keys(origins).length > 0 ? origins : void 0;
 }
 
 // src/server.ts
@@ -4816,6 +5400,38 @@ var TOOLS = [
       return args["detail"] === true ? result : compactActionValidation(result.action.actionId, result.validation);
     }
   },
+  {
+    name: "topolo_prepare_action",
+    title: "Prepare one Topolo action",
+    description: "Fetches one exact live action contract once and returns one valid published example, missing fields, exact request, confirmation state, verification, and rollback without executing it.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        resourceType: { type: "string" },
+        resourceId: { type: "string" },
+        confirm: { type: "boolean", description: "Include confirmation in the plan without executing the action." }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = requiredString(args, "actionId");
+      const resource = optionalResourceContext(args);
+      const preparation = await topolo.client.prepareAction(
+        actionId,
+        args["input"] === void 0 ? void 0 : coerceObjectParam(args["input"], "input"),
+        {
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
+      );
+      return compactActionPreparation(preparation);
+    }
+  },
   {
     name: "topolo_plan_action",
     title: "Plan one Topolo action",
@@ -5283,11 +5899,29 @@ function readMcpVersion() {
 }
 var MCP_VERSION = readMcpVersion();
 
+// src/context.ts
+function createMcpExecutionContext(input) {
+  return createTopoloAgentExecutionContext(input);
+}
+function mcpServerInstructions(context) {
+  return JSON.stringify({
+    effectiveTopoloContext: context,
+    rules: [
+      "Use only this environment, identity, organization, context key, and service origins.",
+      "Prepare mutations before execution and preserve the unchanged request for confirmation.",
+      "Never infer undisclosed actions or switch organization context inside this MCP session."
+    ]
+  });
+}
+function mcpResultEnvelope(context, data) {
+  return { context, data };
+}
+
 // src/server.ts
-function buildServer(topolo, scopes, tools = TOOLS) {
+function buildServer(topolo, scopes, context, tools = TOOLS) {
   const server = new Server(
     { name: "topolo", version: MCP_VERSION },
-    { capabilities: { tools: {} } }
+    { capabilities: { tools: {} }, instructions: mcpServerInstructions(context) }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     const availableTools = await buildTopoloTools(topolo, scopes, tools);
@@ -5310,66 +5944,74 @@ function buildServer(topolo, scopes, tools = TOOLS) {
     const tool = availableTools.find((t) => t.name === params.name);
     if (!tool) {
       return toolError(
+        context,
         `Tool "${params.name}" is not available for this credential. Either the tool does not exist or the current scopes do not permit it.`
       );
     }
     if (!hasAnyScope(scopes, tool.requiredScopes)) {
       return toolError(
+        context,
         `Tool "${tool.name}" requires one of: ${tool.requiredScopes.join(", ")}. Current credential does not grant any of these.`
       );
     }
     try {
       const result = await tool.handler(topolo, params.arguments ?? {});
       return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(mcpResultEnvelope(context, result)) }]
       };
     } catch (err) {
       if (err instanceof TopoloPermissionError) {
-        return toolStructuredError(err, `Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`, {
+        return toolStructuredError(context, err, err.message || "Permission denied.", {
           required: err.required
         });
       }
       if (err instanceof TopoloAuthError) {
-        return toolStructuredError(err, "Authentication failed.");
+        return toolStructuredError(context, err, "Authentication failed.");
       }
       if (err instanceof TopoloHttpError) {
-        return toolStructuredError(err, err.message);
+        return toolStructuredError(context, err, err.message);
       }
-      return toolError(publicMcpErrorMessage(err, "Tool execution failed."));
+      return toolError(context, 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));
+function toolStructuredError(context, error, _message, extra = {}) {
+  return toolError(context, {
+    code: error.code,
+    status: error.status,
+    message: publicTopoloErrorMessage(error),
+    service: error.service,
+    path: error.path,
+    requestId: error.requestId,
+    retryAfter: error.retryAfter,
+    details: error.details,
+    hint: topoloErrorHint(error),
+    ...extra
+  });
 }
 async function advertisedToolNames(topolo, scopes, tools = TOOLS) {
   return (await buildTopoloTools(topolo, scopes, tools)).map((t) => t.name);
 }
-function toolError(message) {
+function toolError(context, error) {
   return {
     isError: true,
-    content: [{ type: "text", text: message }]
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        context,
+        error: typeof error === "string" ? { code: "mcp_error", message: error } : error
+      })
+    }]
   };
 }
 
 // src/auth.ts
-function resolveCredentialFromEnv() {
-  const apiKey = process.env.TOPOLO_API_KEY;
+function resolveCredentialFromEnv(environment = "production") {
+  const prefix = environment === "production" ? "TOPOLO_PRODUCTION" : `TOPOLO_${environment.toUpperCase()}`;
+  const apiKey = process.env[`${prefix}_API_KEY`] ?? (environment === "production" ? process.env.TOPOLO_API_KEY : void 0);
   if (apiKey) return { kind: "api_key", apiKey };
-  const accessToken = process.env.TOPOLO_ACCESS_TOKEN;
+  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? (environment === "production" ? process.env.TOPOLO_ACCESS_TOKEN : void 0);
   if (accessToken) return { kind: "access_token", accessToken };
   return null;
 }
@@ -5401,7 +6043,7 @@ function resolvePinnedContextKey(profile, selector) {
   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 environmentCredential = dependencies.resolveCredentialFromEnv(environment);
   const requestedSelector = selector?.trim();
   if (environmentCredential) {
     if (requestedSelector) {
@@ -5410,15 +6052,16 @@ async function resolveMcpCredential(environment, selector = process.env.TOPOLO_C
     return { credential: environmentCredential, contextKey: null };
   }
   if (requestedSelector) {
-    const config = await dependencies.readConfig();
+    const config2 = await dependencies.readConfig();
     const contextKey = resolvePinnedContextKey(
-      profileForEnvironment(config, environment),
+      profileForEnvironment(config2, environment),
       requestedSelector
     );
     const credential = await dependencies.refreshContextCredentialIfNeeded(environment, contextKey);
     return {
       credential,
       contextKey,
+      storedContext: profileForEnvironment(config2, environment).contexts?.[contextKey],
       credentialProvider: () => dependencies.refreshContextCredentialIfNeeded(
         environment,
         contextKey
@@ -5430,6 +6073,25 @@ async function resolveMcpCredential(environment, selector = process.env.TOPOLO_C
       )
     };
   }
+  const config = await dependencies.readConfig();
+  const profile = profileForEnvironment(config, environment);
+  const activeContext = profile.activeContext;
+  if (activeContext) {
+    const storedContext = profile.contexts?.[activeContext];
+    if (!storedContext) {
+      throw new TopoloMcpPublicError(`Active Topolo context "${activeContext}" is not signed in for this environment`);
+    }
+    return {
+      credential: await dependencies.refreshContextCredentialIfNeeded(environment, activeContext),
+      contextKey: activeContext,
+      storedContext,
+      credentialProvider: () => dependencies.refreshContextCredentialIfNeeded(environment, activeContext),
+      refreshCredential: () => dependencies.refreshContextCredentialIfNeeded(environment, activeContext, { force: true })
+    };
+  }
+  if (Object.keys(profile.contexts ?? {}).length > 0) {
+    throw new TopoloMcpPublicError("No active Topolo context is selected for this environment");
+  }
   return {
     credential: await dependencies.refreshCredentialIfNeeded(environment),
     contextKey: null,
@@ -5484,6 +6146,7 @@ async function runStdioMcp(dependencies = DEFAULT_DEPENDENCIES2) {
   const serviceUrls = dependencies.resolveServiceUrls(profile.serviceUrls, environment);
   const topolo = dependencies.createTopolo({
     credential,
+    environment,
     agent: {
       clientName: "topolo-mcp",
       clientVersion: MCP_VERSION,
@@ -5494,8 +6157,15 @@ async function runStdioMcp(dependencies = DEFAULT_DEPENDENCIES2) {
     ...resolvedCredential.credentialProvider ? { credentialProvider: resolvedCredential.credentialProvider } : {},
     ...resolvedCredential.refreshCredential ? { refreshCredential: resolvedCredential.refreshCredential } : {}
   });
-  const scopes = await loadScopes(topolo);
-  const server = dependencies.buildServer(topolo, scopes);
+  const identity = await loadIdentity(topolo);
+  const scopes = scopesForIdentity(identity);
+  const executionContext = createMcpExecutionContext({
+    environment,
+    contextKey: resolvedCredential.contextKey,
+    identity,
+    serviceUrls
+  });
+  const server = dependencies.buildServer(topolo, scopes, executionContext);
   const transport = dependencies.createTransport();
   await server.connect(transport);
   const toolNames = await dependencies.advertisedToolNames(topolo, scopes);
@@ -5505,14 +6175,19 @@ async function runStdioMcp(dependencies = DEFAULT_DEPENDENCIES2) {
   );
 }
 async function loadScopes(topolo) {
+  return scopesForIdentity(await loadIdentity(topolo));
+}
+function scopesForIdentity(info) {
+  const userWithOrgSlug = info.user;
+  return {
+    permissions: info.user.permissions,
+    role: info.user.role,
+    orgSlug: info.organization?.slug || userWithOrgSlug.orgSlug || void 0
+  };
+}
+async function loadIdentity(topolo) {
   try {
-    const info = await topolo.identity.whoami();
-    const userWithOrgSlug = info.user;
-    return {
-      permissions: info.user.permissions,
-      role: info.user.role,
-      orgSlug: info.organization?.slug || userWithOrgSlug.orgSlug || void 0
-    };
+    return await topolo.identity.whoami();
   } catch (err) {
     if (err instanceof TopoloAuthError) {
       throw new TopoloMcpPublicError("credential rejected.");
@@ -5544,9 +6219,11 @@ export {
   createStdioTransport,
   exitStdioProcess,
   isDirectExecution,
+  loadIdentity,
   loadScopes,
   readStdioEnvironment,
   runStdioMcp,
+  scopesForIdentity,
   terminateStdioMcp,
   writeStdioError
 };