@mixio-pro/kalaasetu-mcp 1.2.1 → 2.0.1-beta

package/src/tools/fal/generate.ts

@@ -1,19 +1,25 @@
 /**
  * Generate module for fal.ai MCP server.
- * Provides tools for generating content and managing queue operations with fal.ai models.
+ * Provides tools for generating content using fal.ai models with MCP progress streaming.
  */
 
 import { z } from "zod";
 import { safeToolExecute } from "../../utils/tool-wrapper";
+import { resolveEnhancer } from "../../utils/prompt-enhancer-presets";
 import {
   FAL_QUEUE_URL,
-  FAL_DIRECT_URL,
   AUTHENTICATED_TIMEOUT,
   getApiKey,
   loadFalConfig,
-  type FalPresetConfig,
 } from "./config";
 
+/**
+ * Helper to wait for a specified duration.
+ */
+async function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 /**
  * Make an authenticated request to fal.ai API.
  */
@@ -41,6 +47,12 @@ async function authenticatedRequest(
 
   if (!response.ok) {
     const errorText = await response.text();
+    if (response.status === 404) {
+      return {
+        status: "IN_PROGRESS_WAITING",
+        detail: "Request not yet available in queue.",
+      };
+    }
     throw new Error(`[${response.status}] API error: ${errorText}`);
   }
 
@@ -59,114 +71,388 @@ function sanitizeParameters(
 }
 
 /**
- * Unified generation tool using presets defined in configuration.
+ * Progress reporter interface for MCP context compatibility.
  */
+interface ProgressContext {
+  reportProgress?: (progress: {
+    progress: number;
+    total: number;
+  }) => Promise<void>;
+  streamContent?: (
+    content: { type: "text"; text: string } | { type: "text"; text: string }[]
+  ) => Promise<void>;
+  log?: {
+    info: (message: string, data?: any) => void;
+    debug: (message: string, data?: any) => void;
+  };
+}
+
 export const falGenerate = {
   name: "fal_generate",
   description:
-    "Generate content using a named preset and optional parameters. Use fal_list_presets to discover available intents and preset names.",
+    "The primary tool for generating AI content (images, videos, etc.) using fal.ai. " +
+    "This tool handles polling internally and streams progress updates to the client. " +
+    "If the generation takes too long (timeout or error), it returns a 'resume_id' that you can use to resume polling. " +
+    "Use 'fal_list_presets' to discover available intents and names. " +
+    "PREREQUISITE: If using local files as parameters, you MUST upload them first using 'fal_upload_file' and use the resulting CDN URL. " +
+    "ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS.",
   parameters: z.object({
     preset_name: z
       .string()
-      .describe("The name of the preset to use (e.g., 'cinematic_image')"),
+      .optional()
+      .describe(
+        "Required for new requests. The unique name of the generation preset (e.g., 'ltx_image_to_video'). Obtain this from 'fal_list_presets'."
+      ),
     parameters: z
       .record(z.string(), z.any())
       .optional()
-      .describe("Optional model-specific parameters to override defaults"),
-    queue: z
-      .boolean()
+      .describe(
+        "A dictionary of model-specific parameters (e.g., { 'prompt': '...', 'image_url': '...' }). " +
+          "These override the default values defined in the preset. " +
+          "NOTE: For image-to-video or video-to-video tasks, use 'fal_upload_file' first and pass the resulting CDN URL here."
+      ),
+    resume_id: z
+      .string()
       .optional()
-      .default(false)
       .describe(
-        "Whether to use the queuing system for long-running tasks. Default: false"
+        "If provided, the tool will resume polling for an existing request instead of starting a new one. " +
+          "Use the 'request_id' returned in an 'IN_PROGRESS' response or after a timeout error."
       ),
   }),
-  timeoutMs: 300000,
-  execute: async (args: {
-    preset_name: string;
-    parameters?: Record<string, any>;
-    queue?: boolean;
-  }) => {
+  timeoutMs: 600000, // 10 minutes max
+  execute: async (
+    args: {
+      preset_name?: string;
+      parameters?: Record<string, any>;
+      resume_id?: string;
+      auto_enhance?: boolean;
+    },
+    context?: ProgressContext
+  ) => {
     return safeToolExecute(async () => {
+      let statusUrl: string;
+      let responseUrl: string;
+      let requestId: string;
       const config = loadFalConfig();
-      const preset = config.presets.find(
-        (p) => p.presetName === args.preset_name
-      );
 
-      if (!preset) {
-        throw new Error(
-          `Preset '${args.preset_name}' not found. Use fal_list_presets to see available options.`
+      if (args.resume_id) {
+        // Check if resume_id is a full URL (new format) or legacy ID
+        if (args.resume_id.startsWith("http")) {
+          // NEW: resume_id IS the status/response URL
+          statusUrl = args.resume_id;
+          // Derive responseUrl by removing /status suffix if present
+          responseUrl = args.resume_id.replace(/\/status$/, "");
+          // Extract requestId from URL for logging
+          const urlParts = args.resume_id.split("/");
+          const lastPart = urlParts[urlParts.length - 1] || "";
+          requestId =
+            lastPart.replace("/status", "") ||
+            urlParts[urlParts.length - 2] ||
+            "unknown";
+          context?.log?.info(`Resuming with FAL URL: ${args.resume_id}`);
+        } else {
+          // LEGACY: Try to resolve model from preset_name or parse modelId::requestId
+          let modelIdFromPreset: string | undefined;
+          if (args.preset_name) {
+            const p = config.presets.find(
+              (x) => x.presetName === args.preset_name
+            );
+            if (p) {
+              modelIdFromPreset = p.modelId;
+              context?.log?.info(
+                `Using model from preset '${args.preset_name}': ${modelIdFromPreset}`
+              );
+            }
+          }
+
+          if (args.resume_id.includes("::")) {
+            const parts = args.resume_id.split("::");
+            const mId = parts[0];
+            const rId = parts[1] || "";
+
+            requestId = rId;
+            // Prefer ID from preset if available (explicit user intent), otherwise use ID from string
+            const effectiveModelId = modelIdFromPreset || mId;
+
+            statusUrl = `${FAL_QUEUE_URL}/${effectiveModelId}/requests/${rId}/status`;
+            responseUrl = `${FAL_QUEUE_URL}/${effectiveModelId}/requests/${rId}`;
+            context?.log?.info(
+              `Resuming polling for ${effectiveModelId} request: ${rId}`
+            );
+          } else {
+            // Legacy/Fallback for raw UUIDs
+            requestId = args.resume_id;
+
+            if (modelIdFromPreset) {
+              // Best case: User provided the preset name!
+              statusUrl = `${FAL_QUEUE_URL}/${modelIdFromPreset}/requests/${requestId}/status`;
+              responseUrl = `${FAL_QUEUE_URL}/${modelIdFromPreset}/requests/${requestId}`;
+              context?.log?.info(
+                `Resuming polling with explicit model: ${modelIdFromPreset}`
+              );
+            } else {
+              // Worst case: No preset, no model in ID. Try legacy generic URL
+              statusUrl = `${FAL_QUEUE_URL}/requests/${args.resume_id}/status`;
+              responseUrl = `${FAL_QUEUE_URL}/requests/${args.resume_id}`;
+
+              // Verify/Recovery: Check if generic URL works, if not try to guess model
+              // ... (Smart recovery logic below)
+            }
+
+            // Verify/Recovery: Check if generic URL works, if not try to guess model
+            try {
+              await authenticatedRequest(statusUrl, "GET");
+            } catch (e: any) {
+              if (`${e}`.includes("405") || `${e}`.includes("404")) {
+                context?.log?.info(
+                  "Generic status URL failed, attempting to recover model-specific URL..."
+                );
+                let found = false;
+                for (const p of config.presets) {
+                  const testUrl = `${FAL_QUEUE_URL}/${p.modelId}/requests/${requestId}/status`;
+                  try {
+                    await authenticatedRequest(testUrl, "GET");
+                    statusUrl = testUrl;
+                    responseUrl = `${FAL_QUEUE_URL}/${p.modelId}/requests/${requestId}`;
+                    context?.log?.info(
+                      `Recovered session using model: ${p.modelId}`
+                    );
+                    found = true;
+                    break;
+                  } catch (ignore) {}
+                }
+
+                if (!found) {
+                  context?.log?.info(
+                    "Could not recover session URL. Assuming generic URL (might fail)."
+                  );
+                }
+              }
+            }
+            context?.log?.info(
+              `Resuming polling for request: ${args.resume_id}`
+            );
+          }
+        } // Close the LEGACY else block (line 149)
+      } else {
+        if (!args.preset_name) {
+          throw new Error(
+            "preset_name is required when starting a new request."
+          );
+        }
+        // ... (config loading and preset finding code remains same, omitted for brevity but preserved in tool)
+        const preset = config.presets.find(
+          (p) => p.presetName === args.preset_name
         );
+
+        if (!preset) {
+          throw new Error(
+            `Preset '${args.preset_name}' not found. Use fal_list_presets to see available options.`
+          );
+        }
+
+        // ... (API key checking and Prompt Enhancement logic remains same)
+        try {
+          const apiKey = getApiKey();
+          if (context?.streamContent) {
+            await context.streamContent({
+              type: "text" as const,
+              text: `[FAL] ✓ API key found (${apiKey.slice(
+                0,
+                8
+              )}...). Using preset: ${args.preset_name} → model: ${
+                preset.modelId
+              }`,
+            });
+          }
+        } catch (keyError: any) {
+          // ...
+          throw keyError;
+        }
+
+        const mergedParams = {
+          ...(preset.defaultParams || {}),
+          ...(args.parameters || {}),
+        };
+
+        // ... (Prompt enhancement logic preserved)
+        // Copying simplified logic block for replacement context matches
+        const shouldEnhance = args.auto_enhance !== false;
+        if (shouldEnhance && preset.promptEnhancer && mergedParams.prompt) {
+          const enhancerName =
+            typeof preset.promptEnhancer === "string"
+              ? preset.promptEnhancer
+              : null;
+          if (enhancerName === "ltx2") {
+            // ... (LLM logic)
+            const { enhancePromptWithLLM, isLLMEnhancerAvailable } =
+              await import("../../utils/llm-prompt-enhancer");
+            if (isLLMEnhancerAvailable()) {
+              // ...
+              try {
+                mergedParams.prompt = await enhancePromptWithLLM(
+                  mergedParams.prompt,
+                  "ltx2"
+                );
+                // ...
+              } catch (err) {}
+            }
+          } else {
+            // ...
+            const enhancer = resolveEnhancer(preset.promptEnhancer);
+            if (enhancer.hasTransformations()) {
+              mergedParams.prompt = enhancer.enhance(mergedParams.prompt);
+              const negatives = enhancer.getNegativeElements();
+              if (negatives && !mergedParams.negative_prompt)
+                mergedParams.negative_prompt = negatives;
+            }
+          }
+        }
+
+        const sanitizedParams = sanitizeParameters(mergedParams);
+        const url = `${FAL_QUEUE_URL}/${preset.modelId}`;
+
+        if (context?.streamContent) {
+          await context.streamContent({
+            type: "text" as const,
+            text: `[FAL] Submitting generation request to ${preset.modelId}...`,
+          });
+        }
+
+        const queueRes = await authenticatedRequest(
+          url,
+          "POST",
+          sanitizedParams
+        );
+
+        if (!queueRes.request_id && !queueRes.status_url) {
+          return JSON.stringify(queueRes);
+        }
+
+        requestId =
+          queueRes.request_id || queueRes.status_url?.split("/").pop() || "";
+
+        if (!requestId) {
+          throw new Error("Could not extract request ID from response");
+        }
+
+        // Prefer explicit status/response URLs from API if available
+        statusUrl =
+          queueRes.status_url ||
+          `${FAL_QUEUE_URL}/${preset.modelId}/requests/${requestId}/status`;
+        responseUrl =
+          queueRes.response_url ||
+          `${FAL_QUEUE_URL}/${preset.modelId}/requests/${requestId}`;
+
+        // Stream the FULL status URL for reliable resuming
+        if (context?.streamContent) {
+          await context.streamContent({
+            type: "text" as const,
+            text: `[FAL] Generation started. resume_id: ${statusUrl} (use this URL to check status)`,
+          });
+        }
       }
 
-      // Merge defaults from config with runtime overrides
-      const mergedParams = {
-        ...(preset.defaultParams || {}),
-        ...(args.parameters || {}),
-      };
+      // Stream message for resume calls
+      if (args.resume_id && context?.streamContent) {
+        await context.streamContent({
+          type: "text" as const,
+          text: `[FAL] Resuming status check for job: ${requestId}`,
+        });
+      }
 
-      const sanitizedParams = sanitizeParameters(mergedParams);
+      const startTime = Date.now();
+      const MAX_POLL_TIME = 600000; // 10 minutes
+      let pollCount = 0;
+      const POLL_INTERVAL = 3000;
 
-      const baseUrl = args.queue ? FAL_QUEUE_URL : FAL_DIRECT_URL;
-      const url = `${baseUrl}/${preset.modelId}`;
+      while (Date.now() - startTime < MAX_POLL_TIME) {
+        pollCount++;
+        let res;
+        try {
+          res = await authenticatedRequest(statusUrl, "GET");
+        } catch (e: any) {
+          if (`${e}`.includes("405")) {
+            context?.log?.info(
+              `Status check 405 on ${statusUrl}, trying fallback to responseUrl...`
+            );
+            // Try checking the request root URL instead of /status
+            res = await authenticatedRequest(responseUrl, "GET");
+            // If successful, update statusUrl to match for future polls
+            statusUrl = responseUrl;
+          } else {
+            throw e;
+          }
+        }
 
-      console.error(
-        `[fal_generate] Using preset '${args.preset_name}' on model ${preset.modelId}...`
-      );
+        // Update URLs if the polling response provides better ones
+        // This fixes 405 errors if our constructed URL was slightly off
+        if (res.status_url) statusUrl = res.status_url;
+        if (res.response_url) responseUrl = res.response_url;
 
-      const result = await authenticatedRequest(url, "POST", sanitizedParams);
+        // Stream progress to MCP client
+        if (context?.reportProgress) {
+          // ... (progress logic)
+          const queuePosition = res.queue_position ?? 0;
+          const elapsed = Date.now() - startTime;
+          const progressPercent = Math.min(
+            Math.round((elapsed / MAX_POLL_TIME) * 100),
+            99
+          );
+          await context.reportProgress({
+            progress: progressPercent,
+            total: 100,
+          });
+        }
 
-      return JSON.stringify(result);
-    }, "fal_generate");
-  },
-};
+        if (context?.streamContent && pollCount % 5 === 0) {
+          // ...
+          await context.streamContent({
+            type: "text" as const,
+            text: `[FAL] Still processing... (${Math.round(
+              (Date.now() - startTime) / 1000
+            )}s elapsed, status: ${res.status})`,
+          });
+        }
 
-/**
- * Get the result of a queued request.
- */
-export const falGetResult = {
-  name: "fal_get_result",
-  description: "Get the result of a queued fal.ai request.",
-  parameters: z.object({
-    url: z.string().describe("The response_url from a queued request"),
-  }),
-  timeoutMs: 300000,
-  execute: async (args: { url: string }) => {
-    const result = await authenticatedRequest(args.url, "GET");
-    return JSON.stringify(result);
-  },
-};
+        if (res.status === "COMPLETED") {
+          if (context?.reportProgress) {
+            await context.reportProgress({ progress: 100, total: 100 });
+          }
+          // responseUrl is now guaranteed to be correct/fresh from polling
+          const finalResult = await authenticatedRequest(responseUrl, "GET");
+          return JSON.stringify(finalResult);
+        }
 
-/**
- * Check the status of a queued request.
- */
-export const falGetStatus = {
-  name: "fal_get_status",
-  description: "Check the status of a queued fal.ai request.",
-  parameters: z.object({
-    url: z.string().describe("The status_url from a queued request"),
-  }),
-  timeoutMs: 300000,
-  execute: async (args: { url: string }) => {
-    const result = await authenticatedRequest(args.url, "GET");
-    return JSON.stringify(result);
-  },
-};
+        if (res.status === "FAILED") {
+          throw new Error(
+            `Generation failed: ${JSON.stringify(res.error || res)}`
+          );
+        }
 
-/**
- * Cancel a queued request.
- */
-export const falCancelRequest = {
-  name: "fal_cancel_request",
-  description: "Cancel a queued fal.ai request.",
-  parameters: z.object({
-    url: z.string().describe("The cancel_url from a queued request"),
-  }),
-  timeoutMs: 300000,
-  execute: async (args: { url: string }) => {
-    return safeToolExecute(async () => {
-      const result = await authenticatedRequest(args.url, "PUT");
-      return JSON.stringify(result);
-    }, "fal_cancel_request");
+        await wait(POLL_INTERVAL);
+      }
+
+      // Timeout - return composite resume_id
+      // We need to know modelId here. If we started new, we have 'preset'
+      // If we resumed, we parsed 'mId' or used raw.
+      const currentModelId =
+        args.resume_id && args.resume_id.includes("::")
+          ? args.resume_id.split("::")[0]
+          : args.preset_name
+          ? config.presets.find((p) => p.presetName === args.preset_name)
+              ?.modelId
+          : "unknown";
+
+      return JSON.stringify({
+        status: "IN_PROGRESS",
+        request_id: requestId,
+        resume_id: statusUrl, // Use the FULL URL for reliable resume
+        status_url: statusUrl,
+        response_url: responseUrl,
+        message:
+          "The generation is still in progress. Call this tool again with resume_id (the URL) to continue polling.",
+      });
+    }, "fal_generate");
   },
 };

package/src/tools/fal/index.ts

@@ -3,12 +3,7 @@
  * Export all fal.ai tools for registration with the MCP server.
  */
 
-export { falListPresets, falGetPresetDetails, falGetConfig } from "./models";
-export {
-  falGenerate,
-  falGetResult,
-  falGetStatus,
-  falCancelRequest,
-} from "./generate";
+export { falListPresets, falGetPresetDetails } from "./models";
+export { falGenerate } from "./generate";
 export { falUploadFile } from "./storage";
 export { SERVER_NAME, SERVER_DESCRIPTION, SERVER_VERSION } from "./config";