@mixio-pro/kalaasetu-mcp 1.1.3 → 1.2.0

package/package.json

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

package/src/index.ts

@@ -1,12 +1,13 @@
 #!/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 {
-  falListModels,
-  falSearchModels,
-  falGetSchema,
-  falGenerateContent,
+  falListPresets,
+  falGetPresetDetails,
+  falGetConfig,
+  falGenerate,
   falGetResult,
   falGetStatus,
   falCancelRequest,
@@ -15,7 +16,7 @@ import {
 
 const server = new FastMCP({
   name: "Kalaasetu MCP Server",
-  version: "1.1.0",
+  version: pkg.version as any,
 });
 
 // Gemini Image Tools
@@ -40,10 +41,10 @@ server.addTool(imageToVideo);
 // server.addTool(perplexityVideos);
 
 // Fal AI Tools
-server.addTool(falListModels);
-server.addTool(falSearchModels);
-server.addTool(falGetSchema);
-server.addTool(falGenerateContent);
+server.addTool(falGetConfig);
+server.addTool(falListPresets);
+server.addTool(falGetPresetDetails);
+server.addTool(falGenerate);
 server.addTool(falGetResult);
 server.addTool(falGetStatus);
 server.addTool(falCancelRequest);

package/src/test-context.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { safeToolExecute } from "./utils/tool-wrapper";
+
+async function runTest() {
+  console.log("Running Error Context Verification Test...");
+
+  // 1. Mock Schema Validation Error
+  const schema = z.object({
+    prompt: z.string(),
+    count: z.number().min(1).max(5),
+  });
+
+  const mockToolWithValidation = async (args: any) => {
+    // Simulate what happens in a real tool when Zod parsing fails inside the execute block
+    // OR if we manually parse and it fails
+    // Most tools currently don't re-parse inside execute because MCP handles it?
+    // Wait, the tools define `parameters` schema, but the `execute` function receives `args`.
+    // The MCP server framework usually does the validation BEFORE calling execute.
+    // BUT if we look at the code, some tools do manual checks or parsing.
+
+    // Let's simulate a manual validation failure inside execute, or a deep validation failure
+    try {
+      schema.parse(args);
+    } catch (error) {
+      throw error;
+    }
+    return "success";
+  };
+
+  const zodResult = await safeToolExecute(
+    async () => mockToolWithValidation({ prompt: 123, count: 10 }),
+    "ZodTool"
+  );
+  console.log("\n--- Zod Error Result ---");
+  console.log(JSON.stringify(zodResult, null, 2));
+
+  // 2. Mock API Error with Status
+  const mockToolWithApiError = async () => {
+    // Simulate a fetch error structure
+    const err: any = new Error("API request failed");
+    err.status = 429;
+    err.statusText = "Too Many Requests";
+    err.responseBody = "Rate limit exceeded. Retry in 60s.";
+    throw err;
+  };
+
+  const apiResult = await safeToolExecute(mockToolWithApiError, "ApiTool");
+  console.log("\n--- API Error Result ---");
+  console.log(JSON.stringify(apiResult, null, 2));
+}
+
+runTest();

package/src/test-error-handling.ts

@@ -0,0 +1,31 @@
+import { safeToolExecute } from "./utils/tool-wrapper";
+
+async function runTest() {
+  console.log("Running Error Handling Verification Test...");
+
+  // Mock tool that throws an error
+  const mockTool = async () => {
+    throw new Error("Simulated tool failure");
+  };
+
+  const result = await safeToolExecute(mockTool, "MockTool");
+
+  console.log("Result:", JSON.stringify(result, null, 2));
+
+  if (
+    result.isError === true &&
+    result.content &&
+    result.content[0]?.text.includes(
+      "Tool execution failed in MockTool: Simulated tool failure"
+    )
+  ) {
+    console.log(
+      "✅ Verification PASSED: Error was correctly caught and formatted."
+    );
+  } else {
+    console.error("❌ Verification FAILED: Unexpected result format.");
+    process.exit(1);
+  }
+}
+
+runTest();

package/src/tools/fal/config.ts

@@ -1,7 +1,8 @@
 /**
- * Configuration module for the fal.ai MCP server.
  * Provides centralized configuration settings for API endpoints, timeouts, and server metadata.
  */
+import * as fs from "fs";
+import * as path from "path";
 
 // API URLs
 export const FAL_BASE_URL = "https://fal.ai/api";
@@ -32,3 +33,96 @@ export function getApiKey(): string {
   }
   return apiKey;
 }
+
+/**
+ * Interface for a FAL preset configuration.
+ */
+export interface FalPresetConfig {
+  presetName: string;
+  intent: string;
+  modelId: string;
+  description?: string;
+  defaultParams?: Record<string, any>;
+  inputType?: "text" | "image" | "video" | "audio" | "custom";
+  outputType?: "image" | "video" | "audio" | "text" | "custom";
+}
+
+/**
+ * Interface for the FAL configuration file.
+ */
+export interface FalConfig {
+  presets: FalPresetConfig[];
+}
+
+/**
+ * Default fallback presets in case no config file is provided.
+ */
+export const DEFAULT_PRESETS: FalPresetConfig[] = [
+  {
+    presetName: "cinematic_image",
+    intent: "Generate high-quality cinematic images from text prompts",
+    modelId: "fal-ai/flux/pro/v1.1",
+    description: "FLUX.1 [pro] v1.1 for state-of-the-art image generation",
+    defaultParams: {
+      image_size: "landscape_4_3",
+    },
+    inputType: "text",
+    outputType: "image",
+  },
+  {
+    presetName: "cinematic_video",
+    intent: "Generate realistic cinematic video from text or image",
+    modelId: "fal-ai/luma-dream-machine",
+    description: "Luma Dream Machine for high-quality video generation",
+    inputType: "custom",
+    outputType: "video",
+  },
+  {
+    presetName: "creative_image",
+    intent: "Generate creative or artistic images with high flexibility",
+    modelId: "fal-ai/stable-diffusion-v35-large",
+    description: "Stable Diffusion 3.5 Large for diverse image styles",
+    inputType: "text",
+    outputType: "image",
+  },
+];
+
+/**
+ * Load the FAL configuration from a JSON file.
+ * Defaults to DEFAULT_PRESETS if no path is provided or if the file cannot be read.
+ */
+export function loadFalConfig(): FalConfig {
+  const configPath = process.env.FAL_CONFIG_JSON_PATH;
+
+  if (!configPath) {
+    console.error(
+      "FAL_CONFIG_JSON_PATH not set. Using internal default presets."
+    );
+    return { presets: DEFAULT_PRESETS };
+  }
+
+  try {
+    const absolutePath = path.isAbsolute(configPath)
+      ? configPath
+      : path.join(process.cwd(), configPath);
+
+    if (!fs.existsSync(absolutePath)) {
+      console.error(
+        `FAL config file not found at ${absolutePath}. Using default presets.`
+      );
+      return { presets: DEFAULT_PRESETS };
+    }
+
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const config = JSON.parse(fileContent) as FalConfig;
+
+    if (!config.presets || !Array.isArray(config.presets)) {
+      throw new Error("Invalid FAL config: 'presets' must be an array.");
+    }
+
+    return config;
+  } catch (error: any) {
+    console.error(`Error loading FAL config: ${error.message}`);
+    return { presets: DEFAULT_PRESETS };
+  }
+}

package/src/tools/fal/generate.ts

@@ -4,11 +4,14 @@
  */
 
 import { z } from "zod";
+import { safeToolExecute } from "../../utils/tool-wrapper";
 import {
   FAL_QUEUE_URL,
   FAL_DIRECT_URL,
   AUTHENTICATED_TIMEOUT,
   getApiKey,
+  loadFalConfig,
+  type FalPresetConfig,
 } from "./config";
 
 /**
@@ -56,17 +59,20 @@ function sanitizeParameters(
 }
 
 /**
- * Generate content using a fal.ai model.
+ * Unified generation tool using presets defined in configuration.
  */
-export const falGenerateContent = {
-  name: "fal_generate_content",
+export const falGenerate = {
+  name: "fal_generate",
   description:
-    "Generate content using any fal.ai model. Supports both direct execution and queued execution for long-running tasks.",
+    "Generate content using a named preset and optional parameters. Use fal_list_presets to discover available intents and preset names.",
   parameters: z.object({
-    model: z.string().describe('The model ID to use (e.g., "fal-ai/flux/dev")'),
+    preset_name: z
+      .string()
+      .describe("The name of the preset to use (e.g., 'cinematic_image')"),
     parameters: z
       .record(z.string(), z.any())
-      .describe("Model-specific parameters as a dictionary"),
+      .optional()
+      .describe("Optional model-specific parameters to override defaults"),
     queue: z
       .boolean()
       .optional()
@@ -75,23 +81,43 @@ export const falGenerateContent = {
         "Whether to use the queuing system for long-running tasks. Default: false"
       ),
   }),
+  timeoutMs: 300000,
   execute: async (args: {
-    model: string;
-    parameters: Record<string, any>;
+    preset_name: string;
+    parameters?: Record<string, any>;
     queue?: boolean;
   }) => {
-    const sanitizedParams = sanitizeParameters(args.parameters);
+    return safeToolExecute(async () => {
+      const config = loadFalConfig();
+      const preset = config.presets.find(
+        (p) => p.presetName === args.preset_name
+      );
 
-    const baseUrl = args.queue ? FAL_QUEUE_URL : FAL_DIRECT_URL;
-    const url = `${baseUrl}/${args.model}`;
+      if (!preset) {
+        throw new Error(
+          `Preset '${args.preset_name}' not found. Use fal_list_presets to see available options.`
+        );
+      }
 
-    console.error(`[fal_generate] Submitting request to ${url}...`);
+      // Merge defaults from config with runtime overrides
+      const mergedParams = {
+        ...(preset.defaultParams || {}),
+        ...(args.parameters || {}),
+      };
 
-    const result = await authenticatedRequest(url, "POST", sanitizedParams);
+      const sanitizedParams = sanitizeParameters(mergedParams);
 
-    console.error(`[fal_generate] Request completed successfully`);
+      const baseUrl = args.queue ? FAL_QUEUE_URL : FAL_DIRECT_URL;
+      const url = `${baseUrl}/${preset.modelId}`;
 
-    return JSON.stringify(result);
+      console.error(
+        `[fal_generate] Using preset '${args.preset_name}' on model ${preset.modelId}...`
+      );
+
+      const result = await authenticatedRequest(url, "POST", sanitizedParams);
+
+      return JSON.stringify(result);
+    }, "fal_generate");
   },
 };
 
@@ -104,6 +130,7 @@ export const falGetResult = {
   parameters: z.object({
     url: z.string().describe("The response_url from a queued request"),
   }),
+  timeoutMs: 300000,
   execute: async (args: { url: string }) => {
     const result = await authenticatedRequest(args.url, "GET");
     return JSON.stringify(result);
@@ -119,6 +146,7 @@ export const falGetStatus = {
   parameters: z.object({
     url: z.string().describe("The status_url from a queued request"),
   }),
+  timeoutMs: 300000,
   execute: async (args: { url: string }) => {
     const result = await authenticatedRequest(args.url, "GET");
     return JSON.stringify(result);
@@ -134,8 +162,11 @@ export const falCancelRequest = {
   parameters: z.object({
     url: z.string().describe("The cancel_url from a queued request"),
   }),
+  timeoutMs: 300000,
   execute: async (args: { url: string }) => {
-    const result = await authenticatedRequest(args.url, "PUT");
-    return JSON.stringify(result);
+    return safeToolExecute(async () => {
+      const result = await authenticatedRequest(args.url, "PUT");
+      return JSON.stringify(result);
+    }, "fal_cancel_request");
   },
 };

package/src/tools/fal/index.ts

@@ -3,9 +3,9 @@
  * Export all fal.ai tools for registration with the MCP server.
  */
 
-export { falListModels, falSearchModels, falGetSchema } from "./models";
+export { falListPresets, falGetPresetDetails, falGetConfig } from "./models";
 export {
-  falGenerateContent,
+  falGenerate,
   falGetResult,
   falGetStatus,
   falCancelRequest,

package/src/tools/fal/models.ts

@@ -1,13 +1,63 @@
 /**
  * Models module for fal.ai MCP server.
- * Provides tools for listing, searching, and retrieving schemas for fal.ai models.
+ * Provides tools for retrieving information about configured fal.ai models.
  */
 
 import { z } from "zod";
-import { FAL_BASE_URL, DEFAULT_TIMEOUT } from "./config";
+import { loadFalConfig, FAL_BASE_URL, DEFAULT_TIMEOUT } from "./config";
+import { safeToolExecute } from "../../utils/tool-wrapper";
 
 /**
- * Make a non-authenticated request to fal.ai API.
+ * Tool to list available generation presets and their intents.
+ */
+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 () => {
+    return safeToolExecute(async () => {
+      const config = loadFalConfig();
+      const summary = config.presets.map((p) => ({
+        presetName: p.presetName,
+        intent: p.intent,
+        inputType: p.inputType,
+        outputType: p.outputType,
+        description: p.description,
+      }));
+      return JSON.stringify(summary, null, 2);
+    }, "fal_list_presets");
+  },
+};
+
+/**
+ * Tool to get full details for a specific preset, including default parameters.
+ */
+export const falGetPresetDetails = {
+  name: "fal_get_preset_details",
+  description:
+    "Get full details for a specific generation preset, including its model ID and default parameters.",
+  parameters: z.object({
+    preset_name: z.string().describe("The name of the preset to inspect"),
+  }),
+  timeoutMs: 30000,
+  execute: async (args: { preset_name: string }) => {
+    return safeToolExecute(async () => {
+      const config = loadFalConfig();
+      const preset = config.presets.find(
+        (p) => p.presetName === args.preset_name
+      );
+      if (!preset) {
+        throw new Error(`Preset '${args.preset_name}' not found.`);
+      }
+      return JSON.stringify(preset, null, 2);
+    }, "fal_get_preset_details");
+  },
+};
+
+/**
+ * Helper for making public API requests to fal.ai
  */
 async function publicRequest(url: string): Promise<any> {
   const response = await fetch(url, {
@@ -24,8 +74,24 @@ async function publicRequest(url: string): Promise<any> {
 }
 
 /**
- * List available models on fal.ai with optional pagination.
+ * 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
+
 export const falListModels = {
   name: "fal_list_models",
   description:
@@ -40,6 +106,7 @@ export const falListModels = {
       .optional()
       .describe("The total number of models to retrieve per page"),
   }),
+  timeoutMs: 300000,
   execute: async (args: { page?: number; total?: number }) => {
     let url = `${FAL_BASE_URL}/models`;
 
@@ -56,15 +123,13 @@ export const falListModels = {
   },
 };
 
-/**
- * Search for models on fal.ai based on keywords.
- */
 export const falSearchModels = {
   name: "fal_search_models",
   description: "Search for models on fal.ai based on keywords.",
   parameters: z.object({
     keywords: z.string().describe("The search terms to find models"),
   }),
+  timeoutMs: 300000,
   execute: async (args: { keywords: string }) => {
     const url = `${FAL_BASE_URL}/models?keywords=${encodeURIComponent(
       args.keywords
@@ -73,23 +138,4 @@ export const falSearchModels = {
     return JSON.stringify(result);
   },
 };
-
-/**
- * Get the OpenAPI schema for a specific model.
- */
-export const falGetSchema = {
-  name: "fal_get_schema",
-  description: "Get the OpenAPI schema for a specific fal.ai model.",
-  parameters: z.object({
-    model_id: z
-      .string()
-      .describe('The ID of the model (e.g., "fal-ai/flux/dev")'),
-  }),
-  execute: async (args: { model_id: string }) => {
-    const url = `${FAL_BASE_URL}/openapi/queue/openapi.json?endpoint_id=${encodeURIComponent(
-      args.model_id
-    )}`;
-    const result = await publicRequest(url);
-    return JSON.stringify(result);
-  },
-};
+*/

package/src/tools/fal/storage.ts

@@ -5,6 +5,7 @@
 
 import { z } from "zod";
 import * as fs from "fs";
+import { safeToolExecute } from "../../utils/tool-wrapper";
 import * as path from "path";
 import { FAL_REST_URL, AUTHENTICATED_TIMEOUT, getApiKey } from "./config";
 
@@ -41,76 +42,79 @@ export const falUploadFile = {
   parameters: z.object({
     path: z.string().describe("The absolute path to the file to upload"),
   }),
+  timeoutMs: 300000,
   execute: async (args: { path: string }) => {
-    // Validate file exists
-    if (!fs.existsSync(args.path)) {
-      throw new Error(`File not found: ${args.path}`);
-    }
+    return safeToolExecute(async () => {
+      // Validate file exists
+      if (!fs.existsSync(args.path)) {
+        throw new Error(`File not found: ${args.path}`);
+      }
 
-    const filename = path.basename(args.path);
-    const fileSize = fs.statSync(args.path).size;
-    const contentType = getMimeType(args.path);
+      const filename = path.basename(args.path);
+      const fileSize = fs.statSync(args.path).size;
+      const contentType = getMimeType(args.path);
 
-    // Step 1: Initiate upload
-    const initiateUrl = `${FAL_REST_URL}/storage/upload/initiate?storage_type=fal-cdn-v3`;
-    const initiatePayload = {
-      content_type: contentType,
-      file_name: filename,
-    };
+      // Step 1: Initiate upload
+      const initiateUrl = `${FAL_REST_URL}/storage/upload/initiate?storage_type=fal-cdn-v3`;
+      const initiatePayload = {
+        content_type: contentType,
+        file_name: filename,
+      };
 
-    console.error(`[fal_upload] Initiating upload for ${filename}...`);
+      console.error(`[fal_upload] Initiating upload for ${filename}...`);
 
-    const initiateResponse = await fetch(initiateUrl, {
-      method: "POST",
-      headers: {
-        Authorization: `Key ${getApiKey()}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(initiatePayload),
-      signal: AbortSignal.timeout(AUTHENTICATED_TIMEOUT),
-    });
+      const initiateResponse = await fetch(initiateUrl, {
+        method: "POST",
+        headers: {
+          Authorization: `Key ${getApiKey()}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(initiatePayload),
+        signal: AbortSignal.timeout(AUTHENTICATED_TIMEOUT),
+      });
 
-    if (!initiateResponse.ok) {
-      const errorText = await initiateResponse.text();
-      throw new Error(
-        `[${initiateResponse.status}] Failed to initiate upload: ${errorText}`
-      );
-    }
+      if (!initiateResponse.ok) {
+        const errorText = await initiateResponse.text();
+        throw new Error(
+          `[${initiateResponse.status}] Failed to initiate upload: ${errorText}`
+        );
+      }
 
-    const initiateData = (await initiateResponse.json()) as {
-      file_url: string;
-      upload_url: string;
-    };
-    const { file_url, upload_url } = initiateData;
+      const initiateData = (await initiateResponse.json()) as {
+        file_url: string;
+        upload_url: string;
+      };
+      const { file_url, upload_url } = initiateData;
 
-    // Step 2: Upload file content
-    console.error(`[fal_upload] Uploading file content...`);
+      // Step 2: Upload file content
+      console.error(`[fal_upload] Uploading file content...`);
 
-    const fileContent = fs.readFileSync(args.path);
+      const fileContent = fs.readFileSync(args.path);
 
-    const uploadResponse = await fetch(upload_url, {
-      method: "PUT",
-      headers: {
-        "Content-Type": contentType,
-      },
-      body: fileContent,
-      signal: AbortSignal.timeout(AUTHENTICATED_TIMEOUT),
-    });
+      const uploadResponse = await fetch(upload_url, {
+        method: "PUT",
+        headers: {
+          "Content-Type": contentType,
+        },
+        body: fileContent,
+        signal: AbortSignal.timeout(AUTHENTICATED_TIMEOUT),
+      });
 
-    if (!uploadResponse.ok) {
-      const errorText = await uploadResponse.text();
-      throw new Error(
-        `[${uploadResponse.status}] Failed to upload file: ${errorText}`
-      );
-    }
+      if (!uploadResponse.ok) {
+        const errorText = await uploadResponse.text();
+        throw new Error(
+          `[${uploadResponse.status}] Failed to upload file: ${errorText}`
+        );
+      }
 
-    console.error(`[fal_upload] Upload completed successfully`);
+      console.error(`[fal_upload] Upload completed successfully`);
 
-    return JSON.stringify({
-      file_url,
-      file_name: filename,
-      file_size: fileSize,
-      content_type: contentType,
-    });
+      return JSON.stringify({
+        file_url,
+        file_name: filename,
+        file_size: fileSize,
+        content_type: contentType,
+      });
+    }, "fal_upload_file");
   },
 };