@topolo/mcp 0.10.2 → 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,
@@ -373,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",
@@ -867,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
       };
     }
@@ -877,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 };