@mixio-pro/kalaasetu-mcp 1.1.2 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixio-pro/kalaasetu-mcp",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "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,21 +1,22 @@
 #!/usr/bin/env bun
 import { FastMCP } from "fastmcp";
-import {
-  geminiTextToImage,
-  geminiEditImage,
-  geminiAnalyzeImages,
-  geminiSingleSpeakerTts,
-  geminiAnalyzeVideos,
-} from "./tools/gemini";
-import { analyzeYoutubeVideo } from "./tools/youtube";
+import pkg from "../package.json";
+import { geminiEditImage, geminiTextToImage } from "./tools/gemini";
 import { imageToVideo } from "./tools/image-to-video";
-import { infinitalk } from "./tools/infinitalk";
-import { hunyuanAvatar } from "./tools/hunyuan-avatar";
-import { perplexityImages, perplexityVideos } from "./tools/perplexity";
+import {
+  falListModels,
+  falSearchModels,
+  falGetSchema,
+  falGenerateContent,
+  falGetResult,
+  falGetStatus,
+  falCancelRequest,
+  falUploadFile,
+} from "./tools/fal";
 
 const server = new FastMCP({
   name: "Kalaasetu MCP Server",
-  version: "1.1.0",
+  version: pkg.version as any,
 });
 
 // Gemini Image Tools
@@ -27,7 +28,7 @@ server.addTool(geminiEditImage);
 // server.addTool(geminiSingleSpeakerTts);
 
 // Gemini Video Analysis Tool
-server.addTool(geminiAnalyzeVideos);
+// server.addTool(geminiAnalyzeVideos);
 
 // YouTube Analyzer Tool
 // server.addTool(analyzeYoutubeVideo);
@@ -35,16 +36,20 @@ server.addTool(geminiAnalyzeVideos);
 // Vertex AI Image-to-Video Tool
 server.addTool(imageToVideo);
 
-// FAL AI Infinitalk Tool
-// server.addTool(infinitalk);
-
-// FAL AI Hunyuan Avatar Tool
-// server.addTool(hunyuanAvatar);
-
 // Perplexity Search Tools
 // server.addTool(perplexityImages);
 // server.addTool(perplexityVideos);
 
+// Fal AI Tools
+// server.addTool(falListModels);
+// server.addTool(falSearchModels);
+// server.addTool(falGetSchema);
+// server.addTool(falGenerateContent);
+// server.addTool(falGetResult);
+// server.addTool(falGetStatus);
+// server.addTool(falCancelRequest);
+// server.addTool(falUploadFile);
+
 server.start({
   transportType: "stdio",
 });

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

@@ -0,0 +1,34 @@
+/**
+ * Configuration module for the fal.ai MCP server.
+ * Provides centralized configuration settings for API endpoints, timeouts, and server metadata.
+ */
+
+// API URLs
+export const FAL_BASE_URL = "https://fal.ai/api";
+export const FAL_QUEUE_URL = "https://queue.fal.run";
+export const FAL_DIRECT_URL = "https://fal.run";
+export const FAL_REST_URL = "https://rest.alpha.fal.ai";
+
+// Timeouts (in milliseconds)
+export const DEFAULT_TIMEOUT = 30000;
+export const AUTHENTICATED_TIMEOUT = 600000; // 10 minutes for long-running operations
+
+// Environment variable names
+export const API_KEY_ENV_VAR = "FAL_KEY";
+
+// Server metadata
+export const SERVER_NAME = "fal.ai MCP Server";
+export const SERVER_DESCRIPTION =
+  "Access fal.ai models and generate content through MCP";
+export const SERVER_VERSION = "1.0.0";
+
+/**
+ * Get the fal.ai API key from environment variables.
+ */
+export function getApiKey(): string {
+  const apiKey = process.env[API_KEY_ENV_VAR];
+  if (!apiKey) {
+    throw new Error(`${API_KEY_ENV_VAR} environment variable not set`);
+  }
+  return apiKey;
+}

package/src/tools/fal/generate.ts

@@ -0,0 +1,146 @@
+/**
+ * Generate module for fal.ai MCP server.
+ * Provides tools for generating content and managing queue operations with fal.ai models.
+ */
+
+import { z } from "zod";
+import { safeToolExecute } from "../../utils/tool-wrapper";
+import {
+  FAL_QUEUE_URL,
+  FAL_DIRECT_URL,
+  AUTHENTICATED_TIMEOUT,
+  getApiKey,
+} from "./config";
+
+/**
+ * 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();
+    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)
+  );
+}
+
+/**
+ * Generate content using a fal.ai model.
+ */
+export const falGenerateContent = {
+  name: "fal_generate_content",
+  description:
+    "Generate content using any fal.ai model. Supports both direct execution and queued execution for long-running tasks.",
+  parameters: z.object({
+    model: z.string().describe('The model ID to use (e.g., "fal-ai/flux/dev")'),
+    parameters: z
+      .record(z.string(), z.any())
+      .describe("Model-specific parameters as a dictionary"),
+    queue: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe(
+        "Whether to use the queuing system for long-running tasks. Default: false"
+      ),
+  }),
+  execute: async (args: {
+    model: string;
+    parameters: Record<string, any>;
+    queue?: boolean;
+  }) => {
+    return safeToolExecute(async () => {
+      const sanitizedParams = sanitizeParameters(args.parameters);
+
+      const baseUrl = args.queue ? FAL_QUEUE_URL : FAL_DIRECT_URL;
+      const url = `${baseUrl}/${args.model}`;
+
+      console.error(`[fal_generate] Submitting request to ${url}...`);
+
+      const result = await authenticatedRequest(url, "POST", sanitizedParams);
+
+      console.error(`[fal_generate] Request completed successfully`);
+
+      return JSON.stringify(result);
+    }, "fal_generate_content");
+  },
+};
+
+/**
+ * Get the result of a queued request.
+ */
+export const falGetResult = {
+  name: "fal_get_result",
+  description: "Get the result of a queued fal.ai request.",
+  parameters: z.object({
+    url: z.string().describe("The response_url from a queued request"),
+  }),
+  execute: async (args: { url: string }) => {
+    const result = await authenticatedRequest(args.url, "GET");
+    return JSON.stringify(result);
+  },
+};
+
+/**
+ * Check the status of a queued request.
+ */
+export const falGetStatus = {
+  name: "fal_get_status",
+  description: "Check the status of a queued fal.ai request.",
+  parameters: z.object({
+    url: z.string().describe("The status_url from a queued request"),
+  }),
+  execute: async (args: { url: string }) => {
+    const result = await authenticatedRequest(args.url, "GET");
+    return JSON.stringify(result);
+  },
+};
+
+/**
+ * Cancel a queued request.
+ */
+export const falCancelRequest = {
+  name: "fal_cancel_request",
+  description: "Cancel a queued fal.ai request.",
+  parameters: z.object({
+    url: z.string().describe("The cancel_url from a queued request"),
+  }),
+  execute: async (args: { url: string }) => {
+    return safeToolExecute(async () => {
+      const result = await authenticatedRequest(args.url, "PUT");
+      return JSON.stringify(result);
+    }, "fal_cancel_request");
+  },
+};

package/src/tools/fal/index.ts

@@ -0,0 +1,14 @@
+/**
+ * fal.ai MCP Tools
+ * Export all fal.ai tools for registration with the MCP server.
+ */
+
+export { falListModels, falSearchModels, falGetSchema } from "./models";
+export {
+  falGenerateContent,
+  falGetResult,
+  falGetStatus,
+  falCancelRequest,
+} from "./generate";
+export { falUploadFile } from "./storage";
+export { SERVER_NAME, SERVER_DESCRIPTION, SERVER_VERSION } from "./config";

package/src/tools/fal/models.ts

@@ -0,0 +1,95 @@
+/**
+ * Models module for fal.ai MCP server.
+ * Provides tools for listing, searching, and retrieving schemas for fal.ai models.
+ */
+
+import { z } from "zod";
+import { FAL_BASE_URL, DEFAULT_TIMEOUT } from "./config";
+
+/**
+ * Make a non-authenticated request to fal.ai API.
+ */
+async function publicRequest(url: string): Promise<any> {
+  const response = await fetch(url, {
+    method: "GET",
+    signal: AbortSignal.timeout(DEFAULT_TIMEOUT),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`[${response.status}] API error: ${errorText}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * List available models on fal.ai with optional pagination.
+ */
+export const falListModels = {
+  name: "fal_list_models",
+  description:
+    "List available models on fal.ai. Use the page and total arguments for pagination. Avoid listing all models at once.",
+  parameters: z.object({
+    page: z
+      .number()
+      .optional()
+      .describe("The page number of models to retrieve (pagination)"),
+    total: z
+      .number()
+      .optional()
+      .describe("The total number of models to retrieve per page"),
+  }),
+  execute: async (args: { page?: number; total?: number }) => {
+    let url = `${FAL_BASE_URL}/models`;
+
+    const params: string[] = [];
+    if (args.page !== undefined) params.push(`page=${args.page}`);
+    if (args.total !== undefined) params.push(`total=${args.total}`);
+
+    if (params.length > 0) {
+      url += "?" + params.join("&");
+    }
+
+    const result = await publicRequest(url);
+    return JSON.stringify(result);
+  },
+};
+
+/**
+ * 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"),
+  }),
+  execute: async (args: { keywords: string }) => {
+    const url = `${FAL_BASE_URL}/models?keywords=${encodeURIComponent(
+      args.keywords
+    )}`;
+    const result = await publicRequest(url);
+    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

@@ -0,0 +1,119 @@
+/**
+ * Storage module for fal.ai MCP server.
+ * Provides tools for uploading files to fal.ai storage.
+ */
+
+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";
+
+/**
+ * Get MIME type from file extension.
+ */
+function getMimeType(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  const mimeTypes: Record<string, string> = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".ogg": "audio/ogg",
+    ".pdf": "application/pdf",
+    ".json": "application/json",
+    ".txt": "text/plain",
+  };
+  return mimeTypes[ext] || "application/octet-stream";
+}
+
+/**
+ * Upload a file to fal.ai storage.
+ */
+export const falUploadFile = {
+  name: "fal_upload_file",
+  description: "Upload a file to fal.ai CDN storage.",
+  parameters: z.object({
+    path: z.string().describe("The absolute path to the file to upload"),
+  }),
+  execute: async (args: { path: string }) => {
+    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);
+
+      // 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}...`);
+
+      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}`
+        );
+      }
+
+      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...`);
+
+      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),
+      });
+
+      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`);
+
+      return JSON.stringify({
+        file_url,
+        file_name: filename,
+        file_size: fileSize,
+        content_type: contentType,
+      });
+    }, "fal_upload_file");
+  },
+};