Execute Batch Actions

Instructions

Implementation Reference

• src/tools/actions.ts:39-44 (handler)

  The handler function for dual_batch_actions tool. Makes a POST request to 'ebus/actions/batch' endpoint with the actions array, executes multiple actions atomically (all succeed or all fail), and returns a success message with the count of actions executed. Handles errors via try-catch.

  }, async (params) => {
    try {
      const res = await makeApiRequest<Record<string, unknown>>("ebus/actions/batch", "POST", params);
      return textResult(`Batch of ${params.actions.length} actions executed.\n${JSON.stringify(res, null, 2)}`);
    } catch (e) { return errorResult(handleApiError(e)); }
  });

• src/tools/actions.ts:27-38 (schema)

  Tool registration and input schema for dual_batch_actions. Defines the tool metadata (title, description, annotations) and inputSchema with an array of actions (1-50 items), each containing action_type, object_id, and optional payload.

    server.registerTool("dual_batch_actions", {
      title: "Execute Batch Actions",
      description: `Execute multiple actions atomically in a single batch. All actions succeed or all fail.
  Useful for complex operations like: mint + transfer + configure in one transaction.`,
      inputSchema: {
        actions: z.array(z.object({
          action_type: z.string().describe("Action type name"),
          object_id: z.string().describe("Target object ID"),
          payload: z.record(z.unknown()).optional().describe("Action payload"),
        })).min(1).max(50).describe("Array of actions to execute atomically (1-50)"),
      },
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },

• src/services/api-client.ts:40-62 (helper)

  The makeApiRequest helper function that performs the actual HTTP request. Constructs the Axios config with proper headers (including auth), method, URL, data, and params. Returns the response data from the API.

  export async function makeApiRequest<T>(
    endpoint: string,
    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" = "GET",
    data?: unknown,
    params?: Record<string, unknown>,
    options?: { timeout?: number; multipart?: boolean }
  ): Promise<T> {
    const config: AxiosRequestConfig = {
      method,
      url: `${API_BASE_URL}/${endpoint}`,
      headers: getAuthHeaders(),
      timeout: options?.timeout ?? 30000,
    };
  
    if (data !== undefined) config.data = data;
    if (params) config.params = params;
    if (options?.multipart) {
      config.headers = { ...config.headers, "Content-Type": "multipart/form-data" };
    }
  
    const response = await axios(config);
    return response.data as T;
  }

• src/services/formatters.ts:39-46 (helper)

  Helper functions for formatting tool responses. textResult creates a standard success response with text content, while errorResult creates an error response with isError flag set to true.

  export function textResult(text: string) {
    return { content: [{ type: "text" as const, text }] };
  }
  
  /** Standard error content response */
  export function errorResult(text: string) {
    return { content: [{ type: "text" as const, text }], isError: true as const };
  }

• src/services/api-client.ts:65-98 (helper)

  The handleApiError helper function that formats API errors into actionable user-friendly messages. Handles various HTTP status codes (400, 401, 403, 404, 409, 422, 429) and network errors with specific guidance.

  export function handleApiError(error: unknown): string {
    if (axios.isAxiosError(error)) {
      const axiosErr = error as AxiosError<{ error?: { message?: string }; message?: string }>;
      if (axiosErr.response) {
        const status = axiosErr.response.status;
        const body = axiosErr.response.data;
        const msg = body?.error?.message || body?.message || "";
  
        switch (status) {
          case 400:
            return `Error: Bad request. ${msg || "Check your parameters and try again."}`;
          case 401:
            return "Error: Authentication required. Use dual_login or set DUAL_ACCESS_TOKEN / DUAL_API_KEY environment variable.";
          case 403:
            return `Error: Permission denied. ${msg || "You don't have access to this resource."}`;
          case 404:
            return `Error: Resource not found. ${msg || "Check the ID is correct."}`;
          case 409:
            return `Error: Conflict. ${msg || "Resource already exists or state conflict."}`;
          case 422:
            return `Error: Validation failed. ${msg || "Check your input data."}`;
          case 429:
            return "Error: Rate limit exceeded. Wait a moment before making more requests.";
          default:
            return `Error: API request failed (${status}). ${msg}`;
        }
      } else if (axiosErr.code === "ECONNABORTED") {
        return "Error: Request timed out. The DUAL API may be slow — try again.";
      } else if (axiosErr.code === "ECONNREFUSED") {
        return "Error: Cannot reach DUAL API. Check your DUAL_API_URL or network connection.";
      }
    }
    return `Error: ${error instanceof Error ? error.message : String(error)}`;
  }