@topolo/mcp 0.4.3 → 0.4.5

package/README.md

@@ -79,7 +79,7 @@ ready-made agent guide that covers both the CLI and this MCP.
 | `TOPOLO_API_KEY`             | Platform API key (preferred)                          |
 | `TOPOLO_ACCESS_TOKEN`        | Short-lived JWT (dev/testing)                         |
 | `TOPOLO_AGENT_NAME`          | Human-readable agent label for audit logs             |
-| `TOPOLO_SERVICE_URL_<ID>`    | Override a service base URL (e.g. `_AUTH`, `_CRM`)    |
+| `TOPOLO_SERVICE_URL_<ID>`    | Override a service base URL (e.g. `_AUTH`, `_MAIL`)   |
 
 Exactly one credential var must be set. If both are present, `TOPOLO_API_KEY`
 wins.
@@ -88,8 +88,10 @@ wins.
 
 1. Resolve the credential from env. **Refuse to start** if none is set.
 2. Call `GET /api/me` to load the user's granted scopes + role.
-3. Filter `TOOLS` by those scopes — agents never see a tool they cannot use.
-4. Connect the stdio transport and begin serving MCP requests.
+3. Connect the stdio transport and begin serving MCP requests.
+4. On tool listing and tool calls, filter static tools by those scopes and load
+   the live action catalog for the credential. Agents never see an action tool
+   they cannot use.
 
 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
@@ -105,10 +107,17 @@ clients surface that as a failed server launch.
 | `topolo_get_application`     | (none)                | no               |
 | `topolo_list_application_requirements` | (none)      | no               |
 | `topolo_audit_applications`  | (none)                | no               |
-| `topolo_crm_list_contacts`   | `crm.contacts:read`   | no               |
-| `topolo_crm_get_contact`     | `crm.contacts:read`   | no               |
+| `topolo_list_actions`        | (credential-scoped)   | no               |
+| Dynamic action tools         | action permission     | action-defined   |
 | `topolo_api_call`            | (service-enforced)    | yes              |
 
+Applications publish machine-action definitions through Topolo Developers.
+TopoloAuth projects those into a credential-scoped action catalog using the
+same service permissions already used for API keys and application access. MCP
+turns each visible catalog entry into a tool named by the action catalog, such
+as `topolo_mail_messages_send`, with the action's input schema and destructive
+hint.
+
 `topolo_api_call` is the escape hatch for endpoints without typed MCP tools
 yet. GET requests work without confirmation; mutating HTTP methods must pass
 `confirm: true` or the SDK rejects the call. Backing services still enforce
@@ -116,7 +125,8 @@ permissions for every request. The tool schema intentionally does not embed a
 large service enum; agents should call `topolo_list_services` first, then pass a
 service ID/slug from that credential-scoped result. New services become callable
 without an MCP release once Auth grants the organization and credential the
-relevant permissions.
+relevant permissions, and new actions become typed tools without an MCP release
+once the application publishes them.
 
 ## Safety rails
 
@@ -128,11 +138,13 @@ relevant permissions.
 - **Credential-scoped catalog discovery.** `topolo_list_services` and
   `topolo_list_applications` use TopoloAuth's live organization/permission
   catalog. They do not expose the global generated platform catalog.
+- **Credential-scoped action discovery.** Dynamic action tools are loaded from
+  the live Auth action catalog and filtered by existing service permissions.
 - **Audit headers.** Every request sends `X-Topolo-Client: topolo-mcp/<ver>`,
   `X-Topolo-Agent: <label>`, `X-Topolo-Request-Id: <uuid>`.
 - **Write-action confirmation.** The SDK refuses mutating HTTP methods unless
-  the call explicitly passes `confirm: true`. Mutating tools (when introduced)
-  will require the host client to approve before invocation.
+  the call explicitly passes `confirm: true`. Mutating action tools require the
+  host client to approve before invocation.
 
 ## Troubleshooting
 
@@ -175,6 +187,6 @@ after running the same package checks and `npm pack --dry-run`.
 
 ## Phase 2 (planned)
 
-- More typed tools as `@topolo/sdk` modules ship.
+- Hosted action catalog administration in Developers UI.
 - HTTP transport in addition to stdio, for hosted (non-subprocess) deployments.
 - Optional `--provenance` on npm publish once the repo is public.

package/dist/dispatch.d.ts

@@ -43,6 +43,7 @@ interface ToolDef {
 }
 declare const TOOLS: ToolDef[];
 declare function filterToolsByScopes(tools: ToolDef[], scopes: ScopeSet): ToolDef[];
+declare function buildTopoloTools(topolo: Topolo, scopes: ScopeSet, tools?: ToolDef[]): Promise<ToolDef[]>;
 
 /**
  * Transport-agnostic Topolo tool dispatch.
@@ -84,6 +85,7 @@ interface ToolAdvertisement {
     inputSchema: Record<string, unknown>;
 }
 declare function listAvailableTopoloTools(scopes: ScopeSet, tools?: ToolDef[]): ToolAdvertisement[];
+declare function listAvailableDynamicTopoloTools(topolo: Topolo, scopes: ScopeSet, tools?: ToolDef[]): Promise<ToolAdvertisement[]>;
 declare function dispatchTopoloTool(input: ToolDispatchInput): Promise<ToolDispatchResult>;
 
-export { type ScopeSet, TOOLS, type ToolAdvertisement, type ToolDef, type ToolDispatchFailureReason, type ToolDispatchInput, type ToolDispatchResult, dispatchTopoloTool, filterToolsByScopes, hasAnyScope, hasScope, listAvailableTopoloTools };
+export { type ScopeSet, TOOLS, type ToolAdvertisement, type ToolDef, type ToolDispatchFailureReason, type ToolDispatchInput, type ToolDispatchResult, buildTopoloTools, dispatchTopoloTool, filterToolsByScopes, hasAnyScope, hasScope, listAvailableDynamicTopoloTools, listAvailableTopoloTools };

package/dist/dispatch.js

@@ -10,6 +10,7 @@ import {
   auditAllApplicationRequirements,
   applicationRequirementScopes,
   requirementsForApplication,
+  resolveCatalogServiceUrl,
   resolveServiceUrl
 } from "@topolo/sdk";
 
@@ -87,7 +88,9 @@ var TOOLS = [
           slug: entry.slug,
           name: entry.name,
           baseUrl: entry.baseUrl,
-          effectiveUrl: entry.baseUrl || resolveServiceUrl(id),
+          apiBaseUrl: entry.apiBaseUrl,
+          launchUrl: entry.launchUrl,
+          effectiveUrl: resolveCatalogServiceUrl(entry, { serviceKey: id }) || resolveServiceUrl(id),
           surfaceKind: entry.surfaceKind,
           launchable: entry.launchable,
           permissions: [...entry.permissions]
@@ -96,6 +99,28 @@ var TOOLS = [
       return { services };
     }
   },
+  {
+    name: "topolo_list_actions",
+    title: "List every Topolo action the agent can call",
+    description: "Returns the credential-scoped callable action catalog. Actions are published by applications through TopoloDevelopers and filtered by TopoloAuth against the current organization and effective permissions.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        service: {
+          type: "string",
+          description: "Optional service id, slug, or name filter."
+        }
+      },
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => ({
+      actions: await topolo.client.listActions({
+        service: typeof args["service"] === "string" ? args["service"] : void 0
+      })
+    })
+  },
   {
     name: "topolo_list_applications",
     title: "List every Topolo platform application",
@@ -229,29 +254,6 @@ var TOOLS = [
       return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
     }
   },
-  {
-    name: "topolo_crm_list_contacts",
-    title: "List CRM contacts",
-    description: "List contacts in the authenticated organization from TopoloCRM. Supports full-text search and pagination. All results are scoped to the caller's organization \u2014 there is no way to query contacts from another org.",
-    requiredScopes: ["crm.contacts:read"],
-    destructive: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Full-text search string" },
-        page: { type: "integer", minimum: 1, default: 1 },
-        pageSize: { type: "integer", minimum: 1, maximum: 200, default: 25 }
-      },
-      additionalProperties: false
-    },
-    handler: async (topolo, args) => {
-      return topolo.crm.listContacts({
-        q: typeof args["query"] === "string" ? args["query"] : void 0,
-        page: typeof args["page"] === "number" ? args["page"] : void 0,
-        pageSize: typeof args["pageSize"] === "number" ? args["pageSize"] : void 0
-      });
-    }
-  },
   {
     name: "topolo_api_call",
     title: "Call any Topolo platform service",
@@ -319,35 +321,59 @@ var TOOLS = [
         confirm: Boolean(args["confirm"])
       });
     }
-  },
-  {
-    name: "topolo_crm_get_contact",
-    title: "Fetch a single CRM contact",
-    description: "Fetch a single contact by id from TopoloCRM, scoped to the caller's organization.",
-    requiredScopes: ["crm.contacts:read"],
-    destructive: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        contactId: { type: "string", minLength: 1 }
-      },
-      required: ["contactId"],
-      additionalProperties: false
-    },
-    handler: async (topolo, args) => {
-      const contactId = args["contactId"];
-      if (typeof contactId !== "string" || !contactId) {
-        throw new Error("contactId is required");
-      }
-      const contact = await topolo.crm.getContact(contactId);
-      if (!contact) throw new Error(`Contact not found: ${contactId}`);
-      return contact;
-    }
   }
 ];
 function filterToolsByScopes(tools, scopes) {
   return tools.filter((t) => hasAnyScope(scopes, t.requiredScopes));
 }
+async function buildTopoloTools(topolo, scopes, tools = TOOLS) {
+  const baseTools = filterToolsByScopes(tools, scopes);
+  const actions = await topolo.client.listActions().catch(() => []);
+  const actionTools = actionsToToolDefs(actions);
+  return filterToolsByScopes([...baseTools, ...actionTools], scopes);
+}
+function actionsToToolDefs(actions) {
+  return actions.map((action) => ({
+    name: action.toolName || toolNameForAction(action),
+    title: action.title,
+    description: action.description,
+    requiredScopes: action.requiredPermission ? [action.requiredPermission] : [],
+    destructive: action.destructive || action.requiresConfirmation || action.method !== "GET",
+    inputSchema: actionInputSchema(action),
+    handler: async (topolo, args) => {
+      const confirm = Boolean(args["confirm"]);
+      const input = { ...args };
+      delete input["confirm"];
+      return topolo.client.callAction(action.actionId, input, { confirm });
+    }
+  }));
+}
+function toolNameForAction(action) {
+  const service = (action.serviceSlug || action.serviceId || "service").replace(/^topolo-/, "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  const name = action.name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return ["topolo", service, name].filter(Boolean).join("_").slice(0, 96);
+}
+function actionInputSchema(action) {
+  const schema = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+    ...action.inputSchema
+  };
+  const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties) ? { ...schema.properties } : {};
+  if (action.requiresConfirmation || action.method !== "GET") {
+    properties.confirm = {
+      type: "boolean",
+      description: "Required for mutating actions. Explicit human-in-the-loop acknowledgement."
+    };
+  }
+  return {
+    ...schema,
+    type: "object",
+    properties,
+    additionalProperties: schema.additionalProperties ?? false
+  };
+}
 function evaluateApplicationAuditGate(report, threshold) {
   const counts = {
     met: 0,
@@ -423,9 +449,19 @@ function listAvailableTopoloTools(scopes, tools = TOOLS) {
     inputSchema: t.inputSchema
   }));
 }
+async function listAvailableDynamicTopoloTools(topolo, scopes, tools = TOOLS) {
+  return (await buildTopoloTools(topolo, scopes, tools)).map((t) => ({
+    name: t.name,
+    title: t.title,
+    description: t.description,
+    requiredScopes: t.requiredScopes,
+    destructive: t.destructive,
+    inputSchema: t.inputSchema
+  }));
+}
 async function dispatchTopoloTool(input) {
   const started = Date.now();
-  const tools = input.tools ?? TOOLS;
+  const tools = await buildTopoloTools(input.topolo, input.scopes, input.tools ?? TOOLS);
   const available = filterToolsByScopes(tools, input.scopes);
   const tool = available.find((t) => t.name === input.toolName);
   if (!tool) {
@@ -476,9 +512,11 @@ async function dispatchTopoloTool(input) {
 }
 export {
   TOOLS,
+  buildTopoloTools,
   dispatchTopoloTool,
   filterToolsByScopes,
   hasAnyScope,
   hasScope,
+  listAvailableDynamicTopoloTools,
   listAvailableTopoloTools
 };

package/dist/index.js

@@ -2040,15 +2040,88 @@ function statusRank(status) {
   return 2;
 }
 var DEFAULT_SERVICE_URLS = SERVICES;
+function resolveCatalogServiceUrl(entry, options = {}) {
+  const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
+  const override = resolveServiceUrlOverride(keys, options.overrides);
+  if (override) return override;
+  const apiBaseUrl = firstString(entry.apiBaseUrl, entry.api_base_url);
+  if (apiBaseUrl) return apiBaseUrl;
+  const bundledUrl = firstBundledServiceUrl(keys);
+  const liveUrl = firstString(entry.baseUrl);
+  if (bundledUrl && (!liveUrl || sameUrlEnvironment(bundledUrl, liveUrl))) return bundledUrl;
+  return liveUrl ?? bundledUrl ?? null;
+}
 function resolveServiceUrl(service, overrides) {
-  const override = overrides?.[service];
+  const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
-  const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, "_").toUpperCase()}`;
-  const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
-  if (envValue) return envValue;
   return DEFAULT_SERVICE_URLS[service];
 }
+function catalogServiceKeyCandidates(entry, preferred) {
+  const values = [preferred, entry.slug, entry.name, entry.serviceId].filter(
+    (value) => typeof value === "string" && value.trim().length > 0
+  );
+  const keys = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    for (const candidate of serviceKeyCandidates(value)) keys.add(candidate);
+  }
+  return [...keys];
+}
+function serviceKeyCandidates(value) {
+  const normalized = value.trim().toLowerCase().replace(/\s+/g, "-");
+  const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
+  return [.../* @__PURE__ */ new Set([
+    normalized,
+    normalized.replace(/-/g, "_"),
+    withoutTopolo,
+    withoutTopolo.replace(/-/g, "_")
+  ])].filter(Boolean);
+}
+function resolveServiceUrlOverride(keys, overrides) {
+  for (const key of keys) {
+    const direct = overrides?.[key];
+    if (direct) return direct;
+    const envStyleKey = key.replace(/\./g, "_");
+    const envStyle = overrides?.[envStyleKey];
+    if (envStyle) return envStyle;
+  }
+  for (const key of keys) {
+    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, "_").toUpperCase()}`;
+    const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+    if (envValue) return envValue;
+  }
+  return null;
+}
+function firstBundledServiceUrl(keys) {
+  for (const key of keys) {
+    const url = DEFAULT_SERVICE_URLS[key];
+    if (url) return url;
+  }
+  return null;
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+function sameUrlEnvironment(left, right) {
+  return urlEnvironment(left) === urlEnvironment(right);
+}
+function urlEnvironment(value) {
+  try {
+    const url = new URL(value);
+    const host = url.hostname.toLowerCase();
+    if (host === "localhost" || host === "127.0.0.1") return "local";
+    if (host.endsWith(".stg.topolo.us") || host.includes("topolo-staging")) return "staging";
+    if (host.endsWith(".topolo.app") || host.endsWith(".topolo.us")) return "production";
+    return "external";
+  } catch {
+    return "external";
+  }
+}
 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";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var CATALOG_CACHE_TTL_MS = 60 * 1e3;
@@ -2062,6 +2135,7 @@ var TopoloClient = class _TopoloClient {
   fetchImpl;
   debug;
   serviceCatalogCache = null;
+  actionCatalogCache = null;
   /**
    * Process-wide cache for slug → service-id lookups. Keyed by
    * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
@@ -2215,8 +2289,12 @@ var TopoloClient = class _TopoloClient {
   async resolveLiveCallableService(serviceKey) {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
-    if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return { serviceKey, baseUrl: match.baseUrl };
+    if (!match || !isCallableCatalogEntry(match)) return null;
+    const baseUrl = resolveCatalogServiceUrl(match, {
+      serviceKey,
+      overrides: this.serviceUrls
+    });
+    return baseUrl ? { serviceKey, baseUrl } : null;
   }
   /**
    * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
@@ -2310,6 +2388,8 @@ var TopoloClient = class _TopoloClient {
         name: typeof s.name === "string" ? s.name : null,
         description: typeof s.description === "string" ? s.description : null,
         baseUrl: typeof s.base_url === "string" ? s.base_url : null,
+        apiBaseUrl: typeof s.api_base_url === "string" ? s.api_base_url : typeof s.apiBaseUrl === "string" ? s.apiBaseUrl : null,
+        launchUrl: typeof s.launch_url === "string" ? s.launch_url : typeof s.launchUrl === "string" ? s.launchUrl : null,
         status: typeof s.status === "string" ? s.status : null,
         surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
         launchable: s.launchable === true,
@@ -2322,6 +2402,67 @@ var TopoloClient = class _TopoloClient {
     };
     return entries;
   }
+  /**
+   * List callable actions from the live Auth catalog. The response is scoped to
+   * the caller's organization and effective permissions; no bundled/static app
+   * action list is used as an authorization source.
+   */
+  async listActions(options = {}) {
+    const now = Date.now();
+    if (!options.service && this.actionCatalogCache && this.actionCatalogCache.expiresAt > now) {
+      return this.actionCatalogCache.entries;
+    }
+    const res = await this.request({
+      service: "auth",
+      method: "GET",
+      path: "/api/actions/catalog",
+      ...options.service ? { query: { service: options.service } } : {}
+    });
+    const raw = res.data?.actions ?? res.actions;
+    if (!Array.isArray(raw)) {
+      throw new TopoloSdkError(
+        "action_catalog_unavailable",
+        "TopoloAuth did not return an action catalog for the current credential."
+      );
+    }
+    const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry));
+    if (!options.service) {
+      this.actionCatalogCache = {
+        entries,
+        expiresAt: now + CATALOG_CACHE_TTL_MS
+      };
+    }
+    return entries;
+  }
+  async getAction(action) {
+    const needle = normalizeActionLookupKey(action);
+    const actions = await this.listActions();
+    const match = actions.find((entry) => actionEntryMatches(entry, needle));
+    if (!match) {
+      throw new TopoloSdkError(
+        "unknown_action",
+        `Unknown Topolo action "${action}". Run action discovery first and pass an action id, name, or tool name.`
+      );
+    }
+    return match;
+  }
+  async callAction(action, input = {}, options = {}) {
+    const entry = await this.getAction(action);
+    const mapped = mapActionInput(entry, input);
+    const service = entry.serviceSlug || entry.serviceId;
+    return this.request({
+      service,
+      method: entry.method,
+      path: mapped.path,
+      ...mapped.query ? { query: mapped.query } : {},
+      ...mapped.body !== void 0 ? { body: mapped.body } : {},
+      headers: {
+        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
+        [TOPOLO_ACTION_NAME_HEADER]: entry.name
+      },
+      confirm: options.confirm === true
+    });
+  }
   /**
    * Bundled generated registry for tooling that audits platform packaging, not
    * for deciding what the current credential may use.
@@ -2334,6 +2475,8 @@ var TopoloClient = class _TopoloClient {
       name: app.name ?? app.id,
       description: null,
       baseUrl: app.productionUrl ?? null,
+      apiBaseUrl: null,
+      launchUrl: app.productionUrl ?? null,
       status: "bundled",
       surfaceKind: "application",
       launchable: Boolean(app.productionUrl),
@@ -2377,7 +2520,7 @@ var TopoloClient = class _TopoloClient {
   }
 };
 function resolveConfiguredServiceId(slug, serviceIds) {
-  for (const serviceKey of serviceKeyCandidates(slug)) {
+  for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceIds?.[serviceKey];
     if (typeof configured === "string" && configured.trim()) return configured.trim();
     const envKey = `TOPOLO_SERVICE_ID_${serviceKey.replace(/\./g, "_").toUpperCase()}`;
@@ -2387,7 +2530,7 @@ function resolveConfiguredServiceId(slug, serviceIds) {
   return null;
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
-  for (const serviceKey of serviceKeyCandidates(slug)) {
+  for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceUrls?.[serviceKey];
     if (typeof configured === "string" && configured.trim()) return configured.trim();
     const envKey = `TOPOLO_SERVICE_URL_${serviceKey.replace(/\./g, "_").toUpperCase()}`;
@@ -2396,7 +2539,7 @@ function resolveConfiguredServiceUrl(slug, serviceUrls) {
   }
   return null;
 }
-function serviceKeyCandidates(slug) {
+function serviceKeyCandidates2(slug) {
   const normalized = normalizeLookupKey(slug);
   const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
   return [.../* @__PURE__ */ new Set([
@@ -2418,7 +2561,7 @@ function catalogEntryLookupKeys(entry) {
   for (const value of values) {
     const normalized = normalizeLookupKey(value);
     if (!normalized) continue;
-    for (const candidate of serviceKeyCandidates(normalized)) {
+    for (const candidate of serviceKeyCandidates2(normalized)) {
       keys.add(candidate);
     }
   }
@@ -2428,9 +2571,101 @@ function isCallableCatalogEntry(entry) {
   const kind = normalizeLookupKey(entry.surfaceKind || "");
   if (kind === "api" || kind === "technical_service" || kind === "service") return true;
   return Boolean(
-    entry.baseUrl && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
+    (entry.baseUrl || entry.apiBaseUrl) && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
   );
 }
+function normalizeActionCatalogEntry(item) {
+  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+  const a = item;
+  const actionId = pickActionString(a.action_id) ?? pickActionString(a.actionId);
+  const name = pickActionString(a.name);
+  const serviceId = pickActionString(a.service_id) ?? pickActionString(a.serviceId);
+  const method = pickActionString(a.method)?.toUpperCase();
+  const path = pickActionString(a.path);
+  if (!actionId || !name || !serviceId || !method || !path || !isHttpMethod(method)) {
+    return null;
+  }
+  return {
+    actionId,
+    name,
+    toolName: pickActionString(a.tool_name) ?? pickActionString(a.toolName) ?? null,
+    title: pickActionString(a.title) ?? name,
+    description: pickActionString(a.description) ?? "",
+    serviceId,
+    serviceSlug: pickActionString(a.service_slug) ?? pickActionString(a.serviceSlug) ?? null,
+    serviceName: pickActionString(a.service_name) ?? pickActionString(a.serviceName) ?? null,
+    method,
+    path,
+    permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? "",
+    requiredPermission: pickActionString(a.required_permission) ?? pickActionString(a.requiredPermission) ?? "",
+    inputSchema: plainObject(a.input_schema ?? a.inputSchema),
+    outputSchema: plainObject(a.output_schema ?? a.outputSchema),
+    readOnly: Boolean(a.read_only ?? a.readOnly),
+    destructive: Boolean(a.destructive),
+    requiresConfirmation: Boolean(a.requires_confirmation ?? a.requiresConfirmation),
+    status: pickActionString(a.status),
+    sourceRevision: pickActionString(a.source_revision) ?? pickActionString(a.sourceRevision)
+  };
+}
+function isHttpMethod(value) {
+  return value === "GET" || value === "POST" || value === "PUT" || value === "PATCH" || value === "DELETE";
+}
+function pickActionString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function plainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function normalizeActionLookupKey(value) {
+  return String(value || "").trim().toLowerCase();
+}
+function actionEntryMatches(entry, needle) {
+  if (!needle) return false;
+  return [entry.actionId, entry.name, entry.toolName].filter((value) => typeof value === "string" && value.length > 0).some((value) => value.toLowerCase() === needle);
+}
+function mapActionInput(action, input) {
+  const remaining = { ...input || {} };
+  const path = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => {
+    const value = remaining[key];
+    if (value === void 0 || value === null || value === "") {
+      throw new TopoloSdkError(
+        "invalid_action_input",
+        `Action "${action.name}" requires path parameter "${key}".`
+      );
+    }
+    delete remaining[key];
+    return encodeURIComponent(String(value));
+  });
+  const explicitQuery = plainObject(remaining.query);
+  delete remaining.query;
+  const explicitBody = Object.prototype.hasOwnProperty.call(remaining, "body") ? remaining.body : void 0;
+  delete remaining.body;
+  if (action.method === "GET") {
+    return {
+      path,
+      query: objectToQuery({ ...remaining, ...explicitQuery })
+    };
+  }
+  const query = objectToQuery(explicitQuery);
+  const body = explicitBody !== void 0 ? explicitBody : remaining;
+  return {
+    path,
+    ...query ? { query } : {},
+    body
+  };
+}
+function objectToQuery(value) {
+  const query = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (raw === void 0 || raw === null) continue;
+    if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean") {
+      query[key] = raw;
+    } else {
+      query[key] = JSON.stringify(raw);
+    }
+  }
+  return Object.keys(query).length > 0 ? query : void 0;
+}
 function describeError(body, fallback) {
   if (body && typeof body === "object") {
     const maybe = body;
@@ -2631,7 +2866,9 @@ var TOOLS = [
           slug: entry.slug,
           name: entry.name,
           baseUrl: entry.baseUrl,
-          effectiveUrl: entry.baseUrl || resolveServiceUrl(id),
+          apiBaseUrl: entry.apiBaseUrl,
+          launchUrl: entry.launchUrl,
+          effectiveUrl: resolveCatalogServiceUrl(entry, { serviceKey: id }) || resolveServiceUrl(id),
           surfaceKind: entry.surfaceKind,
           launchable: entry.launchable,
           permissions: [...entry.permissions]
@@ -2640,6 +2877,28 @@ var TOOLS = [
       return { services };
     }
   },
+  {
+    name: "topolo_list_actions",
+    title: "List every Topolo action the agent can call",
+    description: "Returns the credential-scoped callable action catalog. Actions are published by applications through TopoloDevelopers and filtered by TopoloAuth against the current organization and effective permissions.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        service: {
+          type: "string",
+          description: "Optional service id, slug, or name filter."
+        }
+      },
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => ({
+      actions: await topolo.client.listActions({
+        service: typeof args["service"] === "string" ? args["service"] : void 0
+      })
+    })
+  },
   {
     name: "topolo_list_applications",
     title: "List every Topolo platform application",
@@ -2773,29 +3032,6 @@ var TOOLS = [
       return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
     }
   },
-  {
-    name: "topolo_crm_list_contacts",
-    title: "List CRM contacts",
-    description: "List contacts in the authenticated organization from TopoloCRM. Supports full-text search and pagination. All results are scoped to the caller's organization \u2014 there is no way to query contacts from another org.",
-    requiredScopes: ["crm.contacts:read"],
-    destructive: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Full-text search string" },
-        page: { type: "integer", minimum: 1, default: 1 },
-        pageSize: { type: "integer", minimum: 1, maximum: 200, default: 25 }
-      },
-      additionalProperties: false
-    },
-    handler: async (topolo, args) => {
-      return topolo.crm.listContacts({
-        q: typeof args["query"] === "string" ? args["query"] : void 0,
-        page: typeof args["page"] === "number" ? args["page"] : void 0,
-        pageSize: typeof args["pageSize"] === "number" ? args["pageSize"] : void 0
-      });
-    }
-  },
   {
     name: "topolo_api_call",
     title: "Call any Topolo platform service",
@@ -2863,35 +3099,59 @@ var TOOLS = [
         confirm: Boolean(args["confirm"])
       });
     }
-  },
-  {
-    name: "topolo_crm_get_contact",
-    title: "Fetch a single CRM contact",
-    description: "Fetch a single contact by id from TopoloCRM, scoped to the caller's organization.",
-    requiredScopes: ["crm.contacts:read"],
-    destructive: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        contactId: { type: "string", minLength: 1 }
-      },
-      required: ["contactId"],
-      additionalProperties: false
-    },
-    handler: async (topolo, args) => {
-      const contactId = args["contactId"];
-      if (typeof contactId !== "string" || !contactId) {
-        throw new Error("contactId is required");
-      }
-      const contact = await topolo.crm.getContact(contactId);
-      if (!contact) throw new Error(`Contact not found: ${contactId}`);
-      return contact;
-    }
   }
 ];
 function filterToolsByScopes(tools, scopes) {
   return tools.filter((t) => hasAnyScope(scopes, t.requiredScopes));
 }
+async function buildTopoloTools(topolo, scopes, tools = TOOLS) {
+  const baseTools = filterToolsByScopes(tools, scopes);
+  const actions = await topolo.client.listActions().catch(() => []);
+  const actionTools = actionsToToolDefs(actions);
+  return filterToolsByScopes([...baseTools, ...actionTools], scopes);
+}
+function actionsToToolDefs(actions) {
+  return actions.map((action) => ({
+    name: action.toolName || toolNameForAction(action),
+    title: action.title,
+    description: action.description,
+    requiredScopes: action.requiredPermission ? [action.requiredPermission] : [],
+    destructive: action.destructive || action.requiresConfirmation || action.method !== "GET",
+    inputSchema: actionInputSchema(action),
+    handler: async (topolo, args) => {
+      const confirm = Boolean(args["confirm"]);
+      const input = { ...args };
+      delete input["confirm"];
+      return topolo.client.callAction(action.actionId, input, { confirm });
+    }
+  }));
+}
+function toolNameForAction(action) {
+  const service = (action.serviceSlug || action.serviceId || "service").replace(/^topolo-/, "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  const name = action.name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return ["topolo", service, name].filter(Boolean).join("_").slice(0, 96);
+}
+function actionInputSchema(action) {
+  const schema = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+    ...action.inputSchema
+  };
+  const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties) ? { ...schema.properties } : {};
+  if (action.requiresConfirmation || action.method !== "GET") {
+    properties.confirm = {
+      type: "boolean",
+      description: "Required for mutating actions. Explicit human-in-the-loop acknowledgement."
+    };
+  }
+  return {
+    ...schema,
+    type: "object",
+    properties,
+    additionalProperties: schema.additionalProperties ?? false
+  };
+}
 function evaluateApplicationAuditGate(report, threshold) {
   const counts = {
     met: 0,
@@ -2961,25 +3221,28 @@ var MCP_VERSION = "0.4.1";
 
 // src/server.ts
 function buildServer(topolo, scopes, tools = TOOLS) {
-  const availableTools = filterToolsByScopes(tools, scopes);
   const server = new Server(
     { name: "topolo", version: MCP_VERSION },
     { capabilities: { tools: {} } }
   );
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: availableTools.map((t) => ({
-      name: t.name,
-      title: t.title,
-      description: t.description,
-      inputSchema: t.inputSchema,
-      annotations: {
-        destructiveHint: t.destructive,
-        readOnlyHint: !t.destructive
-      }
-    }))
-  }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const availableTools = await buildTopoloTools(topolo, scopes, tools);
+    return {
+      tools: availableTools.map((t) => ({
+        name: t.name,
+        title: t.title,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        annotations: {
+          destructiveHint: t.destructive,
+          readOnlyHint: !t.destructive
+        }
+      }))
+    };
+  });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const params = request.params;
+    const availableTools = await buildTopoloTools(topolo, scopes, tools);
     const tool = availableTools.find((t) => t.name === params.name);
     if (!tool) {
       return toolError(
@@ -3008,8 +3271,8 @@ function buildServer(topolo, scopes, tools = TOOLS) {
   });
   return server;
 }
-function advertisedToolNames(scopes, tools = TOOLS) {
-  return filterToolsByScopes(tools, scopes).map((t) => t.name);
+async function advertisedToolNames(topolo, scopes, tools = TOOLS) {
+  return (await buildTopoloTools(topolo, scopes, tools)).map((t) => t.name);
 }
 function toolError(message) {
   return {
@@ -3043,7 +3306,7 @@ async function main() {
   const server = buildServer(topolo, scopes);
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  const toolNames = advertisedToolNames(scopes);
+  const toolNames = await advertisedToolNames(topolo, scopes);
   process.stderr.write(
     `TopoloMCP v${MCP_VERSION} connected. Tools available: ${toolNames.join(", ") || "(none)"}
 `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/mcp",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Model Context Protocol server for the Topolo platform. Exposes scope-gated tools that third-party agents (Claude, Codex, etc.) can call natively.",
   "type": "module",
   "bin": {