@mixio-pro/kalaasetu-mcp 2.3.27 → 2.3.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixio-pro/kalaasetu-mcp",
-  "version": "2.3.27",
+  "version": "2.3.28",
   "description": "A powerful Model Context Protocol server providing AI tools for content generation and analysis",
   "type": "module",
   "module": "src/index.ts",

package/src/tools/fal/dynamic-tools.ts

@@ -126,13 +126,14 @@ function buildZodSchema(
   // Convert to Zod using Zod 4's fromJSONSchema (experimental)
   let zodSchema = (z as any).fromJSONSchema(jsonSchema) as z.ZodObject<any>;
 
-  // Always add resume_endpoint for resumable operations
+  // Always add internal parameters (output_path, resume_endpoint)
   zodSchema = zodSchema.extend({
     output_path: z
       .string()
       .optional()
       .describe(
-        "Optional local path/filename to save the final generated asset when status is checked via get_generation_status.",
+        "Optional local path/filename to save the generated file (e.g., 'path/to/image.png'). " +
+          "When status is checked via get_generation_status, the file will be saved to this location.",
       ),
     resume_endpoint: z
       .string()
@@ -177,41 +178,31 @@ export function createToolFromPreset(preset: FalPresetConfig) {
 
           // Handle resume flow
           if (args.resume_endpoint) {
-            const resumeParts = args.resume_endpoint.split("||");
-            const maybeTracking = resumeParts[resumeParts.length - 1];
-            const decodedTracking =
-              maybeTracking &&
-              !maybeTracking.startsWith("http") &&
-              !maybeTracking.includes("/")
-                ? (() => {
-                    try {
-                      return decodeTrackingContext(maybeTracking);
-                    } catch {
-                      return null;
-                    }
-                  })()
-                : null;
-
-            const resumeEndpointWithoutTracking =
-              decodedTracking?.toolName && resumeParts.length > 1
-                ? resumeParts.slice(0, -1).join("||")
-                : args.resume_endpoint;
-
-            if (resumeEndpointWithoutTracking.startsWith("http")) {
-              statusUrl = resumeEndpointWithoutTracking;
-              responseUrl = resumeEndpointWithoutTracking.replace(/\/status$/, "");
-              const urlParts = resumeEndpointWithoutTracking.split("/");
+            const parts = args.resume_endpoint.split("||");
+            statusUrl = parts[0];
+            
+            // Extract tracking context and output_path if present in composite endpoint
+            for (let i = 1; i < parts.length; i++) {
+              const part = parts[i];
+              if (part && (part.includes("/") || part.includes("\\")) && !args.output_path) {
+                args.output_path = part;
+              }
+            }
+
+            if (statusUrl.startsWith("http")) {
+              responseUrl = statusUrl.replace(/\/status$/, "");
+              const urlParts = statusUrl.split("/");
               const lastPart = urlParts[urlParts.length - 1] || "";
               requestId =
                 lastPart.replace("/status", "") ||
                 urlParts[urlParts.length - 2] ||
                 "unknown";
               context?.log?.info(
-                `Resuming with FAL URL: ${resumeEndpointWithoutTracking}`,
+                `Resuming with FAL URL: ${statusUrl} (Job ID: ${requestId})`,
               );
             } else {
               // Legacy UUID format - reconstruct URL
-              requestId = resumeEndpointWithoutTracking;
+              requestId = statusUrl;
               statusUrl = `${FAL_QUEUE_URL}/${preset.modelId}/requests/${requestId}/status`;
               responseUrl = `${FAL_QUEUE_URL}/${preset.modelId}/requests/${requestId}`;
               context?.log?.info(
@@ -404,7 +395,22 @@ export function createToolFromPreset(preset: FalPresetConfig) {
                 responseUrl,
                 "GET",
               );
-              return JSON.stringify(sanitizeResponse(finalResult));
+              
+              // Handle saving to output_path if provided
+              const sanitizedResult = sanitizeResponse(finalResult);
+              if (args.output_path) {
+                try {
+                  const { saveFalResult } = await import("../../utils/fal-save");
+                  const savedFiles = await saveFalResult(finalResult, args.output_path);
+                  if (savedFiles.length > 0) {
+                    (sanitizedResult as any).saved_files = savedFiles;
+                  }
+                } catch (err: any) {
+                  context?.log?.info(`Failed to save files to ${args.output_path}: ${err.message}`);
+                }
+              }
+
+              return JSON.stringify(sanitizedResult);
             }
 
             if (res.status === "FAILED") {
@@ -416,15 +422,22 @@ export function createToolFromPreset(preset: FalPresetConfig) {
             await wait(POLL_INTERVAL);
           }
 
-          // Timeout - return resume_endpoint
+          // Timeout - return composite resume_endpoint
+          const trackingPiece = encodeTrackingContext({
+            toolName: toolName,
+            toolArgs: extractPrimitiveArgs(args),
+            requestId: (context as any)?.requestId,
+          });
+          
           return JSON.stringify({
             status: "IN_PROGRESS",
             request_id: requestId,
+            // Encode tracking context and output_path so get-status can issue async refunds/saves
             resume_endpoint: `${statusUrl}||${encodeTrackingContext({
               toolName,
               toolArgs: extractPrimitiveArgs(args),
               requestId: (context as any)?.requestId,
-            })}`,
+            })}||${args.output_path || ""}`,
             status_url: statusUrl,
             response_url: responseUrl,
             message:

package/src/tools/fal/generate.ts

@@ -113,6 +113,12 @@ export const falGenerate = {
           "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.",
       ),
+    output_path: z
+      .string()
+      .optional()
+      .describe(
+        "Local path to save the generated file (e.g., 'path/to/image.png')",
+      ),
     resume_endpoint: z
       .string()
       .optional()
@@ -127,32 +133,42 @@ export const falGenerate = {
       preset_name?: string;
       parameters?: Record<string, any>;
       resume_endpoint?: string;
+      output_path?: string;
     },
     context?: ProgressContext,
   ) => {
     return safeToolExecute(
       async () => {
-        let statusUrl: string;
-        let responseUrl: string;
-        let requestId: string;
+        let statusUrl: string = "";
+        let responseUrl: string = "";
+        let requestId: string = "";
         const config = loadFalConfig();
 
         if (args.resume_endpoint) {
           // Check if resume_endpoint is a full URL (new format) or legacy ID
           if (args.resume_endpoint.startsWith("http")) {
-            // NEW: resume_endpoint IS the status/response URL
-            statusUrl = args.resume_endpoint;
+            // NEW: resume_endpoint IS the status/response URL (possibly composite with extra metadata)
+            if (args.resume_endpoint.includes("||")) {
+              const parts = args.resume_endpoint.split("||");
+              statusUrl = parts[0] ?? "";
+              // Extract output_path if present in composite endpoint
+              if (parts.length >= 3 && !args.output_path) {
+                args.output_path = parts[2];
+              }
+            } else {
+              statusUrl = args.resume_endpoint;
+            }
             // Derive responseUrl by removing /status suffix if present
-            responseUrl = args.resume_endpoint.replace(/\/status$/, "");
+            responseUrl = statusUrl.replace(/\/status$/, "");
             // Extract requestId from URL for logging
-            const urlParts = args.resume_endpoint.split("/");
+            const urlParts = statusUrl.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_endpoint}`,
+              `Resuming with FAL URL: ${statusUrl} (Job ID: ${requestId})`,
             );
           } else {
             // LEGACY: Try to resolve model from preset_name or parse modelId::requestId
@@ -233,9 +249,7 @@ export const falGenerate = {
                   }
                 }
               }
-              context?.log?.info(
-                `Resuming polling for request: ${args.resume_endpoint}`,
-              );
+              context?.log?.info(`Resuming polling for request: ${statusUrl}`);
             }
           } // Close the LEGACY else block (line 149)
         } else {
@@ -391,6 +405,25 @@ export const falGenerate = {
             }
             // responseUrl is now guaranteed to be correct/fresh from polling
             const finalResult = await authenticatedRequest(responseUrl, "GET");
+
+            // Handle saving to output_path if provided
+            if (args.output_path) {
+              try {
+                const { saveFalResult } = await import("../../utils/fal-save");
+                const savedFiles = await saveFalResult(
+                  finalResult,
+                  args.output_path,
+                );
+                if (savedFiles.length > 0) {
+                  (finalResult as any).saved_files = savedFiles;
+                }
+              } catch (err: any) {
+                context?.log?.info(
+                  `Failed to save files to ${args.output_path}: ${err.message}`,
+                );
+              }
+            }
+
             return JSON.stringify(finalResult);
           }
 
@@ -430,12 +463,12 @@ export const falGenerate = {
         return JSON.stringify({
           status: "IN_PROGRESS",
           request_id: requestId,
-          // Encode tracking context so get-status can issue async refunds
+          // Encode tracking context and output_path so get-status can issue async refunds/saves
           resume_endpoint: `${statusUrl}||${encodeTrackingContext({
             toolName: "fal_generate",
             toolArgs: extractPrimitiveArgs(args),
             requestId: (context as any)?.requestId,
-          })}`,
+          })}||${args.output_path || ""}`,
           status_url: statusUrl,
           response_url: responseUrl,
           message:

package/src/tools/get-status.ts

@@ -314,9 +314,13 @@ export const getGenerationStatus = {
       .string()
       .describe(
         "The resume_endpoint returned by the original generation tool. " +
-          "For FAL: This is a full URL (starts with 'https://queue.fal.run/...'). " +
+          "For FAL: This is a full URL (starts with 'https://queue.fal.run/...') but may include extra metadata via '||' delimiters. " +
           "For Vertex AI: This is typically the composite string 'fetchUrl||operationName||outputPath' with optional tracking context appended.",
       ),
+    output_path: z
+      .string()
+      .optional()
+      .describe("Optional override for the local path to save the generated file."),
     source: z
       .enum(["fal", "vertex", "auto"])
       .optional()
@@ -330,6 +334,7 @@ export const getGenerationStatus = {
     args: {
       resume_endpoint: string;
       source?: "fal" | "vertex" | "auto";
+      output_path?: string;
     },
     context?: any,
   ) => {
@@ -339,34 +344,59 @@ export const getGenerationStatus = {
         const project_id = "mixio-pro";
         const location_id = "us-central1";
 
-        // 1. Decode generic tracking context if present
+        // 1. Decode generic tracking context and extra metadata if present
         let trackingContext: any = null;
         let originalEndpoint = resume_endpoint;
+        let outputPath = args.output_path;
+
         if (resume_endpoint.includes("||")) {
           const parts = resume_endpoint.split("||");
-          // If the last part might be base64 JSON
-          const lastPart = parts[parts.length - 1];
-          if (
-            lastPart &&
-            !lastPart.startsWith("http") &&
-            !lastPart.includes("/") &&
-            !lastPart.includes("mixio-pro") // Ensure it doesn't look like an operation path or URL
-          ) {
-            try {
-              const { decodeTrackingContext } =
-                await import("../utils/endpoint-encoder");
-              trackingContext = decodeTrackingContext(lastPart);
-              if (trackingContext?.toolName) {
-                // Remove the tracking piece from the endpoint we pass to handlers
-                originalEndpoint = parts.slice(0, -1).join("||");
-                // For FAL, the endpoint is just the URL (first part).
-                // For Vertex, it's the `fetchUrl||operationName||outputPath`.
-                // For safety, let's keep the remaining parts together.
-              } else {
-                trackingContext = null;
-                originalEndpoint = resume_endpoint;
+          
+          // For FAL jobs starting with https://
+          if (parts?.[0]?.startsWith("https://")) {
+            originalEndpoint = parts[0];
+            // Part 1 is tracking context (base64)
+            if (parts.length >= 2 && parts[1]) {
+              try {
+                const { decodeTrackingContext } = await import("../utils/endpoint-encoder");
+                trackingContext = decodeTrackingContext(parts[1]);
+                // Try to extract output_path from tracking context if not explicitly provided
+                if (!outputPath) {
+                  outputPath = extractOutputPathFromTrackingContext(trackingContext);
+                }
+              } catch (err) {}
+            }
+            // Part 2 is output_path in our new URL||TRACKING||PATH format
+            if (parts.length >= 3 && parts[2] && !outputPath) {
+              outputPath = parts[2];
+            }
+          } else {
+            // Vertex logic (legacy/other)
+            const lastPart = parts[parts.length - 1];
+            if (
+              lastPart &&
+              !lastPart.startsWith("http") &&
+              !lastPart.includes("/") &&
+              !lastPart.includes("mixio-pro") // Ensure it doesn't look like an operation path or URL
+            ) {
+              try {
+                const { decodeTrackingContext } =
+                  await import("../utils/endpoint-encoder");
+                trackingContext = decodeTrackingContext(lastPart);
+                if (trackingContext?.toolName) {
+                  // Remove the tracking piece from the endpoint we pass to handlers
+                  originalEndpoint = parts.slice(0, -1).join("||");
+                }
+              } catch (err) {}
+            }
+            
+            // For Vertex, if outputPath is not explicitly provided, it might be in the 3rd part of originalEndpoint
+            if (!outputPath) {
+              const vertexParts = originalEndpoint.split("||");
+              if (vertexParts.length >= 3) {
+                outputPath = vertexParts[2];
               }
-            } catch (err) {}
+            }
           }
         }
 
@@ -386,31 +416,39 @@ export const getGenerationStatus = {
         let result: any;
 
         if (detectedSource === "fal") {
-          const falStatusResult = await checkFalStatus(originalEndpoint);
-          const falStatus = falStatusResult?.status;
-
-          if (falStatus === "COMPLETED") {
-            const falResultUrl = getFalResultUrl(originalEndpoint);
-            const falFinalResult = await fetchFalResult(falResultUrl);
-            const falOutputPath = extractOutputPathFromTrackingContext(trackingContext);
-            const { savedVideos, savedImages } = await saveFalUrls(
-              falFinalResult,
-              falOutputPath,
-            );
-
-            if (savedVideos.length > 0) {
-              falFinalResult.saved_videos = savedVideos;
-            }
-            if (savedImages.length > 0) {
-              falFinalResult.saved_images = savedImages;
+          result = await checkFalStatus(originalEndpoint);
+          
+          if (result.status === "COMPLETED") {
+            const falResultUrl = result.response_url || originalEndpoint.replace(/\/status$/, "");
+            const finalResult = await fetchFalResult(falResultUrl);
+            
+            // Prefer direct local saving if outputPath is available
+            if (outputPath) {
+              try {
+                const { saveFalResult } = await import("../utils/fal-save");
+                const saved = await saveFalResult(finalResult, outputPath);
+                if (saved && saved.length > 0) {
+                  result.saved_files = saved;
+                }
+              } catch (err: any) {
+                logger.error(`[FAL Status] Failed to save result locally to ${outputPath}: ${err.message}`);
+              }
+            } else {
+              // Fallback to standard storage logic (upstream)
+              try {
+                const { savedVideos, savedImages } = await saveFalUrls(finalResult);
+                if (savedVideos.length > 0) finalResult.saved_videos = savedVideos;
+                if (savedImages.length > 0) finalResult.saved_images = savedImages;
+              } catch (err: any) {
+                logger.error(`[FAL Status] Failed to save result to standard storage: ${err.message}`);
+              }
             }
 
             result = {
-              ...falFinalResult,
+              ...finalResult,
+              saved_files: result.saved_files,
               status: "COMPLETED",
             };
-          } else {
-            result = falStatusResult;
           }
         } else {
           result = await checkVertexStatus(originalEndpoint);
@@ -444,9 +482,11 @@ export const getGenerationStatus = {
             result: safeResult,
             message:
               status === "COMPLETED"
-                ? detectedSource === "fal"
-                  ? "Generation completed! Check 'result.saved_videos' or 'result.saved_images' for downloaded asset URLs."
-                  : "Generation completed! Check 'result.response.saved_videos' for the video URLs."
+                ? (result.saved_files 
+                   ? `Generation completed! Files saved to ${result.saved_files[0].localPath}` 
+                   : (result.saved_videos || result.saved_images 
+                      ? "Generation completed! Files saved to storage." 
+                      : "Generation completed! Check 'result' for the output URLs."))
                 : status === "FAILED"
                   ? "Generation failed. Check the 'result' field for error details."
                   : "Generation is still in progress. Call this tool again with the same resume_endpoint to check later.",

package/src/utils/fal-save.ts

@@ -0,0 +1,122 @@
+import * as fs from "fs";
+import * as path from "path";
+import { logger } from "./logger";
+
+/**
+ * Result of a file save operation.
+ */
+export interface SavedFile {
+  url: string;
+  localPath: string;
+  filename: string;
+  contentType?: string;
+}
+
+/**
+ * Clean and normalize a path, handling Windows-style backslashes on POSIX systems.
+ */
+export function normalizeLocalPath(filePath: string): string {
+  // Replace Windows backslashes with forward slashes for Mac/Linux
+  let normalized = filePath.replace(/\\/g, "/");
+  
+  // If it starts with a drive letter (e.g., B:/), we might want to handle it
+  // For now, we'll keep it as is, which might resolve relative to CWD if not absolute on Mac
+  // But usually, these are absolute paths in the user's environment.
+  
+  return path.normalize(normalized);
+}
+
+/**
+ * Download a file from a URL and save it to a local path.
+ */
+async function downloadFile(url: string, destPath: string): Promise<void> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+  }
+  
+  const arrayBuffer = await response.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  
+  // Ensure directory exists
+  const dir = path.dirname(destPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  
+  fs.writeFileSync(destPath, buffer);
+}
+
+/**
+ * Parse a FAL result and save any images/videos to the specified output path.
+ * 
+ * @param result The JSON result from FAL API
+ * @param outputPath The base local path to save to (e.g., "path/to/output.png")
+ * @returns Array of saved file information
+ */
+export async function saveFalResult(result: any, outputPath: string): Promise<SavedFile[]> {
+  const savedFiles: SavedFile[] = [];
+  const normalizedPath = normalizeLocalPath(outputPath);
+  const ext = path.extname(normalizedPath);
+  const dir = path.dirname(normalizedPath);
+  const base = path.basename(normalizedPath, ext);
+  
+  // 1. Identify files to download
+  const filesToDownload: { url: string; contentType?: string }[] = [];
+  
+  if (Array.isArray(result.images)) {
+    for (const img of result.images) {
+      if (img.url) filesToDownload.push({ url: img.url, contentType: img.content_type });
+    }
+  } else if (result.image && result.image.url) {
+    filesToDownload.push({ url: result.image.url, contentType: result.image.content_type });
+  }
+  
+  if (result.video && result.video.url) {
+    filesToDownload.push({ url: result.video.url, contentType: result.video.content_type });
+  } else if (Array.isArray(result.videos)) {
+    for (const vid of result.videos) {
+      if (vid.url) filesToDownload.push({ url: vid.url, contentType: vid.content_type });
+    }
+  }
+  
+  // Fallback: search for any "url" fields that look like media
+  if (filesToDownload.length === 0) {
+    const searchUrls = (obj: any) => {
+      if (!obj || typeof obj !== "object") return;
+      if (obj.url && typeof obj.url === "string" && (obj.url.startsWith("http"))) {
+        filesToDownload.push({ url: obj.url, contentType: obj.content_type });
+      } else {
+        for (const key in obj) searchUrls(obj[key]);
+      }
+    };
+    searchUrls(result);
+  }
+  
+  // 2. Download and save
+  for (const [i, file] of filesToDownload.entries()) {
+    let destPath: string;
+    
+    if (i === 0) {
+      destPath = normalizedPath;
+    } else {
+      // For subsequent files, add an index before the extension
+      destPath = path.join(dir, `${base}_${i}${ext}`);
+    }
+    
+    logger.info(`[FAL Save] Saving ${file.url} to ${destPath}...`);
+    try {
+      await downloadFile(file.url, destPath);
+      savedFiles.push({
+        url: file.url,
+        localPath: destPath,
+        filename: path.basename(destPath),
+        contentType: file.contentType
+      });
+    } catch (err: any) {
+      logger.error(`[FAL Save] Failed to save ${file.url}: ${err.message}`);
+    }
+  }
+  
+  return savedFiles;
+}