@topolo/mcp 0.7.2 → 0.9.0

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// ../topolo-sdk/dist/index.js
+// ../../../topolo-platform/packages/topolo-sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -2092,6 +2092,262 @@ function firstString(...values) {
   }
   return null;
 }
+var SUPPORTED_SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
+  "$schema",
+  "$id",
+  "$ref",
+  "$defs",
+  "definitions",
+  "title",
+  "description",
+  "default",
+  "examples",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "type",
+  "nullable",
+  "const",
+  "enum",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "properties",
+  "required",
+  "additionalProperties",
+  "propertyNames",
+  "minProperties",
+  "maxProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "format",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf"
+]);
+function validateTopoloActionInput(schema, input) {
+  const schemaIssue = inspectSchema(schema, "$", schema, 0);
+  if (schemaIssue) return { valid: false, errors: [schemaIssue] };
+  const errors = [];
+  validateNode(schema, input, "$", schema, errors, 0);
+  return { valid: errors.length === 0, errors };
+}
+function inspectSchema(schema, path, root, depth) {
+  if (depth > 128) return { path, code: "schema_depth", message: "Schema recursion exceeded 128 levels." };
+  const unsupportedKeyword = Object.keys(schema).find((keyword) => !SUPPORTED_SCHEMA_KEYWORDS.has(keyword));
+  if (unsupportedKeyword) {
+    return { path, code: "unsupported_schema_keyword", message: `Action schema uses unsupported keyword ${unsupportedKeyword}.` };
+  }
+  if (typeof schema.format === "string" && !["uri", "email", "date-time"].includes(schema.format)) {
+    return { path, code: "unsupported_schema_format", message: `Action schema uses unsupported format ${schema.format}.` };
+  }
+  if (typeof schema.$ref === "string" && !resolveLocalReference(root, schema.$ref)) {
+    return { path, code: "unsupported_schema_ref", message: `Cannot resolve schema reference ${schema.$ref}.` };
+  }
+  const children = [];
+  if (isRecord(schema.properties)) children.push(...Object.entries(schema.properties));
+  if (isRecord(schema.$defs)) children.push(...Object.entries(schema.$defs));
+  if (isRecord(schema.definitions)) children.push(...Object.entries(schema.definitions));
+  children.push(
+    ["additionalProperties", schema.additionalProperties],
+    ["propertyNames", schema.propertyNames],
+    ["items", schema.items],
+    ...arraySchemaEntries("allOf", schema.allOf),
+    ...arraySchemaEntries("anyOf", schema.anyOf),
+    ...arraySchemaEntries("oneOf", schema.oneOf)
+  );
+  for (const [key, child] of children) {
+    if (!isRecord(child)) continue;
+    const issue = inspectSchema(child, `${path}.${key}`, root, depth + 1);
+    if (issue) return issue;
+  }
+  return null;
+}
+function arraySchemaEntries(keyword, value) {
+  return Array.isArray(value) ? value.map((candidate, index) => [`${keyword}[${index}]`, candidate]) : [];
+}
+function validateNode(schema, value, path, root, errors, depth) {
+  if (depth > 128) {
+    errors.push({ path, code: "schema_depth", message: "Schema recursion exceeded 128 levels." });
+    return;
+  }
+  if (typeof schema.$ref === "string") {
+    const resolved = resolveLocalReference(root, schema.$ref);
+    if (!resolved) {
+      errors.push({ path, code: "unsupported_schema_ref", message: `Cannot resolve schema reference ${schema.$ref}.` });
+      return;
+    }
+    validateNode(resolved, value, path, root, errors, depth + 1);
+  }
+  if (Array.isArray(schema.allOf)) {
+    for (const candidate of schema.allOf) {
+      if (isRecord(candidate)) validateNode(candidate, value, path, root, errors, depth + 1);
+    }
+  }
+  if (Array.isArray(schema.anyOf) && !schema.anyOf.some((candidate) => candidateMatches(candidate, value, root, depth))) {
+    errors.push({ path, code: "any_of", message: "Value does not match any allowed schema." });
+    return;
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const matches = schema.oneOf.filter((candidate) => candidateMatches(candidate, value, root, depth)).length;
+    if (matches !== 1) {
+      errors.push({ path, code: "one_of", message: "Value must match exactly one allowed schema." });
+      return;
+    }
+  }
+  if (value === null && schema.nullable === true) return;
+  if (Object.prototype.hasOwnProperty.call(schema, "const") && !sameJsonValue(value, schema.const)) {
+    errors.push({ path, code: "const", message: `Value must equal ${JSON.stringify(schema.const)}.` });
+    return;
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((candidate) => sameJsonValue(value, candidate))) {
+    errors.push({ path, code: "enum", message: `Value must be one of ${schema.enum.map((item) => JSON.stringify(item)).join(", ")}.` });
+    return;
+  }
+  if (!matchesType(schema.type, value)) {
+    errors.push({ path, code: "type", message: `Expected ${String(schema.type)}.` });
+    return;
+  }
+  if (typeof value === "string") validateString(schema, value, path, errors);
+  if (typeof value === "number") validateNumber(schema, value, path, errors);
+  if (Array.isArray(value)) validateArray(schema, value, path, root, errors, depth);
+  if (isRecord(value)) validateObject(schema, value, path, root, errors, depth);
+}
+function validateObject(schema, value, path, root, errors, depth) {
+  if (typeof schema.minProperties === "number" && Object.keys(value).length < schema.minProperties) {
+    errors.push({ path, code: "min_properties", message: `Expected at least ${schema.minProperties} properties.` });
+  }
+  if (typeof schema.maxProperties === "number" && Object.keys(value).length > schema.maxProperties) {
+    errors.push({ path, code: "max_properties", message: `Expected at most ${schema.maxProperties} properties.` });
+  }
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required = Array.isArray(schema.required) ? schema.required.map(String) : [];
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      errors.push({ path: `${path}.${key}`, code: "required", message: "Required property is missing." });
+    }
+  }
+  if (isRecord(schema.propertyNames)) {
+    for (const key of Object.keys(value)) {
+      validateNode(schema.propertyNames, key, `${path}.${key}`, root, errors, depth + 1);
+    }
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const childSchema = properties[key];
+    if (isRecord(childSchema)) {
+      validateNode(childSchema, child, `${path}.${key}`, root, errors, depth + 1);
+    } else if (schema.additionalProperties === false) {
+      errors.push({ path: `${path}.${key}`, code: "additional_property", message: "Property is not declared by the action schema." });
+    } else if (isRecord(schema.additionalProperties)) {
+      validateNode(schema.additionalProperties, child, `${path}.${key}`, root, errors, depth + 1);
+    }
+  }
+}
+function validateArray(schema, value, path, root, errors, depth) {
+  if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+    errors.push({ path, code: "min_items", message: `Expected at least ${schema.minItems} items.` });
+  }
+  if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+    errors.push({ path, code: "max_items", message: `Expected at most ${schema.maxItems} items.` });
+  }
+  if (schema.uniqueItems === true) {
+    const unique = new Set(value.map((item) => JSON.stringify(item)));
+    if (unique.size !== value.length) errors.push({ path, code: "unique_items", message: "Expected every item to be unique." });
+  }
+  if (isRecord(schema.items)) {
+    value.forEach((item, index) => validateNode(schema.items, item, `${path}[${index}]`, root, errors, depth + 1));
+  }
+}
+function validateString(schema, value, path, errors) {
+  if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+    errors.push({ path, code: "min_length", message: `Expected at least ${schema.minLength} characters.` });
+  }
+  if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+    errors.push({ path, code: "max_length", message: `Expected at most ${schema.maxLength} characters.` });
+  }
+  if (typeof schema.pattern === "string") {
+    try {
+      if (!new RegExp(schema.pattern).test(value)) errors.push({ path, code: "pattern", message: "Value does not match the required pattern." });
+    } catch {
+      errors.push({ path, code: "invalid_schema_pattern", message: "Action schema contains an invalid pattern." });
+    }
+  }
+  if (schema.format === "uri" && !isUrl(value)) errors.push({ path, code: "format_uri", message: "Expected an absolute URL." });
+  if (schema.format === "email" && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value)) errors.push({ path, code: "format_email", message: "Expected an email address." });
+  if (schema.format === "date-time" && !isDateTime(value)) errors.push({ path, code: "format_date_time", message: "Expected an ISO-8601 date-time." });
+}
+function validateNumber(schema, value, path, errors) {
+  if (typeof schema.minimum === "number" && value < schema.minimum) errors.push({ path, code: "minimum", message: `Expected a value of at least ${schema.minimum}.` });
+  if (typeof schema.maximum === "number" && value > schema.maximum) errors.push({ path, code: "maximum", message: `Expected a value of at most ${schema.maximum}.` });
+  const exclusiveMinimum = typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : schema.exclusiveMinimum === true && typeof schema.minimum === "number" ? schema.minimum : null;
+  const exclusiveMaximum = typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : schema.exclusiveMaximum === true && typeof schema.maximum === "number" ? schema.maximum : null;
+  if (exclusiveMinimum !== null && value <= exclusiveMinimum) {
+    errors.push({ path, code: "exclusive_minimum", message: `Expected a value greater than ${exclusiveMinimum}.` });
+  }
+  if (exclusiveMaximum !== null && value >= exclusiveMaximum) {
+    errors.push({ path, code: "exclusive_maximum", message: `Expected a value less than ${exclusiveMaximum}.` });
+  }
+  if (typeof schema.multipleOf === "number" && !isMultipleOf(value, schema.multipleOf)) {
+    errors.push({ path, code: "multiple_of", message: `Expected a multiple of ${schema.multipleOf}.` });
+  }
+}
+function candidateMatches(candidate, value, root, depth) {
+  if (!isRecord(candidate)) return false;
+  const issues = [];
+  validateNode(candidate, value, "$", root, issues, depth + 1);
+  return issues.length === 0;
+}
+function resolveLocalReference(root, reference) {
+  if (!reference.startsWith("#/")) return null;
+  let current = root;
+  for (const token of reference.slice(2).split("/").map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"))) {
+    if (Array.isArray(current)) {
+      if (!/^\d+$/.test(token) || Number(token) >= current.length) return null;
+      current = current[Number(token)];
+      continue;
+    }
+    if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, token)) return null;
+    current = current[token];
+  }
+  return isRecord(current) ? current : null;
+}
+function matchesType(type, value) {
+  if (type === void 0) return true;
+  if (Array.isArray(type)) return type.some((candidate) => matchesType(candidate, value));
+  if (type === "null") return value === null;
+  if (type === "array") return Array.isArray(value);
+  if (type === "object") return isRecord(value);
+  if (type === "integer") return typeof value === "number" && Number.isInteger(value);
+  return typeof value === type;
+}
+function sameJsonValue(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isUrl(value) {
+  try {
+    return Boolean(new URL(value).protocol);
+  } catch {
+    return false;
+  }
+}
+function isDateTime(value) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && !Number.isNaN(Date.parse(value));
+}
+function isMultipleOf(value, divisor) {
+  if (!(divisor > 0)) return false;
+  const quotient = value / divisor;
+  return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * Math.max(1, Math.abs(quotient)) * 4;
+}
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
 var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
@@ -2311,7 +2567,10 @@ var TopoloClient = class _TopoloClient {
       serviceKey,
       overrides: this.serviceUrls
     });
-    return baseUrl ? { serviceKey, baseUrl } : null;
+    if (baseUrl) return { 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;
   }
   /**
    * Resolve a service-slug → opaque app-id via caller config or TopoloAuth.
@@ -2396,7 +2655,7 @@ var TopoloClient = class _TopoloClient {
     }
     const entries = [];
     for (const item of raw) {
-      if (!isRecord(item)) continue;
+      if (!isRecord2(item)) continue;
       const s = item;
       const appId = typeof s.app_id === "string" ? s.app_id : typeof s.id === "string" ? s.id : null;
       if (!appId) continue;
@@ -2446,6 +2705,44 @@ var TopoloClient = class _TopoloClient {
     }
     return entry;
   }
+  async listBindableResources(application) {
+    const service = await this.getService(application);
+    const identity = await this.introspect();
+    if (identity.apiKey) {
+      return {
+        application: { appId: service.appId, slug: service.slug, name: service.name },
+        organizationId: identity.organization?.id ?? null,
+        resources: identity.apiKey.resourceBindings.map((binding) => ({
+          resourceType: binding.resourceType,
+          resourceId: binding.resourceId,
+          label: null,
+          slug: null,
+          status: "active",
+          organizationId: identity.organization?.id ?? null,
+          metadata: {}
+        })),
+        resourceTypes: service.apiKeyResources,
+        syncError: null,
+        source: "api_key_binding"
+      };
+    }
+    const response = await this.readAction(
+      "app_topolo_auth.service_api_key_resources.list",
+      { appId: service.appId }
+    );
+    const payload = isRecord2(response) && isRecord2(response.data) ? response.data : response;
+    if (!isRecord2(payload) || !Array.isArray(payload.resources)) {
+      throw new TopoloSdkError("resource_catalog_unavailable", "TopoloAuth did not return bindable resources.");
+    }
+    return {
+      application: { appId: service.appId, slug: service.slug, name: service.name },
+      organizationId: readOptionalString(payload.organizationId ?? payload.organization_id),
+      resources: payload.resources.map(normalizeBindableResource).filter((resource) => Boolean(resource)),
+      resourceTypes: normalizeApiKeyResourceMetadataList(payload.resourceTypes ?? payload.resource_types),
+      syncError: readOptionalString(payload.syncError ?? payload.sync_error),
+      source: "auth_catalog"
+    };
+  }
   /**
    * List callable actions from the live registry-canonical catalog (definitions
    * from the Catalog registry, scoping from Auth). The response is scoped to the
@@ -2540,10 +2837,44 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input, options);
   }
+  async validateActionInput(action, input = {}) {
+    const entry = await this.getAction(action);
+    return { action: entry, validation: validateTopoloActionInput(entry.inputSchema, input) };
+  }
+  async planAction(action, input = {}, options = {}) {
+    const entry = await this.getAction(action);
+    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;
+    let request = null;
+    if (validation.valid) {
+      const mapped = mapActionInput(entry, input);
+      request = {
+        method: entry.method,
+        service: entry.appSlug || entry.appId,
+        apiBaseUrl: entry.apiBaseUrl,
+        path: mapped.path,
+        ...mapped.query ? { query: mapped.query } : {},
+        ...mapped.body !== void 0 ? { body: mapped.body } : {},
+        ...options.resource ? { resource: options.resource } : {}
+      };
+    }
+    return {
+      action: entry,
+      validation,
+      confirmationRequired,
+      confirmationProvided: options.confirm === true,
+      executable: validation.valid && agentAccess !== "off" && (!confirmationRequired || options.confirm === true),
+      request,
+      verification: stringArray(entry.agentContract?.verify),
+      rollbackActionId: pickActionString(entry.agentContract?.rollbackActionId),
+      nextActionIds: stringArray(entry.agentContract?.nextActionIds)
+    };
+  }
   async readAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
-    if (entry.method !== "GET" || !entry.readOnly || entry.destructive || entry.requiresConfirmation || agentAccess !== "auto") {
+    if (!entry.readOnly || entry.destructive || entry.requiresConfirmation || agentAccess !== "auto") {
       throw new TopoloPermissionError(
         `Topolo action "${entry.actionId}" is not an automatic read-only action.`,
         entry.requiredPermission ? [entry.requiredPermission] : []
@@ -2564,6 +2895,13 @@ var TopoloClient = class _TopoloClient {
         `Topolo action "${entry.actionId}" requires { confirm: true } before invocation.`
       );
     }
+    const validation = validateTopoloActionInput(entry.inputSchema, input);
+    if (!validation.valid) {
+      throw new TopoloSdkError(
+        "invalid_action_input",
+        `Topolo action "${entry.actionId}" input is invalid: ${validation.errors.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`
+      );
+    }
     const mapped = mapActionInput(entry, input);
     const service = entry.appSlug || entry.appId;
     return this.request({
@@ -2578,7 +2916,7 @@ var TopoloClient = class _TopoloClient {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
       },
-      confirm: options.confirm === true
+      confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
     });
   }
   /**
@@ -2635,7 +2973,14 @@ var TopoloClient = class _TopoloClient {
         id: organization.id,
         slug: organization.slug,
         name: organization.name ?? organization.slug
-      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null
+      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null,
+      apiKey: kind === "api_key" ? {
+        id: readOptionalString(payload.apiKey?.id),
+        name: readOptionalString(payload.apiKey?.name),
+        appId: readOptionalString(payload.apiKey?.appId),
+        scopes: stringArray(payload.apiKey?.scopes),
+        resourceBindings: normalizeResourceBindings(payload.apiKey?.resourceBindings)
+      } : null
     };
   }
 };
@@ -2650,7 +2995,7 @@ function resolveConfiguredAppId(slug, appIds) {
   return null;
 }
 function normalizeApiKeyResourceMetadata(input) {
-  if (!isRecord(input)) return null;
+  if (!isRecord2(input)) return null;
   const resourceType = readString(input.resourceType ?? input.resource_type);
   const label = readString(input.label);
   const emptyLabel = readString(input.emptyLabel ?? input.empty_label);
@@ -2683,10 +3028,38 @@ function normalizeApiKeyResourceMetadataList(input) {
   }
   return resources;
 }
+function normalizeBindableResource(input) {
+  if (!isRecord2(input)) return null;
+  const resourceType = readString(input.resourceType ?? input.resource_type);
+  const resourceId = readString(input.resourceId ?? input.resource_id);
+  if (!resourceType || !resourceId) return null;
+  return {
+    resourceType,
+    resourceId,
+    label: readOptionalString(input.label),
+    slug: readOptionalString(input.slug),
+    status: readOptionalString(input.status),
+    organizationId: readOptionalString(input.organizationId ?? input.organization_id),
+    metadata: isRecord2(input.metadata) ? input.metadata : {}
+  };
+}
+function normalizeResourceBindings(input) {
+  if (!Array.isArray(input)) return [];
+  return input.flatMap((binding) => {
+    if (!isRecord2(binding)) return [];
+    const resourceType = readString(binding.resourceType ?? binding.resource_type);
+    const resourceId = readString(binding.resourceId ?? binding.resource_id);
+    return resourceType && resourceId ? [{ resourceType, resourceId }] : [];
+  });
+}
 function readString(value) {
   return typeof value === "string" ? value.trim() : "";
 }
-function isRecord(value) {
+function readOptionalString(value) {
+  const normalized = readString(value);
+  return normalized || null;
+}
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
@@ -2758,14 +3131,14 @@ function catalogSearchQuery(options) {
   return query;
 }
 function normalizeCatalogPage(value) {
-  if (!isRecord(value)) return { nextCursor: null, hasMore: false };
+  if (!isRecord2(value)) return { nextCursor: null, hasMore: false };
   return {
     nextCursor: typeof value.nextCursor === "string" && value.nextCursor ? value.nextCursor : null,
     hasMore: value.hasMore === true
   };
 }
 function normalizeServiceCatalogEntry(item) {
-  if (!isRecord(item)) return null;
+  if (!isRecord2(item)) return null;
   const appId = typeof item.app_id === "string" ? item.app_id : typeof item.id === "string" ? item.id : null;
   if (!appId) return null;
   const permissions = Array.isArray(item.granted_permissions) ? item.granted_permissions.filter(
@@ -2820,6 +3193,7 @@ function normalizeActionCatalogEntry(item) {
     authorizationMode: pickAuthorizationMode(a.authorization_mode ?? a.authorizationMode),
     inputSchema: plainObject(a.input_schema ?? a.inputSchema),
     outputSchema: plainObject(a.output_schema ?? a.outputSchema),
+    agentContract: plainObject(a.agent_contract ?? a.agentContract),
     readOnly: Boolean(a.read_only ?? a.readOnly),
     destructive: Boolean(a.destructive),
     requiresConfirmation: Boolean(a.requires_confirmation ?? a.requiresConfirmation),
@@ -2843,6 +3217,9 @@ function pickAuthorizationMode(value) {
 function plainObject(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
+function stringArray(value) {
+  return Array.isArray(value) ? value.map((item) => String(item || "").trim()).filter(Boolean) : [];
+}
 function mapActionInput(action, input) {
   const remaining = { ...input || {} };
   const path = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => {
@@ -2992,7 +3369,7 @@ function createTopolo(options) {
   };
 }
 
-// ../topolo-sdk/dist/node/credential-store.js
+// ../../../topolo-platform/packages/topolo-sdk/dist/node/credential-store.js
 import { mkdir, readFile, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir, platform } from "os";
@@ -3322,6 +3699,46 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
     return cred;
   }
 }
+async function refreshContextCredentialIfNeeded(environment, key, options = {}) {
+  const config = await readConfig();
+  const profile = profileForEnvironment(config, environment);
+  const context = profile.contexts?.[key];
+  const credential = context?.credential;
+  if (!credential || credential.kind !== "access_token") return credential ?? null;
+  const oauthClientId = context.oauthClientId ?? profile.oauthClientId;
+  if (!credential.refreshToken || !credential.expiresAt || !oauthClientId) return credential;
+  const now = Math.floor(Date.now() / 1e3);
+  if (!options.force && credential.expiresAt - REFRESH_SKEW_SECONDS > now) return credential;
+  try {
+    const oauth = new TopoloOAuth({
+      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+    });
+    const tokens = await oauth.refreshToken({
+      clientId: oauthClientId,
+      refreshToken: credential.refreshToken
+    });
+    const refreshed = {
+      kind: "access_token",
+      accessToken: tokens.access_token,
+      ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: credential.refreshToken },
+      expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
+    };
+    await writeConfig(writeProfileConfig(config, environment, {
+      ...profile.activeContext === key ? { credential: refreshed } : {},
+      contexts: {
+        ...profile.contexts ?? {},
+        [key]: {
+          ...context,
+          credential: refreshed,
+          oauthClientId
+        }
+      }
+    }));
+    return refreshed;
+  } catch {
+    return credential;
+  }
+}
 function resolveAgentName(configAgentName) {
   return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
 }
@@ -3344,15 +3761,6 @@ function resolveServiceUrls(configUrls, environment = selectedEnvironment()) {
   return Object.keys(merged).length > 0 ? merged : void 0;
 }
 
-// src/auth.ts
-function resolveCredentialFromEnv() {
-  const apiKey = process.env.TOPOLO_API_KEY;
-  if (apiKey) return { kind: "api_key", apiKey };
-  const accessToken = process.env.TOPOLO_ACCESS_TOKEN;
-  if (accessToken) return { kind: "access_token", accessToken };
-  return null;
-}
-
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -3607,6 +4015,148 @@ var TOOLS = [
       );
     }
   },
+  {
+    name: "topolo_validate_action",
+    title: "Validate Topolo action input",
+    description: "Validates input locally against the exact JSON Schema published for one credential-scoped action. Does not invoke the action.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("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.");
+      }
+      return topolo.client.validateActionInput(actionId, input ?? {});
+    }
+  },
+  {
+    name: "topolo_plan_action",
+    title: "Plan one Topolo action",
+    description: "Validates one credential-scoped action and returns its exact request, confirmation state, verification steps, rollback action, and next actions without executing it.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        resourceType: { type: "string", description: "Optional app-local resource alias, such as workspace." },
+        resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." },
+        confirm: { type: "boolean", description: "Include confirmation in the plan without executing the action." }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("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.");
+      }
+      const resource = optionalResourceContext(args);
+      return topolo.client.planAction(
+        actionId,
+        input ?? {},
+        {
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
+      );
+    }
+  },
+  {
+    name: "topolo_get_action_examples",
+    title: "Get Topolo action examples and documentation",
+    description: "Returns the public documentation URL and inline examples published for one action.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { actionId: { type: "string", minLength: 1 } },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("actionId is required.");
+      const action = await topolo.client.getAction(actionId);
+      return {
+        actionId: action.actionId,
+        docsUrl: action.agentContract?.docsUrl ?? null,
+        examples: action.agentContract?.examples ?? []
+      };
+    }
+  },
+  {
+    name: "topolo_discover_capabilities",
+    title: "Discover one Topolo application capability contract",
+    description: "Discovers capability and schema actions published by one application. Use the actionService value returned by topolo_search_applications as service.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { service: { type: "string", minLength: 1 } },
+      required: ["service"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const service = typeof args["service"] === "string" ? args["service"].trim() : "";
+      if (!service) throw new Error("service is required.");
+      return topolo.client.searchActions({ service, query: "capabilities", limit: 100 });
+    }
+  },
+  {
+    name: "topolo_get_resource_types",
+    title: "Get application resource-scoping types",
+    description: "Returns the canonical resource-scoping metadata published for one application, including aliases accepted by resource-scoped API keys and action calls.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { application: { type: "string", minLength: 1 } },
+      required: ["application"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const application = typeof args["application"] === "string" ? args["application"].trim() : "";
+      if (!application) throw new Error("application is required.");
+      const entry = await topolo.client.getService(application);
+      return {
+        application: { appId: entry.appId, slug: entry.slug, name: entry.name },
+        resourceTypes: entry.apiKeyResources
+      };
+    }
+  },
+  {
+    name: "topolo_list_resources",
+    title: "List bindable Topolo resource ids",
+    description: "Returns credential-scoped resource ids for one application. OAuth credentials use the published Auth resource catalog; API keys return only their own bound resources.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { application: { type: "string", minLength: 1 } },
+      required: ["application"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const application = typeof args["application"] === "string" ? args["application"].trim() : "";
+      if (!application) throw new Error("application is required.");
+      return topolo.client.listBindableResources(application);
+    }
+  },
   {
     name: "topolo_list_application_requirements",
     title: "List Topolo application build requirements",
@@ -3925,14 +4475,79 @@ function toolError(message) {
   };
 }
 
+// src/auth.ts
+function resolveCredentialFromEnv() {
+  const apiKey = process.env.TOPOLO_API_KEY;
+  if (apiKey) return { kind: "api_key", apiKey };
+  const accessToken = process.env.TOPOLO_ACCESS_TOKEN;
+  if (accessToken) return { kind: "access_token", accessToken };
+  return null;
+}
+
+// src/context-credential.ts
+var DEFAULT_DEPENDENCIES = {
+  readConfig,
+  refreshContextCredentialIfNeeded,
+  refreshCredentialIfNeeded,
+  resolveCredentialFromEnv
+};
+function resolvePinnedContextKey(profile, selector) {
+  const normalized = selector.trim().toLowerCase();
+  if (!normalized) {
+    throw new Error("TOPOLO_CONTEXT must not be empty");
+  }
+  const contexts = Object.entries(profile.contexts ?? {});
+  const exact = contexts.find(([key]) => key.toLowerCase() === normalized);
+  if (exact) return exact[0];
+  const matches = contexts.filter(([, context]) => [
+    context.organizationId,
+    context.organizationSlug,
+    context.organizationName
+  ].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 Error(`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");
+    }
+    return { credential: environmentCredential, contextKey: null };
+  }
+  if (requestedSelector) {
+    const config = await dependencies.readConfig();
+    const contextKey = resolvePinnedContextKey(
+      profileForEnvironment(config, environment),
+      requestedSelector
+    );
+    const credential = await dependencies.refreshContextCredentialIfNeeded(environment, contextKey);
+    return {
+      credential,
+      contextKey,
+      refreshCredential: () => dependencies.refreshContextCredentialIfNeeded(
+        environment,
+        contextKey,
+        { force: true }
+      )
+    };
+  }
+  return {
+    credential: await dependencies.refreshCredentialIfNeeded(environment),
+    contextKey: null,
+    refreshCredential: () => dependencies.refreshCredentialIfNeeded(environment, { force: true })
+  };
+}
+
 // src/index.ts
 async function main() {
   const environment = normalizeEnvironment(process.env.TOPOLO_ENV);
-  const environmentCredential = resolveCredentialFromEnv();
-  let credential = environmentCredential;
-  if (!credential) {
-    credential = await refreshCredentialIfNeeded(environment);
-  }
+  const resolvedCredential = await resolveMcpCredential(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"
@@ -3952,7 +4567,7 @@ async function main() {
     },
     serviceUrls,
     requireConfirmForWrites: true,
-    ...!environmentCredential ? { refreshCredential: () => refreshCredentialIfNeeded(environment, { force: true }) } : {}
+    ...resolvedCredential.refreshCredential ? { refreshCredential: resolvedCredential.refreshCredential } : {}
   });
   const scopes = await loadScopes(topolo);
   const server = buildServer(topolo, scopes);
@@ -3960,7 +4575,7 @@ async function main() {
   await server.connect(transport);
   const toolNames = await advertisedToolNames(topolo, scopes);
   process.stderr.write(
-    `TopoloMCP v${MCP_VERSION} connected (${environment}). Tools available: ${toolNames.join(", ") || "(none)"}
+    `TopoloMCP v${MCP_VERSION} connected (${environment}${resolvedCredential.contextKey ? `, ${resolvedCredential.contextKey}` : ""}). Tools available: ${toolNames.join(", ") || "(none)"}
 `
   );
 }