@topolo/mcp 0.9.11 → 0.10.1

package/README.md

@@ -217,6 +217,9 @@ sent.
   catalog. They do not expose the global generated platform catalog.
 - **Credential-scoped action discovery.** `topolo_search_actions` reads only one
   app partition and returns at most 100 permission-filtered actions per page.
+  Search, capability discovery, validation, planning, and application audit
+  return compact agent guidance by default; pass `detail: true` only when the
+  full contracts or findings are needed.
 - **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

package/dist/dispatch.js

@@ -5,11 +5,16 @@ import { TopoloAuthError, TopoloPermissionError } from "@topolo/sdk";
 import {
   APPLICATION_REQUIREMENTS,
   APPLICATION_REQUIREMENTS_VERSION,
-  APPLICATIONS,
-  DEFAULT_APP_URLS,
-  auditAllApplicationRequirements,
+  auditApplicationEntries,
   applicationRequirementScopes,
+  compactActionCatalogEntry,
+  compactActionPlan,
+  compactActionValidation,
+  compactApplicationAudit,
+  friendlyAppId,
+  listApplicationDirectory,
   requirementsForApplication,
+  resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl
 } from "@topolo/sdk";
 
@@ -62,7 +67,6 @@ function publicMcpErrorMessage(error, fallback) {
 }
 
 // src/tools.ts
-var APPLICATION_IDS = Object.keys(APPLICATIONS).sort();
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 function requiredString(args, name) {
   const value = typeof args[name] === "string" ? args[name].trim() : "";
@@ -78,6 +82,20 @@ function optionalResourceContext(args) {
   }
   return { resourceType, resourceId };
 }
+function coerceObjectParam(value, name) {
+  let candidate = value;
+  if (typeof candidate === "string" && candidate.trim().startsWith("{")) {
+    try {
+      candidate = JSON.parse(candidate);
+    } catch {
+    }
+  }
+  if (candidate === void 0) return {};
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new TopoloMcpPublicError(`${name} must be an object.`);
+  }
+  return candidate;
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -103,7 +121,8 @@ var TOOLS = [
       properties: {
         query: { type: "string" },
         cursor: { type: "string" },
-        limit: { type: "integer", minimum: 1, maximum: 100, default: 25 }
+        limit: { type: "integer", minimum: 1, maximum: 100, default: 25 },
+        detail: { type: "boolean", description: "Return full schemas and agent contracts. Defaults to compact action guidance." }
       },
       additionalProperties: false
     },
@@ -157,12 +176,13 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
       if (!service) throw new TopoloMcpPublicError("service is required for bounded action discovery.");
-      return topolo.client.searchActions({
+      const result = await topolo.client.searchActions({
         service,
         query: typeof args["query"] === "string" ? args["query"] : void 0,
         cursor: typeof args["cursor"] === "string" ? args["cursor"] : void 0,
         limit: typeof args["limit"] === "number" ? args["limit"] : void 0
       });
+      return args["detail"] === true ? result : { actions: result.actions.map(compactActionCatalogEntry), page: result.page };
     }
   },
   {
@@ -228,14 +248,11 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
       if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
-      const input = args["input"];
-      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new TopoloMcpPublicError("input must be an object.");
-      }
+      const input = coerceObjectParam(args["input"], "input");
       const resource = optionalResourceContext(args);
       return topolo.client.readAction(
         actionId,
-        input ?? {},
+        input,
         resource ? { resource } : {}
       );
     }
@@ -261,14 +278,11 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
       if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
-      const input = args["input"];
-      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new TopoloMcpPublicError("input must be an object.");
-      }
+      const input = coerceObjectParam(args["input"], "input");
       const resource = optionalResourceContext(args);
       return topolo.client.callAction(
         actionId,
-        input ?? {},
+        input,
         {
           confirm: args["confirm"] === true,
           ...resource ? { resource } : {}
@@ -307,23 +321,17 @@ var TOOLS = [
       if (!isCanonicalBase64(contentBase64)) throw new TopoloMcpPublicError("contentBase64 must be canonical base64.");
       if (!contentType) throw new TopoloMcpPublicError("contentType is required.");
       if (!fileName) throw new TopoloMcpPublicError("fileName is required.");
-      const input = args["input"];
-      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new TopoloMcpPublicError("input must be an object.");
-      }
-      const completionInput = args["completionInput"];
-      if (completionInput !== void 0 && (!completionInput || typeof completionInput !== "object" || Array.isArray(completionInput))) {
-        throw new TopoloMcpPublicError("completionInput must be an object.");
-      }
+      const input = coerceObjectParam(args["input"], "input");
+      const completionInput = coerceObjectParam(args["completionInput"], "completionInput");
       const resource = optionalResourceContext(args);
       return topolo.client.uploadActionBase64(
         actionId,
         contentBase64,
-        input ?? {},
+        input,
         {
           fileName,
           contentType,
-          completionInput: completionInput ?? {},
+          completionInput,
           confirm: args["confirm"] === true,
           ...resource ? { resource } : {}
         }
@@ -340,7 +348,8 @@ var TOOLS = [
       type: "object",
       properties: {
         actionId: { type: "string", minLength: 1 },
-        input: { type: "object", additionalProperties: true }
+        input: { type: "object", additionalProperties: true },
+        detail: { type: "boolean", description: "Include the full action contract. Defaults to a compact validation result." }
       },
       required: ["actionId"],
       additionalProperties: false
@@ -348,11 +357,9 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
       if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
-      const input = args["input"];
-      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new TopoloMcpPublicError("input must be an object.");
-      }
-      return topolo.client.validateActionInput(actionId, input ?? {});
+      const input = coerceObjectParam(args["input"], "input");
+      const result = await topolo.client.validateActionInput(actionId, input);
+      return args["detail"] === true ? result : compactActionValidation(result.action.actionId, result.validation);
     }
   },
   {
@@ -368,7 +375,8 @@ var TOOLS = [
         input: { type: "object", additionalProperties: true },
         resourceType: { type: "string", description: "Optional resource-scoping alias published in the app resource catalog (e.g. workspace, brand, merchant)." },
         resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." },
-        confirm: { type: "boolean", description: "Include confirmation in the plan without executing the action." }
+        confirm: { type: "boolean", description: "Include confirmation in the plan without executing the action." },
+        detail: { type: "boolean", description: "Include the full action contract. Defaults to the executable request and verification plan." }
       },
       required: ["actionId"],
       additionalProperties: false
@@ -376,19 +384,17 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
       if (!actionId) throw new TopoloMcpPublicError("actionId is required.");
-      const input = args["input"];
-      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
-        throw new TopoloMcpPublicError("input must be an object.");
-      }
+      const input = coerceObjectParam(args["input"], "input");
       const resource = optionalResourceContext(args);
-      return topolo.client.planAction(
+      const plan = await topolo.client.planAction(
         actionId,
-        input ?? {},
+        input,
         {
           confirm: args["confirm"] === true,
           ...resource ? { resource } : {}
         }
       );
+      return args["detail"] === true ? plan : compactActionPlan(plan);
     }
   },
   {
@@ -422,14 +428,18 @@ var TOOLS = [
     destructive: false,
     inputSchema: {
       type: "object",
-      properties: { service: { type: "string", minLength: 1 } },
+      properties: {
+        service: { type: "string", minLength: 1 },
+        detail: { type: "boolean", description: "Return full schemas and agent contracts. Defaults to compact capability guidance." }
+      },
       required: ["service"],
       additionalProperties: false
     },
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
       if (!service) throw new TopoloMcpPublicError("service is required.");
-      return topolo.client.searchActions({ service, limit: 100 });
+      const result = await topolo.client.searchActions({ service, limit: 100 });
+      return args["detail"] === true ? result : { actions: result.actions.map(compactActionCatalogEntry), page: result.page };
     }
   },
   {
@@ -560,7 +570,7 @@ var TOOLS = [
       },
       additionalProperties: false
     },
-    handler: async (_topolo, args) => {
+    handler: async (topolo, args) => {
       const application = args["application"];
       if (application === void 0) {
         return {
@@ -570,12 +580,8 @@ var TOOLS = [
           requirements: APPLICATION_REQUIREMENTS
         };
       }
-      if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
-        throw new TopoloMcpPublicError(
-          `Unknown application "${String(application)}". ${formatKnownValues(APPLICATION_IDS, "applications")}`
-        );
-      }
-      const app = APPLICATIONS[application];
+      const resolved = await resolveDirectoryApplication(topolo, application);
+      const app = resolved.application;
       return {
         version: APPLICATION_REQUIREMENTS_VERSION,
         application: app,
@@ -601,11 +607,15 @@ var TOOLS = [
           type: "string",
           enum: ["missing", "needs_review", "partial"],
           description: "Optional conformance gate. Returns conformanceGate.passed=false when findings at this severity or worse exist."
+        },
+        detail: {
+          type: "boolean",
+          description: "Include every finding and migration item. Defaults to per-app scores and a queue count."
         }
       },
       additionalProperties: false
     },
-    handler: async (_topolo, args) => {
+    handler: async (topolo, args) => {
       const application = args["application"];
       const failOn = args["failOn"];
       if (failOn !== void 0 && typeof failOn !== "string") {
@@ -614,16 +624,15 @@ var TOOLS = [
       const gate = failOn ? normalizeFailOn(failOn) : null;
       let report;
       if (application === void 0) {
-        report = auditAllApplicationRequirements();
-        return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
-      }
-      if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
-        throw new TopoloMcpPublicError(
-          `Unknown application "${String(application)}". ${formatKnownValues(APPLICATION_IDS, "applications")}`
-        );
+        const directory = await listApplicationDirectory(topolo.client);
+        report = auditApplicationEntries(directory.applications.map((app) => app.application));
+        const output2 = args["detail"] === true ? report : compactApplicationAudit(report);
+        return gate ? { ...output2, conformanceGate: evaluateApplicationAuditGate(report, gate) } : output2;
       }
-      report = auditAllApplicationRequirements([application]);
-      return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
+      const resolved = await resolveDirectoryApplication(topolo, application);
+      report = auditApplicationEntries([resolved.application]);
+      const output = args["detail"] === true ? report : compactApplicationAudit(report);
+      return gate ? { ...output, conformanceGate: evaluateApplicationAuditGate(report, gate) } : output;
     }
   },
   {
@@ -762,31 +771,19 @@ function statusesAtOrWorse(threshold) {
   return ["missing", "needs_review", "partial"];
 }
 function displayAppId(entry) {
-  for (const value of [entry.slug, entry.name, entry.appId]) {
-    if (typeof value !== "string" || !value.trim()) continue;
-    for (const candidate of appIdCandidates(value)) {
-      if (Object.prototype.hasOwnProperty.call(DEFAULT_APP_URLS, candidate)) {
-        return candidate;
-      }
-    }
-  }
-  return appIdCandidates(entry.slug || entry.appId)[0] || entry.appId;
-}
-function appIdCandidates(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);
+  return friendlyAppId(entry);
 }
-function formatKnownValues(values, label) {
-  const sorted = [...values].sort();
-  const preview = sorted.slice(0, 25).join(", ");
-  const suffix = sorted.length > 25 ? `, ... +${sorted.length - 25} more` : "";
-  return `Run discovery for the full ${label} list. Known snapshot sample: ${preview}${suffix}`;
+async function resolveDirectoryApplication(topolo, application) {
+  if (typeof application !== "string" || !application.trim()) {
+    throw new TopoloMcpPublicError("`application` must be a non-empty string.");
+  }
+  try {
+    return await resolveApplicationDirectoryEntry(topolo.client, application);
+  } catch (error) {
+    throw new TopoloMcpPublicError(
+      error instanceof Error ? error.message : `Unknown application "${application}".`
+    );
+  }
 }
 
 // src/dispatch.ts