@mixio-pro/kalaasetu-mcp 2.0.4-beta → 2.0.7-beta

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@mixio-pro/kalaasetu-mcp",
-  "version": "2.0.4-beta",
+  "version": "2.0.7-beta",
   "description": "A powerful Model Context Protocol server providing AI tools for content generation and analysis",
   "type": "module",
   "module": "src/index.ts",
   "main": "src/index.ts",
   "bin": {
-    "kalaasetu-mcp": "./bin/cli.js"
+    "kalaasetu-mcp": "bin/cli.js"
   },
   "files": [
     "src",
@@ -35,7 +35,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/mixiopro/kalaasetu-mcp.git"
+    "url": "git+https://github.com/mixiopro/kalaasetu-mcp.git"
   },
   "bugs": {
     "url": "https://github.com/mixiopro/kalaasetu-mcp/issues"
@@ -58,4 +58,4 @@
     "wav": "^1.0.2",
     "zod": "^4.1.12"
   }
-}
+}

package/src/index.ts

@@ -1,14 +1,15 @@
 #!/usr/bin/env bun
 import { FastMCP } from "fastmcp";
 import pkg from "../package.json";
-import { geminiEditImage, geminiTextToImage } from "./tools/gemini";
-import { imageToVideo } from "./tools/image-to-video";
 import {
   falListPresets,
   falGetPresetDetails,
-  falGenerate,
   falUploadFile,
 } from "./tools/fal";
+import { createAllFalTools } from "./tools/fal/dynamic-tools";
+import { geminiEditImage, geminiTextToImage } from "./tools/gemini";
+import { imageToVideo } from "./tools/image-to-video";
+import { getGenerationStatus } from "./tools/get-status";
 
 const server = new FastMCP({
   name: "Kalaasetu MCP Server",
@@ -36,13 +37,17 @@ server.addTool(imageToVideo);
 // server.addTool(perplexityImages);
 // server.addTool(perplexityVideos);
 
-import { getGenerationStatus } from "./tools/get-status";
-
-// Fal AI Tools
+// Discovery and Utility Tools
 server.addTool(falListPresets);
-server.addTool(falGenerate);
+server.addTool(falGetPresetDetails);
 server.addTool(falUploadFile);
 
+// Dynamic FAL AI Tools - each preset becomes a separate tool (prefixed with fal_)
+const falTools = createAllFalTools();
+for (const tool of falTools) {
+  server.addTool(tool);
+}
+
 // Unified Status Tool (works with both FAL and Vertex AI)
 server.addTool(getGenerationStatus);
 

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

@@ -0,0 +1,406 @@
+/**
+ * Dynamic FAL Tools Generator
+ *
+ * Creates MCP tools dynamically from preset configurations.
+ * Each preset becomes a first-class MCP tool with its own Zod schema.
+ */
+
+import { z, type ZodTypeAny } from "zod";
+import { safeToolExecute } from "../../utils/tool-wrapper";
+import { resolveEnhancer } from "../../utils/prompt-enhancer-presets";
+import { sanitizeResponse } from "../../utils/sanitize";
+import {
+  FAL_QUEUE_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.
+ */
+async function authenticatedRequest(
+  url: string,
+  method: "GET" | "POST" | "PUT" = "GET",
+  jsonData?: Record<string, any>
+): Promise<any> {
+  const headers: Record<string, string> = {
+    Authorization: `Key ${getApiKey()}`,
+    "Content-Type": "application/json",
+  };
+
+  const options: RequestInit = {
+    method,
+    headers,
+    signal: AbortSignal.timeout(AUTHENTICATED_TIMEOUT),
+  };
+
+  if (jsonData && (method === "POST" || method === "PUT")) {
+    options.body = JSON.stringify(jsonData);
+  }
+
+  const response = await fetch(url, options);
+
+  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}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Sanitize parameters by removing null/undefined values.
+ */
+function sanitizeParameters(
+  parameters: Record<string, any>
+): Record<string, any> {
+  return Object.fromEntries(
+    Object.entries(parameters).filter(([_, v]) => v != null)
+  );
+}
+
+/**
+ * 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;
+  };
+}
+
+
+/**
+ * Build a Zod object schema from preset input_schema using built-in z.fromJSONSchema.
+ */
+function buildZodSchema(
+  inputSchema: Record<string, any> | undefined,
+  defaultParams?: Record<string, any>
+): z.ZodObject<any> {
+  // Construct a properties object for JSON schema
+  const properties: Record<string, any> = {};
+
+  if (inputSchema) {
+    for (const [key, schema] of Object.entries(inputSchema)) {
+      properties[key] = { ...schema };
+      // Override default if specified in defaultParams
+      if (defaultParams && defaultParams[key] !== undefined) {
+        properties[key].default = defaultParams[key];
+      }
+    }
+  }
+
+  // Create full JSON schema object
+  const jsonSchema = {
+    type: "object",
+    properties,
+  };
+
+  // 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
+  zodSchema = zodSchema.extend({
+    resume_endpoint: z
+      .string()
+      .optional()
+      .describe(
+        "If provided, resume polling for an existing request instead of starting a new one. " +
+          "Use the 'resume_endpoint' returned in an 'IN_PROGRESS' response."
+      ),
+    auto_enhance: z
+      .boolean()
+      .default(true) // Our custom default
+      .describe(
+        "Whether to automatically enhance the prompt. Set to false to disable."
+      ),
+  });
+
+  return zodSchema;
+}
+
+/**
+ * Create an MCP tool from a preset configuration.
+ */
+export function createToolFromPreset(preset: FalPresetConfig) {
+  const zodSchema = buildZodSchema(
+    preset.input_schema as Record<string, any>,
+    preset.defaultParams
+  );
+
+  const toolName = preset.presetName.startsWith("fal_")
+    ? preset.presetName
+    : `fal_${preset.presetName}`;
+
+  return {
+    name: toolName,
+    description:
+      preset.intent +
+      (preset.description ? ` ${preset.description}` : "") +
+      ` [Model: ${preset.modelId}]`,
+    parameters: zodSchema,
+    timeoutMs: 90000, // 90 seconds MCP timeout
+
+    execute: async (
+      args: Record<string, any>,
+      context?: ProgressContext
+    ) => {
+      return safeToolExecute(async () => {
+        let statusUrl: string;
+        let responseUrl: string;
+        let requestId: string;
+
+        // Handle resume flow
+        if (args.resume_endpoint) {
+          if (args.resume_endpoint.startsWith("http")) {
+            statusUrl = args.resume_endpoint;
+            responseUrl = args.resume_endpoint.replace(/\/status$/, "");
+            const urlParts = args.resume_endpoint.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}`);
+          } else {
+            // Legacy UUID format - reconstruct URL
+            requestId = args.resume_endpoint;
+            statusUrl = `${FAL_QUEUE_URL}/${preset.modelId}/requests/${requestId}/status`;
+            responseUrl = `${FAL_QUEUE_URL}/${preset.modelId}/requests/${requestId}`;
+            context?.log?.info(
+              `Resuming polling for ${preset.modelId} request: ${requestId}`
+            );
+          }
+        } else {
+          // New request - start generation
+          try {
+            const apiKey = getApiKey();
+            if (context?.streamContent) {
+              await context.streamContent({
+                type: "text" as const,
+                text: `[FAL] ✓ API key found (${apiKey.slice(0, 8)}...). Using model: ${preset.modelId}`,
+              });
+            }
+          } catch (keyError: any) {
+            throw keyError;
+          }
+
+          // Build parameters: input_schema defaults → defaultParams → user args
+          // Extract only the model parameters (exclude our internal fields)
+          const { resume_endpoint, auto_enhance, ...userParams } = args;
+
+          // Start with defaults from input_schema
+          const schemaDefaults: Record<string, any> = {};
+          if (preset.input_schema) {
+            for (const [key, paramSchema] of Object.entries(preset.input_schema)) {
+              if ((paramSchema as any).default !== undefined) {
+                schemaDefaults[key] = (paramSchema as any).default;
+              }
+            }
+          }
+
+          // Merge: schema defaults → preset defaultParams → user params
+          const mergedParams = {
+            ...schemaDefaults,
+            ...(preset.defaultParams || {}),
+            ...userParams,
+          };
+
+          // Apply prompt enhancement if enabled
+          const shouldEnhance = auto_enhance !== false;
+          if (shouldEnhance && preset.promptEnhancer && mergedParams.prompt) {
+            const enhancerName =
+              typeof preset.promptEnhancer === "string"
+                ? preset.promptEnhancer
+                : null;
+
+            if (enhancerName === "ltx2") {
+              const { enhancePromptWithLLM, isLLMEnhancerAvailable } =
+                await import("../../utils/llm-prompt-enhancer");
+              if (isLLMEnhancerAvailable()) {
+                try {
+                  const originalPrompt = mergedParams.prompt;
+                  mergedParams.prompt = await enhancePromptWithLLM(
+                    mergedParams.prompt,
+                    "ltx2"
+                  );
+                  context?.log?.info(
+                    `LLM-enhanced prompt: "${originalPrompt}" → "${mergedParams.prompt}"`
+                  );
+                } catch (err) {
+                  context?.log?.info(
+                    `LLM enhancement failed, using original prompt`
+                  );
+                }
+              }
+            } else if (preset.promptEnhancer) {
+              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(sanitizeResponse(queueRes));
+          }
+
+          requestId =
+            queueRes.request_id || queueRes.status_url?.split("/").pop() || "";
+
+          if (!requestId) {
+            throw new Error("Could not extract request ID from response");
+          }
+
+          statusUrl =
+            queueRes.status_url ||
+            `${FAL_QUEUE_URL}/${preset.modelId}/requests/${requestId}/status`;
+          responseUrl =
+            queueRes.response_url ||
+            `${FAL_QUEUE_URL}/${preset.modelId}/requests/${requestId}`;
+
+          if (context?.streamContent) {
+            await context.streamContent({
+              type: "text" as const,
+              text: `[FAL] Generation started. resume_endpoint: ${statusUrl}`,
+            });
+          }
+        }
+
+        // Stream message for resume calls
+        if (args.resume_endpoint && context?.streamContent) {
+          await context.streamContent({
+            type: "text" as const,
+            text: `[FAL] Resuming status check for job: ${requestId}`,
+          });
+        }
+
+        // Poll for completion
+        const startTime = Date.now();
+        const MAX_POLL_TIME = 60000; // 60 seconds internal timeout
+        let pollCount = 0;
+        const POLL_INTERVAL = 3000;
+
+        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...`
+              );
+              res = await authenticatedRequest(responseUrl, "GET");
+              statusUrl = responseUrl;
+            } else {
+              throw e;
+            }
+          }
+
+          if (res.status_url) statusUrl = res.status_url;
+          if (res.response_url) responseUrl = res.response_url;
+
+          if (context?.reportProgress) {
+            const elapsed = Date.now() - startTime;
+            const progressPercent = Math.min(
+              Math.round((elapsed / MAX_POLL_TIME) * 100),
+              99
+            );
+            await context.reportProgress({
+              progress: progressPercent,
+              total: 100,
+            });
+          }
+
+          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})`,
+            });
+          }
+
+          if (res.status === "COMPLETED") {
+            if (context?.reportProgress) {
+              await context.reportProgress({ progress: 100, total: 100 });
+            }
+            const finalResult = await authenticatedRequest(responseUrl, "GET");
+            return JSON.stringify(sanitizeResponse(finalResult));
+          }
+
+          if (res.status === "FAILED") {
+            throw new Error(
+              `Generation failed: ${JSON.stringify(res.error || res)}`
+            );
+          }
+
+          await wait(POLL_INTERVAL);
+        }
+
+        // Timeout - return resume_endpoint
+        return JSON.stringify({
+          status: "IN_PROGRESS",
+          request_id: requestId,
+          resume_endpoint: statusUrl,
+          status_url: statusUrl,
+          response_url: responseUrl,
+          message:
+            "The generation is still in progress. Call this tool again with resume_endpoint to continue polling.",
+        });
+      }, preset.presetName);
+    },
+  };
+}
+
+/**
+ * Create all FAL tools from the configuration.
+ * Each preset becomes a separate MCP tool.
+ */
+export function createAllFalTools(): ReturnType<typeof createToolFromPreset>[] {
+  const config = loadFalConfig();
+  return config.presets.map((preset) => createToolFromPreset(preset));
+}

package/src/tools/fal/generate.ts

@@ -92,7 +92,7 @@ export const falGenerate = {
   description:
     "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. " +
+    "If the generation takes too long (timeout or error), it returns a 'resume_endpoint' 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.",
@@ -105,18 +105,17 @@ export const falGenerate = {
       ),
     parameters: z
       .record(z.string(), z.any())
-      .optional()
       .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
+    resume_endpoint: z
       .string()
       .optional()
       .describe(
         "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."
+          "Use the 'resume_endpoint' returned in an 'IN_PROGRESS' response or after a timeout error."
       ),
   }),
   timeoutMs: 90000, // 90 seconds MCP timeout (internal timeout is 60s)
@@ -124,7 +123,7 @@ export const falGenerate = {
     args: {
       preset_name?: string;
       parameters?: Record<string, any>;
-      resume_id?: string;
+      resume_endpoint?: string;
       auto_enhance?: boolean;
     },
     context?: ProgressContext
@@ -135,21 +134,21 @@ export const falGenerate = {
       let requestId: string;
       const config = loadFalConfig();
 
-      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;
+      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;
           // Derive responseUrl by removing /status suffix if present
-          responseUrl = args.resume_id.replace(/\/status$/, "");
+          responseUrl = args.resume_endpoint.replace(/\/status$/, "");
           // Extract requestId from URL for logging
-          const urlParts = args.resume_id.split("/");
+          const urlParts = args.resume_endpoint.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}`);
+          context?.log?.info(`Resuming with FAL URL: ${args.resume_endpoint}`);
         } else {
           // LEGACY: Try to resolve model from preset_name or parse modelId::requestId
           let modelIdFromPreset: string | undefined;
@@ -165,8 +164,8 @@ export const falGenerate = {
             }
           }
 
-          if (args.resume_id.includes("::")) {
-            const parts = args.resume_id.split("::");
+          if (args.resume_endpoint.includes("::")) {
+            const parts = args.resume_endpoint.split("::");
             const mId = parts[0];
             const rId = parts[1] || "";
 
@@ -181,7 +180,7 @@ export const falGenerate = {
             );
           } else {
             // Legacy/Fallback for raw UUIDs
-            requestId = args.resume_id;
+            requestId = args.resume_endpoint;
 
             if (modelIdFromPreset) {
               // Best case: User provided the preset name!
@@ -192,8 +191,8 @@ export const falGenerate = {
               );
             } 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}`;
+              statusUrl = `${FAL_QUEUE_URL}/requests/${args.resume_endpoint}/status`;
+              responseUrl = `${FAL_QUEUE_URL}/requests/${args.resume_endpoint}`;
 
               // Verify/Recovery: Check if generic URL works, if not try to guess model
               // ... (Smart recovery logic below)
@@ -230,7 +229,7 @@ export const falGenerate = {
               }
             }
             context?.log?.info(
-              `Resuming polling for request: ${args.resume_id}`
+              `Resuming polling for request: ${args.resume_endpoint}`
             );
           }
         } // Close the LEGACY else block (line 149)
@@ -348,13 +347,13 @@ export const falGenerate = {
         if (context?.streamContent) {
           await context.streamContent({
             type: "text" as const,
-            text: `[FAL] Generation started. resume_id: ${statusUrl} (use this URL to check status)`,
+            text: `[FAL] Generation started. resume_endpoint: ${statusUrl} (use this URL to check status)`,
           });
         }
       }
 
       // Stream message for resume calls
-      if (args.resume_id && context?.streamContent) {
+      if (args.resume_endpoint && context?.streamContent) {
         await context.streamContent({
           type: "text" as const,
           text: `[FAL] Resuming status check for job: ${requestId}`,
@@ -362,7 +361,7 @@ export const falGenerate = {
       }
 
       const startTime = Date.now();
-      const MAX_POLL_TIME = 60000; // 60 seconds internal timeout - then return resume_id
+      const MAX_POLL_TIME = 60000; // 60 seconds internal timeout - then return resume_endpoint
       let pollCount = 0;
       const POLL_INTERVAL = 3000;
 
@@ -433,12 +432,12 @@ export const falGenerate = {
         await wait(POLL_INTERVAL);
       }
 
-      // Timeout - return composite resume_id
+      // Timeout - return composite resume_endpoint
       // 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.resume_endpoint && args.resume_endpoint.includes("::")
+          ? args.resume_endpoint.split("::")[0]
           : args.preset_name
           ? config.presets.find((p) => p.presetName === args.preset_name)
               ?.modelId
@@ -447,11 +446,11 @@ export const falGenerate = {
       return JSON.stringify({
         status: "IN_PROGRESS",
         request_id: requestId,
-        resume_id: statusUrl, // Use the FULL URL for reliable resume
+        resume_endpoint: 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.",
+          "The generation is still in progress. Call this tool again with resume_endpoint (the URL) to continue polling.",
       });
     }, "fal_generate");
   },

package/src/tools/fal/models.ts

@@ -72,7 +72,9 @@ export const falListPresets = {
 
       // Fetch schemas for presets that don't have them (or if refresh requested)
       for (const preset of config.presets) {
-        const shouldFetch = !preset.input_schema || args.refresh_schemas;
+        const hasSchema =
+          preset.input_schema && Object.keys(preset.input_schema).length > 0;
+        const shouldFetch = !hasSchema || args.refresh_schemas;
         console.log(
           `[fal_list_presets] ${
             preset.presetName

package/src/tools/get-status.ts

@@ -6,13 +6,27 @@
 import { z } from "zod";
 import { safeToolExecute } from "../utils/tool-wrapper";
 import { getGoogleAccessToken } from "../utils/google-auth";
+import { sanitizeResponse } from "../utils/sanitize";
 
 const FAL_KEY = process.env.FAL_KEY;
 
 /**
  * Check FAL generation status using the status URL
  */
-async function checkFalStatus(statusUrl: string): Promise<any> {
+interface VertexOperation {
+  done?: boolean;
+  response?: {
+    videos?: Array<{
+      bytesBase64Encoded?: string;
+    }>;
+    saved_videos?: any[];
+    [key: string]: any;
+  };
+  error?: any;
+  [key: string]: any;
+}
+
+export async function checkFalStatus(statusUrl: string): Promise<any> {
   if (!FAL_KEY) {
     throw new Error("FAL_KEY environment variable not set");
   }
@@ -30,45 +44,52 @@ async function checkFalStatus(statusUrl: string): Promise<any> {
     throw new Error(`FAL API error [${response.status}]: ${errorText}`);
   }
 
-  const statusResult = (await response.json()) as { status?: string };
-
-  if (statusResult.status === "COMPLETED") {
-    // Fetch the actual result
-    const responseUrl = statusUrl.replace(/\/status$/, "");
-    const resultResponse = await fetch(responseUrl, {
-      method: "GET",
-      headers: {
-        Authorization: `Key ${FAL_KEY}`,
-        "Content-Type": "application/json",
-      },
-    });
-
-    if (resultResponse.ok) {
-      return await resultResponse.json();
-    }
+  return await response.json();
+}
+
+export async function fetchFalResult(responseUrl: string): Promise<any> {
+  if (!FAL_KEY) {
+    throw new Error("FAL_KEY environment variable not set");
+  }
+
+  const response = await fetch(responseUrl, {
+    method: "GET",
+    headers: {
+      Authorization: `Key ${FAL_KEY}`,
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`FAL API error [${response.status}]: ${errorText}`);
   }
 
-  return statusResult;
+  return await response.json();
 }
 
-/**
- * Check Vertex AI operation status
- */
-async function checkVertexStatus(
-  operationName: string,
-  projectId: string,
-  locationId: string
-): Promise<any> {
+export async function checkVertexStatus(resumeEndpoint: string): Promise<any> {
   const accessToken = await getGoogleAccessToken();
 
-  const operationsUrl = `https://${locationId}-aiplatform.googleapis.com/v1/projects/${projectId}/locations/${locationId}/publishers/google/models/veo-3.1-generate-preview/operations/${operationName}`;
+  // resumeEndpoint is composite format: fetchUrl||operationName||outputPath
+  const parts = resumeEndpoint.split("||");
+  const fetchUrl = parts[0] || "";
+  const operationName = parts[1] || "";
+  const outputPath = parts[2] || ""; // Optional custom output path
 
-  const response = await fetch(operationsUrl, {
-    method: "GET",
+  if (!fetchUrl || !operationName) {
+    throw new Error(
+      "Invalid Vertex resume_endpoint format. Expected 'fetchUrl||operationName[||outputPath]'.",
+    );
+  }
+
+  const response = await fetch(fetchUrl, {
+    method: "POST",
     headers: {
       Authorization: `Bearer ${accessToken}`,
       "Content-Type": "application/json",
     },
+    body: JSON.stringify({ operationName }),
   });
 
   if (!response.ok) {
@@ -76,64 +97,91 @@ async function checkVertexStatus(
     throw new Error(`Vertex AI API error [${response.status}]: ${errorText}`);
   }
 
-  return await response.json();
+  const result = (await response.json()) as VertexOperation;
+
+  // If completed, save videos if present
+  const done = !!result.done || !!result.response;
+  if (done) {
+    const resp = result.response || result;
+    if (Array.isArray(resp?.videos) && resp.videos.length > 0) {
+      const { getStorage } = await import("../storage");
+      const { generateTimestampedFilename } = await import("../utils/filename");
+      const storage = getStorage();
+      const savedVideos: any[] = [];
+
+      for (let i = 0; i < resp.videos.length; i++) {
+        const v = resp.videos[i];
+        if (v?.bytesBase64Encoded) {
+          let filePath: string;
+          if (outputPath) {
+            // Use custom path, add index for subsequent videos
+            filePath =
+              i === 0 ? outputPath : outputPath.replace(/\.mp4$/i, `_${i}.mp4`);
+          } else {
+            // Default timestamped filename
+            filePath = generateTimestampedFilename(`video_output_${i}.mp4`);
+          }
+          const buf = Buffer.from(v.bytesBase64Encoded, "base64");
+          const url = await storage.writeFile(filePath, buf);
+          savedVideos.push({
+            url,
+            filename: filePath,
+            mimeType: "video/mp4",
+          });
+          // CRITICAL: Remove base64 data to prevent context window poisoning
+          delete v.bytesBase64Encoded;
+        }
+      }
+
+      if (savedVideos.length > 0) {
+        resp.saved_videos = savedVideos;
+      }
+    }
+  }
+
+  return result;
 }
 
 export const getGenerationStatus = {
   name: "get_generation_status",
   description:
     "Check the status or retrieve the result of a generation operation that was started by 'fal_generate' or 'generateVideoi2v'. " +
-    "Use this when the original generation tool returned an 'IN_PROGRESS' status with a 'resume_id'. " +
-    "Pass the resume_id exactly as it was returned. " +
-    "For FAL operations, the resume_id is a full URL. " +
-    "For Vertex AI operations, the resume_id is an operation name.",
+    "Use this when the original generation tool returned an 'IN_PROGRESS' status with a 'resume_endpoint'. " +
+    "Pass the resume_endpoint exactly as it was returned. " +
+    "For FAL operations, the resume_endpoint is a full URL. " +
+    "For Vertex AI operations, the resume_endpoint is an operation name or full path.",
   parameters: z.object({
-    resume_id: z
+    resume_endpoint: z
       .string()
       .describe(
-        "The resume_id returned by the original generation tool. " +
+        "The resume_endpoint returned by the original generation tool. " +
           "For FAL: This is a full URL (starts with 'https://queue.fal.run/...'). " +
-          "For Vertex AI: This is an operation name."
+          "For Vertex AI: This is an operation name or full path.",
       ),
     source: z
       .enum(["fal", "vertex", "auto"])
       .optional()
       .default("auto")
       .describe(
-        "Source of the operation: 'fal' for FAL AI, 'vertex' for Google Vertex AI, or 'auto' to auto-detect based on resume_id format."
+        "Source of the operation: 'fal' for FAL AI, 'vertex' for Google Vertex AI, or 'auto' to auto-detect based on resume_endpoint format.",
       ),
-    project_id: z
-      .string()
-      .optional()
-      .default("mixio-pro")
-      .describe("GCP Project ID (only needed for Vertex AI operations)."),
-    location_id: z
-      .string()
-      .optional()
-      .default("us-central1")
-      .describe("GCP region (only needed for Vertex AI operations)."),
   }),
   timeoutMs: 30000, // 30 seconds for status check
   execute: async (args: {
-    resume_id: string;
+    resume_endpoint: string;
     source?: "fal" | "vertex" | "auto";
-    project_id?: string;
-    location_id?: string;
   }) => {
     return safeToolExecute(async () => {
-      const {
-        resume_id,
-        source = "auto",
-        project_id = "mixio-pro",
-        location_id = "us-central1",
-      } = args;
-
-      // Auto-detect source based on resume_id format
+      const { resume_endpoint, source = "auto" } = args;
+      const project_id = "mixio-pro";
+      const location_id = "us-central1";
+
+      // Auto-detect source based on resume_endpoint format
       let detectedSource = source;
       if (source === "auto") {
         if (
-          resume_id.startsWith("https://queue.fal.run") ||
-          resume_id.startsWith("https://fal.run")
+          resume_endpoint.startsWith("https://queue.fal.run") ||
+          resume_endpoint.startsWith("https://fal.run")
         ) {
           detectedSource = "fal";
         } else {
@@ -144,30 +192,33 @@ export const getGenerationStatus = {
       let result: any;
 
       if (detectedSource === "fal") {
-        result = await checkFalStatus(resume_id);
+        result = await checkFalStatus(resume_endpoint);
       } else {
-        result = await checkVertexStatus(resume_id, project_id, location_id);
+        result = await checkVertexStatus(resume_endpoint);
       }
 
       // Normalize the response
       const status =
-        result.status || (result.done ? "COMPLETED" : "IN_PROGRESS");
+        (result as any).status ||
+        ((result as any).done ? "COMPLETED" : "IN_PROGRESS");
+
+      const safeResult = sanitizeResponse(result);
 
       return JSON.stringify(
         {
           source: detectedSource,
           status,
-          resume_id,
-          result,
+          resume_endpoint,
+          result: safeResult,
           message:
             status === "COMPLETED"
-              ? "Generation completed! The result is included in the 'result' field."
+              ? "Generation completed! Check 'result.response.saved_videos' for the video 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_id to check later.",
+                ? "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.",
         },
         null,
-        2
+        2,
       );
     }, "get_generation_status");
   },

package/src/tools/image-to-video.ts

@@ -8,6 +8,7 @@ import {
 } from "../utils/prompt-enhancer-presets";
 
 import { getGoogleAccessToken } from "../utils/google-auth";
+import { checkVertexStatus } from "./get-status";
 
 async function wait(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -16,7 +17,7 @@ async function wait(ms: number): Promise<void> {
 import { ensureLocalFile } from "../utils/url-file";
 
 async function fileToBase64(
-  filePath: string
+  filePath: string,
 ): Promise<{ data: string; mimeType: string }> {
   const fileResult = await ensureLocalFile(filePath);
 
@@ -47,7 +48,7 @@ export const imageToVideo = {
   description:
     "Generate professional-quality cinematic videos from a starting image and text prompt using Google's Vertex AI Veo models. " +
     "This tool follows a 'Synchronous Facade' pattern: it handles polling internally but can be paused/resumed. " +
-    "If the generation takes too long, it returns a 'resume_id' that you MUST use to call this tool again to pick up progress. " +
+    "If the generation takes too long, it returns a 'resume_endpoint' that you MUST use to call this tool again to pick up progress. " +
     "It produces state-of-the-art cinematic results. " +
     "ONLY USE WHEN WORKING WITH GOOGLE VERTEX AI MODELS.",
   parameters: z.object({
@@ -55,7 +56,7 @@ export const imageToVideo = {
       .string()
       .optional()
       .describe(
-        "Required for new requests. Descriptive text for the video action and style (e.g., 'A robot walking through a neon city at night')."
+        "Required for new requests. Descriptive text for the video action and style (e.g., 'A robot walking through a neon city at night').",
       ),
     image_path: z
       .string()
@@ -65,21 +66,21 @@ export const imageToVideo = {
       .string()
       .optional()
       .describe(
-        "Optional: Absolute local path or URL to the ENDING image frame to guide the video's conclusion."
+        "Optional: Absolute local path or URL to the ENDING image frame to guide the video's conclusion.",
       ),
     aspect_ratio: z
       .string()
       .optional()
       .default("16:9")
       .describe(
-        "Target aspect ratio: '16:9' (landscape) or '9:16' (vertical)."
+        "Target aspect ratio: '16:9' (landscape) or '9:16' (vertical).",
       ),
     duration_seconds: z
       .string()
       .optional()
       .default("6")
       .describe(
-        "Target duration. Vertex AI ONLY supports exactly '4', '6', or '8' seconds. Other values will be rounded to the nearest supported step."
+        "Target duration. Vertex AI ONLY supports exactly '4', '6', or '8' seconds. Other values will be rounded to the nearest supported step.",
       ),
     resolution: z
       .string()
@@ -89,71 +90,59 @@ export const imageToVideo = {
       .string()
       .optional()
       .describe(
-        "Visual elements or styles to EXCLUDE from the generated video."
+        "Visual elements or styles to EXCLUDE from the generated video.",
       ),
     person_generation: z
       .string()
       .optional()
       .describe(
-        "Policy for generating people: 'allow_adult' (standard) or 'allow_all'. Note: Gemini 1.5+ safety filters apply."
+        "Policy for generating people: 'allow_adult' (standard) or 'allow_all'. Note: Gemini 1.5+ safety filters apply.",
       ),
     reference_images: z
       .array(z.string())
       .optional()
       .describe(
-        "Optional: Additional images (up to 3) to guide style or character consistency."
+        "Optional: Additional images (up to 3) to guide style or character consistency.",
       ),
     output_path: z
       .string()
       .optional()
       .describe(
-        "Optional: Local path to save the resulting .mp4 file. Defaults to timestamped filename."
-      ),
-    project_id: z
-      .string()
-      .optional()
-      .default("mixio-pro")
-      .describe("GCP Project ID for Vertex billing. Default is mixio-pro."),
-    location_id: z
-      .string()
-      .optional()
-      .default("us-central1")
-      .describe(
-        "GCP region for Vertex AI processing (Default is 'us-central1')."
+        "Optional: Local path to save the resulting .mp4 file. Defaults to timestamped filename.",
       ),
     model_id: z
       .string()
       .optional()
       .default("veo-3.1-fast-generate-001")
       .describe(
-        "Specific Vertex Veo model ID to use. Default Value is veo-3.1-fast-generate-001"
+        "Specific Vertex Veo model ID to use. Default Value is veo-3.1-fast-generate-001",
       ),
     generate_audio: z
       .boolean()
       .optional()
       .describe(
-        "If true, Vertex will attempt to synthesize synchronized audio for the video."
+        "If true, Vertex will attempt to synthesize synchronized audio for the video.",
       )
       .default(false),
-    resume_id: z
+    resume_endpoint: z
       .string()
       .optional()
       .describe(
         "If provided, the tool will check the status of an existing Vertex operation instead of starting a new one. " +
-          "Use the 'request_id' returned in an 'IN_PROGRESS' response."
+          "Use the 'resume_endpoint' returned in an 'IN_PROGRESS' response.",
       ),
     auto_enhance: z
       .boolean()
       .optional()
       .describe(
-        "Whether to automatically enhance the prompt using Veo/LTX guidelines (default: true if enabled via preset or config). Set to false to disable enhancement."
+        "Whether to automatically enhance the prompt using Veo/LTX guidelines (default: true if enabled via preset or config). Set to false to disable enhancement.",
       ),
     enhancer_preset: z
       .string()
       .optional()
       .describe(
         "Optional: Name of a video prompt enhancer preset (e.g., 'veo', 'ltx2', 'cinematic_video'). " +
-          "When using Veo, setting this to 'veo' (or setting auto_enhance=true) will trigger the LLM-based enhancer."
+          "When using Veo, setting this to 'veo' (or setting auto_enhance=true) will trigger the LLM-based enhancer.",
       ),
   }),
   timeoutMs: 90000, // 90 seconds MCP timeout (internal timeout is 60s)
@@ -169,11 +158,9 @@ export const imageToVideo = {
       person_generation?: string;
       reference_images?: string[] | string;
       output_path?: string;
-      project_id?: string;
-      location_id?: string;
       model_id?: string;
       generate_audio?: boolean;
-      resume_id?: string;
+      resume_endpoint?: string;
       enhancer_preset?: string;
       auto_enhance?: boolean;
     },
@@ -190,11 +177,11 @@ export const imageToVideo = {
         info: (msg: string, data?: any) => void;
         debug: (msg: string, data?: any) => void;
       };
-    }
+    },
   ) {
     return safeToolExecute(async () => {
-      const projectId = args.project_id || "mixio-pro";
-      const location = args.location_id || "us-central1";
+      const projectId = "mixio-pro";
+      const location = "us-central1";
       const modelId = args.model_id || "veo-3.1-fast-generate-preview";
 
       // Validate and parse duration_seconds - snap to nearest 4, 6, or 8
@@ -260,13 +247,13 @@ export const imageToVideo = {
 
       // If resuming, reconstruct the full operation path from the UUID
       let operationName: string | undefined;
-      if (args.resume_id) {
+      if (args.resume_endpoint) {
         // Support both UUID-only and full path formats
-        if (args.resume_id.includes("/")) {
-          operationName = args.resume_id; // Already a full path
+        if (args.resume_endpoint.includes("/")) {
+          operationName = args.resume_endpoint; // Already a full path
         } else {
           // Reconstruct full path from UUID
-          operationName = `projects/${projectId}/locations/${location}/publishers/google/models/${modelId}/operations/${args.resume_id}`;
+          operationName = `projects/${projectId}/locations/${location}/publishers/google/models/${modelId}/operations/${args.resume_endpoint}`;
         }
       }
       let current: any;
@@ -327,7 +314,7 @@ export const imageToVideo = {
             refImages = args.reference_images;
           } else {
             throw new Error(
-              "Invalid reference_images: must be array or string"
+              "Invalid reference_images: must be array or string",
             );
           }
 
@@ -342,7 +329,7 @@ export const imageToVideo = {
                   },
                   referenceType: "asset",
                 };
-              })
+              }),
             );
           }
         }
@@ -385,7 +372,7 @@ export const imageToVideo = {
               try {
                 enhancedPrompt = await enhancePromptWithLLM(args.prompt, "veo");
                 context?.log?.info(
-                  `LLM-enhanced prompt for Veo: "${args.prompt}" → "${enhancedPrompt}"`
+                  `LLM-enhanced prompt for Veo: "${args.prompt}" → "${enhancedPrompt}"`,
                 );
 
                 if (context?.streamContent) {
@@ -396,12 +383,12 @@ export const imageToVideo = {
                 }
               } catch (err: any) {
                 context?.log?.info(
-                  `LLM enhancement failed, using original: ${err.message}`
+                  `LLM enhancement failed, using original: ${err.message}`,
                 );
               }
             } else {
               context?.log?.info(
-                "GEMINI_API_KEY not set, skipping Veo LLM enhancement"
+                "GEMINI_API_KEY not set, skipping Veo LLM enhancement",
               );
             }
           } else {
@@ -457,57 +444,44 @@ export const imageToVideo = {
 
       if (!operationName) {
         throw new Error(
-          "Vertex did not return an operation name for long-running request"
+          "Vertex did not return an operation name for long-running request",
         );
       }
 
-      // Extract just the operation UUID from the full path for a cleaner resume_id
-      // Full path: projects/.../operations/<uuid>
-      const operationUuid = operationName.split("/").pop() || operationName;
+      // Construct the composite resume_endpoint: fetchUrl||operationName||outputPath
+      // This allows get_generation_status to use the URL directly and preserve output_path
+      const outputPathPart = args.output_path || "";
+      const compositeResumeEndpoint = `${fetchUrl}||${operationName}||${outputPathPart}`;
 
-      // Stream the resume_id to the LLM immediately (before polling starts)
+      // Stream the resume_endpoint to the LLM immediately (before polling starts)
       // This way the LLM has it even if MCP client times out during polling
       if (context?.streamContent) {
-        const isResume = !!args.resume_id;
+        const isResume = !!args.resume_endpoint;
         await context.streamContent({
           type: "text" as const,
           text: isResume
-            ? `[Vertex] Resuming status check for job: ${operationUuid}`
-            : `[Vertex] Video generation started. resume_id: ${operationUuid} (use this to check status if needed)`,
+            ? `[Vertex] Resuming status check for job`
+            : `[Vertex] Video generation started. resume_endpoint: ${compositeResumeEndpoint} (use this to check status if needed)`,
         });
       }
 
       // Poll for status - keep polling until done
-      // Resume_id was already streamed, so if MCP client times out the LLM still has it
+      // Resume_endpoint was already streamed, so if MCP client times out the LLM still has it
       let done = current ? !!current.done || !!current.response : false;
       const startTime = Date.now();
-      const MAX_POLL_TIME = 60000; // 60 seconds internal timeout - then return resume_id
+      const MAX_POLL_TIME = 60000; // 60 seconds internal timeout - then return resume_endpoint
 
       while (!done && Date.now() - startTime < MAX_POLL_TIME) {
         await wait(10000); // 10 second intervals
 
-        const poll = await fetch(fetchUrl, {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${token}`,
-            "Content-Type": "application/json",
-          },
-          body: JSON.stringify({ operationName }),
-        });
-        if (!poll.ok) {
-          const text = await poll.text();
-          throw new Error(
-            `Vertex operation poll failed: ${poll.status} ${text}`
-          );
-        }
-        current = (await poll.json()) as any;
+        current = await checkVertexStatus(compositeResumeEndpoint);
         done = !!current.done || !!current.response;
 
         if (context?.reportProgress) {
           const elapsed = Date.now() - startTime;
           const progressPercent = Math.min(
             Math.round((elapsed / MAX_POLL_TIME) * 100),
-            99
+            99,
           );
           await context.reportProgress({
             progress: progressPercent,
@@ -519,7 +493,7 @@ export const imageToVideo = {
           await context.streamContent({
             type: "text" as const,
             text: `[Vertex] Still processing... (${Math.round(
-              (Date.now() - startTime) / 1000
+              (Date.now() - startTime) / 1000,
             )}s elapsed)`,
           });
         }
@@ -529,68 +503,33 @@ export const imageToVideo = {
         return JSON.stringify({
           status: "IN_PROGRESS",
           request_id: operationName,
-          resume_id: operationName,
+          resume_endpoint: compositeResumeEndpoint,
           message:
-            "Still in progress. Call this tool again with resume_id to continue checking.",
+            "Still in progress. Call this tool again with resume_endpoint to continue checking.",
         });
       }
 
       const resp = current.response || current;
-      // Decode from response.videos[].bytesBase64Encoded only
-      const videos: Array<{ url: string; filename: string; mimeType: string }> =
-        [];
-      const saveVideo = async (base64: string, index: number) => {
-        if (!base64) return;
-
-        // Use provided output path or generate default with timestamp
-        let filePath: string;
-        if (args.output_path) {
-          // User provided path - use as-is for first video, add index for subsequent
-          filePath =
-            index === 0
-              ? args.output_path
-              : args.output_path.replace(/\.mp4$/i, `_${index}.mp4`);
-        } else {
-          // No path provided - generate timestamped default
-          const defaultName = `video_output${index > 0 ? `_${index}` : ""}.mp4`;
-          filePath = generateTimestampedFilename(defaultName);
-        }
-
-        const buf = Buffer.from(base64, "base64");
-        const storage = getStorage();
-        const url = await storage.writeFile(filePath, buf);
-        videos.push({
-          url,
-          filename: filePath,
-          mimeType: "video/mp4",
-        });
-      };
-
-      if (Array.isArray(resp?.videos) && resp.videos.length > 0) {
-        for (let i = 0; i < resp.videos.length; i++) {
-          const v = resp.videos[i] || {};
-          if (typeof v.bytesBase64Encoded === "string") {
-            await saveVideo(v.bytesBase64Encoded, i);
-          }
-        }
-      }
-      if (videos.length > 0) {
+      
+      // checkVertexStatus already handles saving videos and sanitizing base64
+      if (Array.isArray(resp.saved_videos) && resp.saved_videos.length > 0) {
         return JSON.stringify({
-          videos,
+          videos: resp.saved_videos,
           message: "Video(s) generated successfully",
         });
       }
 
-      // If nothing saved, return a concise summary plus head/tail snippets of JSON
-      let jsonStr = "";
-      try {
-        jsonStr = JSON.stringify(resp);
-      } catch {}
-      const head150 = jsonStr ? jsonStr.slice(0, 150) : "";
-      const tail50 = jsonStr
-        ? jsonStr.slice(Math.max(0, jsonStr.length - 50))
-        : "";
-      return `Vertex operation done but no videos array present. operationName=${operationName}. json_head150=${head150} json_tail50=${tail50}`;
+      // If nothing saved, return a clean error without any raw JSON that could contain base64
+      // CRITICAL: Never return raw response data to prevent context window poisoning
+      const respKeys = resp ? Object.keys(resp) : [];
+      return JSON.stringify({
+        status: "ERROR",
+        message:
+          "Vertex operation completed but no videos were found in the response.",
+        operationName,
+        responseKeys: respKeys,
+        hint: "The response structure may have changed. Check the Vertex AI documentation or search for the expected response format.",
+      });
     }, "imageToVideo");
   },
 };

package/src/utils/sanitize.ts

@@ -0,0 +1,35 @@
+/**
+ * Utility to sanitize API responses by removing or masking large data fields
+ * like base64-encoded bytes to prevent context window poisoning.
+ */
+
+/**
+ * Recursively sanitizes an object by replacing large data fields.
+ * @param obj The object or array to sanitize
+ * @returns A new object with sensitive/large fields masked
+ */
+export function sanitizeResponse(obj: any): any {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== "object") return obj;
+
+  if (Array.isArray(obj)) {
+    return obj.map(sanitizeResponse);
+  }
+
+  const sanitized: any = {};
+  for (const key of Object.keys(obj)) {
+    // List of keys known to contain large binary data or base64
+    const isLargeDataKey =
+      key === "bytesBase64Encoded" ||
+      key === "base64" ||
+      key === "data" ||
+      key === "content" && typeof obj[key] === "string" && obj[key].length > 10000;
+
+    if (isLargeDataKey) {
+      sanitized[key] = "[LARGE_DATA_HIDDEN]";
+    } else {
+      sanitized[key] = sanitizeResponse(obj[key]);
+    }
+  }
+  return sanitized;
+}