@topolo/mcp 0.10.1 → 0.10.3

package/dist/dispatch.d.ts

@@ -75,6 +75,11 @@ type ToolDispatchResult = {
     reason: ToolDispatchFailureReason;
     durationMs: number;
     requiredScopes?: string[];
+    code?: string;
+    status?: number;
+    requestId?: string;
+    details?: unknown;
+    hint?: string;
 };
 interface ToolAdvertisement {
     name: string;

package/dist/dispatch.js

@@ -1,5 +1,11 @@
 // src/dispatch.ts
-import { TopoloAuthError, TopoloPermissionError } from "@topolo/sdk";
+import {
+  TopoloAuthError,
+  TopoloHttpError,
+  TopoloPermissionError,
+  publicTopoloErrorMessage,
+  topoloErrorHint
+} from "@topolo/sdk";
 
 // src/tools.ts
 import {
@@ -8,6 +14,7 @@ import {
   auditApplicationEntries,
   applicationRequirementScopes,
   compactActionCatalogEntry,
+  compactActionPreparation,
   compactActionPlan,
   compactActionValidation,
   compactApplicationAudit,
@@ -82,6 +89,17 @@ function optionalResourceContext(args) {
   }
   return { resourceType, resourceId };
 }
+function summarizeActionCapabilities(service, actions) {
+  return {
+    service,
+    total: actions.length,
+    readOnly: actions.filter((action) => action.readOnly).length,
+    mutating: actions.filter((action) => !action.readOnly).length,
+    destructive: actions.filter((action) => action.destructive).length,
+    confirmationRequired: actions.filter((action) => action.requiresConfirmation).length,
+    resourceTypes: [...new Set(actions.map((action) => action.agentContract?.resource?.kind).filter(Boolean))].sort()
+  };
+}
 function coerceObjectParam(value, name) {
   let candidate = value;
   if (typeof candidate === "string" && candidate.trim().startsWith("{")) {
@@ -362,6 +380,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",
@@ -423,13 +473,14 @@ var TOOLS = [
   {
     name: "topolo_discover_capabilities",
     title: "Discover one Topolo application capability contract",
-    description: "Lists every action published by one application \u2014 its full capability contract, straight from the registry-canonical catalog. Use the actionService value returned by topolo_search_applications as service. Follow page.nextCursor via topolo_search_actions when the contract exceeds one page.",
+    description: "Lists every action published by one application \u2014 its full capability contract, straight from the registry-canonical catalog. Use the actionService value returned by topolo_search_applications as service.",
     requiredScopes: [],
     destructive: false,
     inputSchema: {
       type: "object",
       properties: {
         service: { type: "string", minLength: 1 },
+        summary: { type: "boolean", description: "Return compact counts without action rows." },
         detail: { type: "boolean", description: "Return full schemas and agent contracts. Defaults to compact capability guidance." }
       },
       required: ["service"],
@@ -438,8 +489,26 @@ var TOOLS = [
     handler: async (topolo, args) => {
       const service = typeof args["service"] === "string" ? args["service"].trim() : "";
       if (!service) throw new TopoloMcpPublicError("service is required.");
-      const result = await topolo.client.searchActions({ service, limit: 100 });
-      return args["detail"] === true ? result : { actions: result.actions.map(compactActionCatalogEntry), page: result.page };
+      if (args["summary"] === true && args["detail"] === true) {
+        throw new TopoloMcpPublicError("summary cannot be combined with detail.");
+      }
+      const actions = [];
+      const seenCursors = /* @__PURE__ */ new Set();
+      let cursor;
+      for (; ; ) {
+        const page = await topolo.client.searchActions({ service, limit: 100, ...cursor ? { cursor } : {} });
+        actions.push(...page.actions);
+        if (!page.page.hasMore) break;
+        const nextCursor = page.page.nextCursor?.trim();
+        if (!nextCursor || seenCursors.has(nextCursor)) {
+          throw new TopoloMcpPublicError("Capability discovery returned an invalid continuation cursor.");
+        }
+        seenCursors.add(nextCursor);
+        cursor = nextCursor;
+      }
+      if (args["summary"] === true) return summarizeActionCapabilities(service, actions);
+      const result = { actions, page: { nextCursor: null, hasMore: false } };
+      return args["detail"] === true ? result : { actions: actions.map(compactActionCatalogEntry), page: result.page };
     }
   },
   {
@@ -837,8 +906,13 @@ async function dispatchTopoloTool(input) {
       return {
         ok: false,
         reason: "permission",
-        error: `Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`,
+        error: publicTopoloErrorMessage(err),
         requiredScopes: err.required,
+        code: err.code,
+        status: err.status,
+        requestId: err.requestId,
+        details: err.details,
+        hint: topoloErrorHint(err),
         durationMs: Date.now() - started
       };
     }
@@ -847,6 +921,24 @@ async function dispatchTopoloTool(input) {
         ok: false,
         reason: "auth",
         error: "Authentication failed.",
+        code: err.code,
+        status: err.status,
+        requestId: err.requestId,
+        details: err.details,
+        hint: topoloErrorHint(err),
+        durationMs: Date.now() - started
+      };
+    }
+    if (err instanceof TopoloHttpError) {
+      return {
+        ok: false,
+        reason: "handler",
+        error: publicTopoloErrorMessage(err),
+        code: err.code,
+        status: err.status,
+        requestId: err.requestId,
+        details: err.details,
+        hint: topoloErrorHint(err),
         durationMs: Date.now() - started
       };
     }

package/dist/http.d.ts

@@ -1,5 +1,5 @@
+import { TopoloRuntimeEnvironment, TopoloCredential, Topolo } from '@topolo/sdk';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
-import { TopoloCredential, Topolo } from '@topolo/sdk';
 
 /**
  * Hosted, multi-tenant MCP Streamable HTTP transport for the Topolo platform.
@@ -18,9 +18,11 @@ import { TopoloCredential, Topolo } from '@topolo/sdk';
  * Mcp-Session-Id continuity, GET SSE stream, DELETE to terminate) over pure
  * Web-Standard Request/Response — so it runs unchanged in a Cloudflare Worker.
  */
-interface TopoloMcpHttpOptions {
+interface TopoloMcpHttpInternalOptions {
     /** Path the MCP endpoint is mounted at. Defaults to '/mcp'. */
     path?: string;
+    /** Effective Topolo environment. Defaults to production and is always surfaced to the MCP client. */
+    environment?: TopoloRuntimeEnvironment;
     /** Per-service URL overrides (e.g. staging). Passed through to createTopolo. */
     serviceUrls?: Record<string, string>;
     /** Per-service TopoloAuth app-id overrides. Passed through to createTopolo. */
@@ -52,12 +54,33 @@ interface McpSession {
  *   const handler = createTopoloMcpHttpHandler();
  *   export default { fetch: handler.fetch };
  */
-declare function createTopoloMcpHttpHandler(options?: TopoloMcpHttpOptions): {
+declare function createTopoloMcpHttpHandlerInternal(options?: TopoloMcpHttpInternalOptions): {
     /** Cloudflare Worker / fetch-compatible entrypoint. */
     fetch: (request: Request) => Promise<Response>;
     /** Exposed for tests/introspection. */
     sessions: Map<string, McpSession>;
 };
+type TopoloMcpHttpHandlerInternal = ReturnType<typeof createTopoloMcpHttpHandlerInternal>;
+
+interface TopoloMcpHttpOptions {
+    /** Path the MCP endpoint is mounted at. Defaults to '/mcp'. */
+    path?: string;
+    /** Effective Topolo environment. Defaults to production and is always surfaced to the MCP client. */
+    environment?: TopoloRuntimeEnvironment;
+    /** Per-service URL overrides (e.g. staging). Passed through to createTopolo. */
+    serviceUrls?: Record<string, string>;
+    /** Per-service TopoloAuth app-id overrides. Passed through to createTopolo. */
+    appIds?: Record<string, string>;
+    /** Human-readable agent label for audit logs (forwarded to the SDK). */
+    agentName?: string;
+    /** Validated network transport for the SDK client. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Create the public hosted MCP handler. The SDK client is always constructed
+ * here from the validated effective environment and per-request credential.
+ */
+declare function createTopoloMcpHttpHandler(options?: TopoloMcpHttpOptions): TopoloMcpHttpHandlerInternal;
 type TopoloMcpHttpHandler = ReturnType<typeof createTopoloMcpHttpHandler>;
 
 export { type TopoloMcpHttpHandler, type TopoloMcpHttpOptions, createTopoloMcpHttpHandler };