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

package/src/tools/fal/models.ts

@@ -1,45 +1,159 @@
+import { z } from "zod";
+import {
+  loadFalConfig,
+  saveFalConfig,
+  FAL_BASE_URL,
+  DEFAULT_TIMEOUT,
+} from "./config";
+import { safeToolExecute } from "../../utils/tool-wrapper";
+
 /**
- * Models module for fal.ai MCP server.
- * Provides tools for retrieving information about configured fal.ai models.
+ * Extract simplified input schema from FAL OpenAPI response.
+ * Returns only the properties object from the input schema.
  */
+function extractInputSchema(openApiSchema: any): Record<string, any> | null {
+  try {
+    const schemas = openApiSchema?.components?.schemas;
+    if (!schemas) return null;
 
-import { z } from "zod";
-import { loadFalConfig, FAL_BASE_URL, DEFAULT_TIMEOUT } from "./config";
-import { safeToolExecute } from "../../utils/tool-wrapper";
+    // Find the input schema - usually named like "Ltx2ImageToVideoInput" or similar
+    const inputSchemaKey = Object.keys(schemas).find(
+      (key) =>
+        key.toLowerCase().includes("input") &&
+        !key.toLowerCase().includes("output")
+    );
+
+    if (!inputSchemaKey) return null;
+
+    const inputSchema = schemas[inputSchemaKey];
+    if (!inputSchema?.properties) return null;
+
+    // Extract simplified properties
+    const simplified: Record<string, any> = {};
+    for (const [propName, propDef] of Object.entries(
+      inputSchema.properties as Record<string, any>
+    )) {
+      simplified[propName] = {
+        type: propDef.type,
+        description: propDef.description,
+        ...(propDef.enum && { enum: propDef.enum }),
+        ...(propDef.default !== undefined && { default: propDef.default }),
+        ...(propDef.examples && { example: propDef.examples[0] }),
+      };
+    }
+
+    return simplified;
+  } catch (e) {
+    return null;
+  }
+}
 
 /**
  * Tool to list available generation presets and their intents.
+ * Dynamically fetches and caches input schemas from FAL API.
  */
 export const falListPresets = {
   name: "fal_list_presets",
   description:
-    "List all available generation presets, including their intents, input types, and output types. Use this to find the right preset for a task.",
-  parameters: z.object({}),
-  timeoutMs: 30000,
-  execute: async () => {
+    "The entry point for discovering fal.ai capabilities on this server. " +
+    "Lists all available generation presets, including their high-level 'intent' (e.g., 'Generate cinematic video'), " +
+    "input/output types, and INPUT SCHEMA with parameter details. Call this first when you need to perform an AI generation task.",
+  parameters: z.object({
+    refresh_schemas: z
+      .boolean()
+      .optional()
+      .describe("If true, re-fetch schemas from FAL API even if cached."),
+  }),
+  timeoutMs: 60000, // Allow more time for schema fetching
+  execute: async (args: { refresh_schemas?: boolean }) => {
     return safeToolExecute(async () => {
       const config = loadFalConfig();
+      let updated = false;
+
+      // 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;
+        console.log(
+          `[fal_list_presets] ${
+            preset.presetName
+          }: shouldFetch=${shouldFetch}, hasSchema=${!!preset.input_schema}, refresh=${
+            args.refresh_schemas
+          }`
+        );
+
+        if (shouldFetch) {
+          try {
+            const url = `https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=${preset.modelId}`;
+            console.log(`[fal_list_presets] Fetching schema from: ${url}`);
+            const response = await fetch(url, {
+              method: "GET",
+              signal: AbortSignal.timeout(10000),
+            });
+
+            if (response.ok) {
+              const openApiSchema = await response.json();
+              const simplified = extractInputSchema(openApiSchema);
+              console.log(
+                `[fal_list_presets] Extracted schema for ${preset.presetName}:`,
+                simplified ? Object.keys(simplified) : null
+              );
+
+              if (simplified) {
+                preset.input_schema = simplified;
+                updated = true;
+              }
+            } else {
+              console.log(
+                `[fal_list_presets] Fetch failed: ${response.status}`
+              );
+            }
+          } catch (e: any) {
+            console.log(
+              `[fal_list_presets] Error fetching schema for ${preset.presetName}:`,
+              e.message
+            );
+          }
+        }
+      }
+
+      // Save updated config if schemas were fetched
+      if (updated) {
+        console.log(`[fal_list_presets] Saving updated config...`);
+        const saved = saveFalConfig(config);
+        console.log(`[fal_list_presets] Config saved: ${saved}`);
+      }
+
+      // Return enriched preset list
       const summary = config.presets.map((p) => ({
         presetName: p.presetName,
         intent: p.intent,
         inputType: p.inputType,
         outputType: p.outputType,
         description: p.description,
+        inputSchema: p.input_schema,
       }));
+
       return JSON.stringify(summary, null, 2);
     }, "fal_list_presets");
   },
 };
 
 /**
- * Tool to get full details for a specific preset, including default parameters.
+ * Tool to get full details for a specific preset, including default parameters
+ * and real-time model metadata from fal.ai.
  */
 export const falGetPresetDetails = {
   name: "fal_get_preset_details",
   description:
-    "Get full details for a specific generation preset, including its model ID and default parameters.",
+    "Retrieve full details for a specific generation preset. " +
+    "This tool fetches both the local preset configuration (like 'defaultParams') " +
+    "and the live model metadata (schema, benchmarks, etc.) from fal.ai. " +
+    "Use this to understand the full capabilities and constraints of a model. " +
+    "ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS.",
   parameters: z.object({
-    preset_name: z.string().describe("The name of the preset to inspect"),
+    preset_name: z
+      .string()
+      .describe("The name of the preset to inspect (e.g., 'cinematic_image')."),
   }),
   timeoutMs: 30000,
   execute: async (args: { preset_name: string }) => {
@@ -51,7 +165,43 @@ export const falGetPresetDetails = {
       if (!preset) {
         throw new Error(`Preset '${args.preset_name}' not found.`);
       }
-      return JSON.stringify(preset, null, 2);
+
+      // Fetch live model metadata/schema from fal.ai API
+      // Based on: https://fal.ai/api/openapi/queue/openapi.json?endpoint_id={model_id}
+      let modelMetadata: any = null;
+      let schemaSource = "none";
+
+      try {
+        const url = `https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=${preset.modelId}`;
+        const schema = await publicRequest(url);
+
+        // Extract relevant schema parts if possible, or return full schema
+        if (schema) {
+          modelMetadata = schema;
+          schemaSource = "api";
+        }
+      } catch (e) {
+        // console.error(`Failed to fetch schema for ${preset.modelId}:`, e);
+        // Fallback to locally defined schema if available
+      }
+
+      // Fallback: If API failed or returned nothing, use manual schema from config
+      if (!modelMetadata && preset.input_schema) {
+        modelMetadata = preset.input_schema;
+        schemaSource = "local_config";
+      }
+
+      return JSON.stringify(
+        {
+          preset,
+          modelMetadata,
+          _meta: {
+            schemaSource,
+          },
+        },
+        null,
+        2
+      );
     }, "fal_get_preset_details");
   },
 };
@@ -73,22 +223,6 @@ async function publicRequest(url: string): Promise<any> {
   return response.json();
 }
 
-/**
- * Tool to retrieve the current full FAL configuration.
- */
-export const falGetConfig = {
-  name: "fal_get_config",
-  description: "Retrieve the full FAL configuration JSON file content.",
-  parameters: z.object({}),
-  timeoutMs: 30000,
-  execute: async () => {
-    return safeToolExecute(async () => {
-      const config = loadFalConfig();
-      return JSON.stringify(config, null, 2);
-    }, "fal_get_config");
-  },
-};
-
 /* 
 // ORIGINAL UNRESTRICTED TOOLS - Commented out for reference
 

package/src/tools/fal/storage.ts

@@ -38,9 +38,16 @@ function getMimeType(filePath: string): string {
  */
 export const falUploadFile = {
   name: "fal_upload_file",
-  description: "Upload a file to fal.ai CDN storage.",
+  description:
+    "Upload a local file (image, video, audio) to fal.ai CDN storage. " +
+    "CRITICAL: You MUST use this tool to upload local files before passing their URLs to generation tools in FAL. ONLY USE WHEN WORKING WITH FAL MODELS/PRESETS" +
+    "It returns a public 'file_url' which should be used as input for 'fal_generate'.",
   parameters: z.object({
-    path: z.string().describe("The absolute path to the file to upload"),
+    path: z
+      .string()
+      .describe(
+        "The absolute local path to the file to upload (e.g., '/Users/name/images/input.jpg')."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: { path: string }) => {

package/src/tools/gemini.ts

@@ -12,6 +12,10 @@ import { PassThrough } from "stream";
 import { getStorage } from "../storage";
 import { generateTimestampedFilename } from "../utils/filename";
 import { safeToolExecute } from "../utils/tool-wrapper";
+import {
+  resolveEnhancer,
+  listImageEnhancerPresets,
+} from "../utils/prompt-enhancer-presets";
 
 const ai = new GoogleGenAI({
   apiKey: process.env.GEMINI_API_KEY || "",
@@ -202,23 +206,43 @@ async function processVideoInput(
 export const geminiTextToImage = {
   name: "generateImage",
   description:
-    "Generate images from text prompts using Gemini image models with optional reference images. Returns the URL of the generated image.",
+    "Generate high-quality images from text prompts using Google's Imagen 3 model via Gemini. " +
+    "This tool is highly capable of following complex instructions. " +
+    "Best practices: " +
+    "1. Be descriptive: instead of 'a dog', use 'a golden retriever playing in a sunlit meadow, cinematic lighting'. " +
+    "2. Specify style: e.g., '3D render', 'oil painting', 'minimalist vector art'. " +
+    "3. Use reference images: you can provide existing images to guide the style or content. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
-    prompt: z.string().describe("Text description of the image to generate"),
+    prompt: z
+      .string()
+      .describe("Detailed text description of the image to generate."),
     aspect_ratio: z
       .string()
       .optional()
-      .describe("Aspect ratio: 1:1, 3:4, 4:3, 9:16, or 16:9 (default 9:16)"),
+      .describe(
+        "Supported ratios: 1:1, 3:4, 4:3, 9:16, or 16:9. Default is 9:16."
+      ),
     output_path: z
       .string()
       .optional()
       .describe(
-        "File path to save the generated image (optional, auto-generated if not provided)"
+        "Optional: specific local path or filename to save the image (e.g., 'outputs/hero.png'). " +
+          "If omitted, a timestamped filename is generated automatically."
       ),
     reference_images: z
       .array(z.string())
       .optional()
-      .describe("Optional reference image file paths to guide generation"),
+      .describe(
+        "Optional: local paths or URLs of images to use as visual references for style or composition."
+      ),
+    enhancer_preset: z
+      .string()
+      .optional()
+      .describe(
+        "Optional: Name of a prompt enhancer preset to apply (e.g., 'cinematic', 'photorealistic', 'anime'). " +
+          "Automatically enhances the prompt with professional style modifiers."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: {
@@ -226,10 +250,20 @@ export const geminiTextToImage = {
     aspect_ratio?: string;
     output_path?: string;
     reference_images?: string[];
+    enhancer_preset?: string;
   }) => {
     return safeToolExecute(async () => {
       try {
-        const contents: any[] = [args.prompt];
+        // Apply prompt enhancement if preset specified
+        let enhancedPrompt = args.prompt;
+        if (args.enhancer_preset) {
+          const enhancer = resolveEnhancer(args.enhancer_preset);
+          if (enhancer.hasTransformations()) {
+            enhancedPrompt = enhancer.enhance(args.prompt);
+          }
+        }
+
+        const contents: any[] = [enhancedPrompt];
 
         if (args.reference_images && Array.isArray(args.reference_images)) {
           for (const refPath of args.reference_images) {
@@ -297,18 +331,40 @@ export const geminiTextToImage = {
 export const geminiEditImage = {
   name: "editImage",
   description:
-    "Edit existing images with text instructions using Gemini 3 Pro Image Preview",
+    "Modify or edit an existing image based on text instructions using Google's Imagen 3 model via Gemini. " +
+    "This can be used for inpainting (changing specific parts), style transfer, or adding/removing elements. " +
+    "Describe the desired changes relative to the source image (e.g., 'Change the white shirt to a blue one' or 'Add a cat sitting on the sofa'). " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
-    image_path: z.string().describe("Path to the source image file"),
-    prompt: z.string().describe("Text instructions for editing the image"),
+    image_path: z
+      .string()
+      .describe(
+        "Absolute local path or URL to the source image file to be edited."
+      ),
+    prompt: z
+      .string()
+      .describe(
+        "Instructional text describing the edits or modifications required."
+      ),
     output_path: z
       .string()
       .optional()
-      .describe("File path to save the edited image"),
+      .describe(
+        "Optional: specific local path to save the edited result. Defaults to generated timestamp."
+      ),
     reference_images: z
       .array(z.string())
       .optional()
-      .describe("Additional image paths for reference"),
+      .describe(
+        "Optional: additional images to guide the edit (e.g., to reference a specific character or object style)."
+      ),
+    enhancer_preset: z
+      .string()
+      .optional()
+      .describe(
+        "Optional: Name of a prompt enhancer preset to apply (e.g., 'cinematic', 'photorealistic'). " +
+          "Enhances the edit instructions with professional style modifiers."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: {
@@ -316,11 +372,21 @@ export const geminiEditImage = {
     prompt: string;
     output_path?: string;
     reference_images?: string[];
+    enhancer_preset?: string;
   }) => {
     return safeToolExecute(async () => {
       try {
+        // Apply prompt enhancement if preset specified
+        let enhancedPrompt = args.prompt;
+        if (args.enhancer_preset) {
+          const enhancer = resolveEnhancer(args.enhancer_preset);
+          if (enhancer.hasTransformations()) {
+            enhancedPrompt = enhancer.enhance(args.prompt);
+          }
+        }
+
         const imagePart = await fileToGenerativePart(args.image_path);
-        const contents: any[] = [args.prompt, imagePart];
+        const contents: any[] = [enhancedPrompt, imagePart];
 
         if (args.reference_images) {
           for (const refPath of args.reference_images) {
@@ -378,12 +444,19 @@ export const geminiEditImage = {
 export const geminiAnalyzeImages = {
   name: "analyzeImages",
   description:
-    "Analyze and describe images using Gemini 2.5 Pro with advanced multimodal understanding",
+    "Perform advanced multimodal analysis on one or more images using Google's Gemini 2.5 Pro model. " +
+    "Use this for complex reasoning, visual question answering, OCR, or describing scenes in detail. " +
+    "You can compare multiple images by providing them in the array. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
     image_paths: z
       .array(z.string())
-      .describe("Array of image file paths to analyze"),
-    prompt: z.string().describe("Text prompt or question about the images"),
+      .describe(
+        "An array of absolute local file paths or publicly accessible URLs to analyze."
+      ),
+    prompt: z
+      .string()
+      .describe("The question, query, or instruction to apply to the images."),
   }),
   timeoutMs: 300000,
   execute: async (args: { image_paths: string[]; prompt: string }) => {
@@ -447,19 +520,22 @@ export const geminiAnalyzeImages = {
 export const geminiSingleSpeakerTts = {
   name: "generateSpeech",
   description:
-    "Generate single speaker voice audio from text using Gemini 2.5 Pro Preview TTS model",
+    "Convert text to natural-sounding speech using Google's Gemini 2.5 Pro Preview TTS model. " +
+    "This tool generates a single speaker's voice in a WAV format. " +
+    "Best for long-form narration or simple voiceovers. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
-    text: z.string().describe("Text to convert to speech"),
+    text: z.string().describe("The text content to be converted into speech."),
     voice_name: z
       .string()
       .describe(
-        "Voice name from supported options. Use Kore, Erinome or Despina for the female voices and Enceladus for male."
+        "Supported voices: 'Despina' (Female, versatile), 'Kore' (Female, calm), 'Erinome' (Female, expressive), or 'Enceladus' (Male, neutral)."
       ),
     output_path: z
       .string()
       .optional()
       .describe(
-        "Output WAV file path (optional, defaults to timestamp-based filename)"
+        "Optional: Output WAV file path. Defaults to a timestamped filename in the output directory."
       ),
   }),
   timeoutMs: 300000,
@@ -518,37 +594,41 @@ export const geminiSingleSpeakerTts = {
 export const geminiAnalyzeVideos = {
   name: "analyzeVideos",
   description:
-    "Analyze and understand video content using Gemini 2.5 Flash model. Intelligently handles YouTube URLs and local videos (files <20MB processed inline, ≥20MB uploaded via File API). Supports timestamp queries, clipping, and custom frame rates with default 5 FPS for local videos to optimize processing.",
+    "Comprehensive video understanding using Google's Gemini 2.5 Pro model. " +
+    "Capable of analyzing both longitudinal content (YouTube) and specific local files. " +
+    "Supports time-aware queries (e.g., 'What color is the car at 02:45?'), clipping, and advanced visual reasoning over video streams. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
     video_inputs: z
       .array(z.string())
       .describe(
-        "Array of video inputs - mix of local file paths and YouTube URLs (max 10 videos). Local files <20MB processed inline, larger files uploaded via File API automatically."
+        "An array containing absolute paths to local videos or YouTube URLs. Max 10 per request. " +
+          "Note: Local files are automatically optimized for processing."
       ),
     prompt: z
       .string()
       .describe(
-        "Text prompt or question about the videos. Use MM:SS format for timestamp references (e.g., 'What happens at 01:30?')."
+        "The question or instruction regarding the video. Use MM:SS or HH:MM:SS for precise time references."
       ),
     fps: z
       .number()
       .optional()
       .describe(
-        "Frame rate for video processing (default: 5 FPS for local videos to reduce file size, 1 FPS for YouTube URLs)"
+        "Optional: Target frames per second for processing. Lower FPS (1-5) is recommended for long videos to save tokens."
       ),
     start_offset: z
       .string()
       .optional()
-      .describe("Clip start time in seconds with 's' suffix (e.g., '40s')"),
+      .describe("Start time of the segment to analyze (e.g., '10s', '01:30')."),
     end_offset: z
       .string()
       .optional()
-      .describe("Clip end time in seconds with 's' suffix (e.g., '80s')"),
+      .describe("End time of the segment to analyze (e.g., '20s', '02:00')."),
     media_resolution: z
       .string()
       .optional()
       .describe(
-        "Media resolution: 'default' or 'low' (low resolution uses ~100 tokens/sec vs 300 tokens/sec)"
+        "Processing resolution: 'default' or 'low'. 'low' significantly reduces token usage for simple visual tasks."
       ),
   }),
   timeoutMs: 300000,