@mixio-pro/kalaasetu-mcp 1.1.3 → 1.2.0

package/src/tools/perplexity.ts

@@ -1,190 +1,230 @@
 import { z } from "zod";
+import { safeToolExecute } from "../utils/tool-wrapper";
 
 export const perplexityImages = {
   name: "perplexityImages",
-  description: "Searches for images using the Perplexity API. Returns a formatted text response that includes a summary and a numbered list of image URLs with citations mapped to the text.",
+  description:
+    "Searches for images using the Perplexity API. Returns a formatted text response that includes a summary and a numbered list of image URLs with citations mapped to the text.",
   parameters: z.object({
     query: z.string().describe("The search query for images."),
-    image_domain_filter: z.array(z.string()).optional().describe("A list of domains to include or exclude. To exclude, prefix with '-'. E.g., ['wikimedia.org', '-gettyimages.com']."),
-    image_format_filter: z.array(z.string()).optional().describe("A list of allowed image formats. E.g., ['jpg', 'png', 'gif']."),
+    image_domain_filter: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "A list of domains to include or exclude. To exclude, prefix with '-'. E.g., ['wikimedia.org', '-gettyimages.com']."
+      ),
+    image_format_filter: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "A list of allowed image formats. E.g., ['jpg', 'png', 'gif']."
+      ),
   }),
-  execute: async (args: { query: string; image_domain_filter?: string[]; image_format_filter?: string[] }) => {
-    const apiKey = process.env.PERPLEXITY_API_KEY;
-    if (!apiKey) {
-      throw new Error("PERPLEXITY_API_KEY environment variable is not set.");
-    }
-
-    const url = "https://api.perplexity.ai/chat/completions";
-    const headers = {
-      "Authorization": `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-      "accept": "application/json"
-    };
-
-    const payload: any = {
-      model: "sonar",
-      messages: [
-        { role: "user", content: `Show me images of ${args.query}` }
-      ],
-      return_images: true
-    };
-
-    if (args.image_domain_filter) {
-      payload.image_domain_filter = args.image_domain_filter;
-    }
-    
-    if (args.image_format_filter) {
-      payload.image_format_filter = args.image_format_filter;
-    }
-
-    const res = await fetch(url, {
-      method: "POST",
-      headers: headers,
-      body: JSON.stringify(payload),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`Perplexity API request failed: ${res.status} ${text}`);
-    }
-
-    const data: any = await res.json();
-    let content = data.choices?.[0]?.message?.content;
-    const images = data.images;
-    const citations = data.citations;
-
-    if (!images || images.length === 0) {
-      return `No direct image URLs found in the API response. The text content was: ${content}`;
-    }
-
-    // Create a map of origin_url -> new 1-based index
-    const originUrlToImageIndex: { [key: string]: number } = {};
-    images.forEach((img: any, index: number) => {
-      if (img.origin_url) {
-        originUrlToImageIndex[img.origin_url] = index + 1;
+  timeoutMs: 300000,
+  execute: async (args: {
+    query: string;
+    image_domain_filter?: string[];
+    image_format_filter?: string[];
+  }) => {
+    return safeToolExecute(async () => {
+      const apiKey = process.env.PERPLEXITY_API_KEY;
+      if (!apiKey) {
+        throw new Error("PERPLEXITY_API_KEY environment variable is not set.");
       }
-    });
 
-    // Create a map of old citation index -> new image index
-    const oldToNewCitationMap: { [key: number]: number } = {};
-    if (citations && Array.isArray(citations)) {
+      const url = "https://api.perplexity.ai/chat/completions";
+      const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        accept: "application/json",
+      };
+
+      const payload: any = {
+        model: "sonar",
+        messages: [
+          { role: "user", content: `Show me images of ${args.query}` },
+        ],
+        return_images: true,
+      };
+
+      if (args.image_domain_filter) {
+        payload.image_domain_filter = args.image_domain_filter;
+      }
+
+      if (args.image_format_filter) {
+        payload.image_format_filter = args.image_format_filter;
+      }
+
+      const res = await fetch(url, {
+        method: "POST",
+        headers: headers,
+        body: JSON.stringify(payload),
+      });
+
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Perplexity API request failed: ${res.status} ${text}`);
+      }
+
+      const data: any = await res.json();
+      let content = data.choices?.[0]?.message?.content;
+      const images = data.images;
+      const citations = data.citations;
+
+      if (!images || images.length === 0) {
+        return `No direct image URLs found in the API response. The text content was: ${content}`;
+      }
+
+      // Create a map of origin_url -> new 1-based index
+      const originUrlToImageIndex: { [key: string]: number } = {};
+      images.forEach((img: any, index: number) => {
+        if (img.origin_url) {
+          originUrlToImageIndex[img.origin_url] = index + 1;
+        }
+      });
+
+      // Create a map of old citation index -> new image index
+      const oldToNewCitationMap: { [key: number]: number } = {};
+      if (citations && Array.isArray(citations)) {
         citations.forEach((citationUrl: string, index: number) => {
-            if (originUrlToImageIndex[citationUrl]) {
-                oldToNewCitationMap[index + 1] = originUrlToImageIndex[citationUrl];
-            }
+          if (originUrlToImageIndex[citationUrl]) {
+            oldToNewCitationMap[index + 1] = originUrlToImageIndex[citationUrl];
+          }
         });
-    }
+      }
 
-    // Replace citations in the content
-    if (content && typeof content === 'string') {
-        content = content.replace(/\[(\d+)\]/g, (match: string, oldIndexStr: string) => {
+      // Replace citations in the content
+      if (content && typeof content === "string") {
+        content = content
+          .replace(/\[(\d+)\]/g, (match: string, oldIndexStr: string) => {
             const oldIndex = parseInt(oldIndexStr, 10);
             const newIndex = oldToNewCitationMap[oldIndex];
             if (newIndex) {
-                return `[${newIndex}]`;
+              return `[${newIndex}]`;
             }
-            return ''; // Remove citation if it doesn't correspond to an image
-        }).replace(/(\s\s+)/g, ' ').trim(); // Clean up extra spaces
-    }
-    
-    // Build the final formatted output
-    let output = content + "\n\n--- Images ---\n";
-    images.forEach((img: any, index: number) => {
-      output += `${index + 1}. ${img.image_url}\n   (Source: ${img.origin_url})\n`;
-    });
-
-    return output;
+            return ""; // Remove citation if it doesn't correspond to an image
+          })
+          .replace(/(\s\s+)/g, " ")
+          .trim(); // Clean up extra spaces
+      }
+
+      // Build the final formatted output
+      let output = content + "\n\n--- Images ---\n";
+      images.forEach((img: any, index: number) => {
+        output += `${index + 1}. ${img.image_url}\n   (Source: ${
+          img.origin_url
+        })\n`;
+      });
+
+      return output;
+    }, "perplexityImages");
   },
 };
 
 export const perplexityVideos = {
   name: "perplexityVideos",
-  description: "Searches for videos using the Perplexity API. Returns a formatted text response that includes a summary and a numbered list of video URLs with citations mapped to the text.",
+  description:
+    "Searches for videos using the Perplexity API. Returns a formatted text response that includes a summary and a numbered list of video URLs with citations mapped to the text.",
   parameters: z.object({
     query: z.string().describe("The search query for videos."),
-    search_domain_filter: z.array(z.string()).optional().describe("A list of domains to limit the search to (e.g., ['youtube.com']). Use a '-' prefix to exclude a domain."),
+    search_domain_filter: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "A list of domains to limit the search to (e.g., ['youtube.com']). Use a '-' prefix to exclude a domain."
+      ),
   }),
+  timeoutMs: 300000,
   execute: async (args: { query: string; search_domain_filter?: string[] }) => {
-    const apiKey = process.env.PERPLEXITY_API_KEY;
-    if (!apiKey) {
-      throw new Error("PERPLEXITY_API_KEY environment variable is not set.");
-    }
-
-    const url = "https://api.perplexity.ai/chat/completions";
-    const headers = {
-      "Authorization": `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-      "accept": "application/json"
-    };
-
-    const payload: any = {
-      model: "sonar-pro",
-      messages: [
-        { role: "user", content: `Show me videos of ${args.query}` }
-      ],
-      media_response: { overrides: { return_videos: true } }
-    };
-
-    if (args.search_domain_filter) {
-      payload.search_domain_filter = args.search_domain_filter;
-    }
-
-    const res = await fetch(url, {
-      method: "POST",
-      headers: headers,
-      body: JSON.stringify(payload),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`Perplexity API request failed: ${res.status} ${text}`);
-    }
-
-    const data: any = await res.json();
-    let content = data.choices?.[0]?.message?.content;
-    const videos = data.videos;
-    const citations = data.citations;
-
-    if (!videos || videos.length === 0) {
-      return `No direct video URLs found in the API response. Full API Response: ${JSON.stringify(data, null, 2)}`;
-    }
-
-    // Create a map of video url -> new 1-based index
-    const urlToVideoIndex: { [key: string]: number } = {};
-    videos.forEach((video: any, index: number) => {
-      if (video.url) {
-        urlToVideoIndex[video.url] = index + 1;
+    return safeToolExecute(async () => {
+      const apiKey = process.env.PERPLEXITY_API_KEY;
+      if (!apiKey) {
+        throw new Error("PERPLEXITY_API_KEY environment variable is not set.");
+      }
+
+      const url = "https://api.perplexity.ai/chat/completions";
+      const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        accept: "application/json",
+      };
+
+      const payload: any = {
+        model: "sonar-pro",
+        messages: [
+          { role: "user", content: `Show me videos of ${args.query}` },
+        ],
+        media_response: { overrides: { return_videos: true } },
+      };
+
+      if (args.search_domain_filter) {
+        payload.search_domain_filter = args.search_domain_filter;
       }
-    });
 
-    // Create a map of old citation index -> new video index
-    const oldToNewCitationMap: { [key: number]: number } = {};
-    if (citations && Array.isArray(citations)) {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: headers,
+        body: JSON.stringify(payload),
+      });
+
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Perplexity API request failed: ${res.status} ${text}`);
+      }
+
+      const data: any = await res.json();
+      let content = data.choices?.[0]?.message?.content;
+      const videos = data.videos;
+      const citations = data.citations;
+
+      if (!videos || videos.length === 0) {
+        return `No direct video URLs found in the API response. Full API Response: ${JSON.stringify(
+          data,
+          null,
+          2
+        )}`;
+      }
+
+      // Create a map of video url -> new 1-based index
+      const urlToVideoIndex: { [key: string]: number } = {};
+      videos.forEach((video: any, index: number) => {
+        if (video.url) {
+          urlToVideoIndex[video.url] = index + 1;
+        }
+      });
+
+      // Create a map of old citation index -> new video index
+      const oldToNewCitationMap: { [key: number]: number } = {};
+      if (citations && Array.isArray(citations)) {
         citations.forEach((citationUrl: string, index: number) => {
-            if (urlToVideoIndex[citationUrl]) {
-                oldToNewCitationMap[index + 1] = urlToVideoIndex[citationUrl];
-            }
+          if (urlToVideoIndex[citationUrl]) {
+            oldToNewCitationMap[index + 1] = urlToVideoIndex[citationUrl];
+          }
         });
-    }
+      }
 
-    // Replace citations in the content
-    if (content && typeof content === 'string') {
-        content = content.replace(/\[(\d+)\]/g, (match: string, oldIndexStr: string) => {
+      // Replace citations in the content
+      if (content && typeof content === "string") {
+        content = content
+          .replace(/\[(\d+)\]/g, (match: string, oldIndexStr: string) => {
             const oldIndex = parseInt(oldIndexStr, 10);
             const newIndex = oldToNewCitationMap[oldIndex];
             if (newIndex) {
-                return `[${newIndex}]`;
+              return `[${newIndex}]`;
             }
-            return ''; // Remove citation if it doesn't correspond to a video
-        }).replace(/(\s\s+)/g, ' ').trim(); // Clean up extra spaces
-    }
-    
-    // Build the final formatted output
-    let output = content + "\n\n--- Videos ---\n";
-    videos.forEach((video: any, index: number) => {
-      output += `${index + 1}. ${video.url}\n`;
-    });
-
-    return output;
+            return ""; // Remove citation if it doesn't correspond to a video
+          })
+          .replace(/(\s\s+)/g, " ")
+          .trim(); // Clean up extra spaces
+      }
+
+      // Build the final formatted output
+      let output = content + "\n\n--- Videos ---\n";
+      videos.forEach((video: any, index: number) => {
+        output += `${index + 1}. ${video.url}\n`;
+      });
+
+      return output;
+    }, "perplexityVideos");
   },
 };

package/src/tools/youtube.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { GoogleGenAI } from "@google/genai";
+import { safeToolExecute } from "../utils/tool-wrapper";
 
 const ai = new GoogleGenAI({
   apiKey: process.env.GEMINI_API_KEY || "",
@@ -7,46 +8,64 @@ const ai = new GoogleGenAI({
 
 export const analyzeYoutubeVideo = {
   name: "analyzeYoutubeVideo",
-  description: "Analyze YouTube videos for content using the correct GenAI JS API approach with FileData fileUri. Perfect for extracting stock media content, analyzing video content, or getting descriptions of YouTube videos",
+  description:
+    "Analyze YouTube videos for content using the correct GenAI JS API approach with FileData fileUri. Perfect for extracting stock media content, analyzing video content, or getting descriptions of YouTube videos",
   parameters: z.object({
-    youtube_url: z.string().describe("YouTube video URL to analyze (format: https://www.youtube.com/watch?v=VIDEO_ID)"),
-    prompt: z.string().describe("Analysis prompt or question about the YouTube video content"),
+    youtube_url: z
+      .string()
+      .describe(
+        "YouTube video URL to analyze (format: https://www.youtube.com/watch?v=VIDEO_ID)"
+      ),
+    prompt: z
+      .string()
+      .describe("Analysis prompt or question about the YouTube video content"),
   }),
+  timeoutMs: 300000,
   execute: async (args: { youtube_url: string; prompt: string }) => {
-    try {
-      // Validate YouTube URL format
-      if (!args.youtube_url || (!args.youtube_url.includes('youtube.com/watch') && !args.youtube_url.includes('youtu.be'))) {
-        throw new Error("Invalid YouTube URL format. Expected: https://www.youtube.com/watch?v=VIDEO_ID");
-      }
-
-      // Create content using the correct FileData approach with fileUri
-      const response = await ai.models.generateContent({
-        model: 'models/gemini-2.5-flash',
-        contents: {
-          parts: [
-            {
-              fileData: {
-                fileUri: args.youtube_url
-              }
-            },
-            { text: args.prompt }
-          ]
+    return safeToolExecute(async () => {
+      try {
+        // Validate YouTube URL format
+        if (
+          !args.youtube_url ||
+          (!args.youtube_url.includes("youtube.com/watch") &&
+            !args.youtube_url.includes("youtu.be"))
+        ) {
+          throw new Error(
+            "Invalid YouTube URL format. Expected: https://www.youtube.com/watch?v=VIDEO_ID"
+          );
         }
-      });
 
-      let result = "";
-      if (response.candidates && response.candidates[0]?.content?.parts) {
-        for (const part of response.candidates[0].content.parts) {
-          if (part.text) {
-            result += part.text;
+        // Create content using the correct FileData approach with fileUri
+        const response = await ai.models.generateContent({
+          model: "models/gemini-2.5-flash",
+          contents: {
+            parts: [
+              {
+                fileData: {
+                  fileUri: args.youtube_url,
+                },
+              },
+              { text: args.prompt },
+            ],
+          },
+        });
+
+        let result = "";
+        if (response.candidates && response.candidates[0]?.content?.parts) {
+          for (const part of response.candidates[0].content.parts) {
+            if (part.text) {
+              result += part.text;
+            }
           }
         }
+
+        return (
+          result ||
+          "YouTube video analysis completed but no text response received"
+        );
+      } catch (error: any) {
+        throw new Error(`YouTube video analysis failed: ${error.message}`);
       }
-      
-      return result || "YouTube video analysis completed but no text response received";
-      
-    } catch (error: any) {
-      throw new Error(`YouTube video analysis failed: ${error.message}`);
-    }
+    }, "analyzeYoutubeVideo");
   },
 };

package/src/utils/tool-wrapper.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+/**
+ * Standardized error result for MCP tools
+ */
+export interface ToolErrorResult {
+  isError: true;
+  content: Array<{
+    type: "text";
+    text: string;
+  }>;
+}
+
+/**
+ * Helper to check if a result is a ToolErrorResult
+ */
+export function isToolErrorResult(result: any): result is ToolErrorResult {
+  return (
+    typeof result === "object" &&
+    result !== null &&
+    result.isError === true &&
+    Array.isArray(result.content)
+  );
+}
+
+/**
+ * Format an error into a user-friendly string and log secure details
+ */
+export function formatToolError(error: unknown, context?: string): string {
+  let errorMessage = error instanceof Error ? error.message : String(error);
+
+  // Enhanced Zod Error Handling
+  if (error instanceof z.ZodError) {
+    const issues = error.issues.map(
+      (issue) => `[${issue.path.join(".")}] ${issue.message}`
+    );
+    errorMessage = `Validation Error: ${issues.join("; ")}`;
+  } else {
+    // Enhanced API Error Handling (looking for common properties)
+    const errObj = error as any;
+    if (errObj?.status || errObj?.statusText) {
+      const status = errObj.status ? `[${errObj.status}]` : "";
+      const text = errObj.statusText || "";
+      // If the message doesn't already contain the status info, append it
+      if (!errorMessage.includes(String(errObj.status))) {
+        errorMessage = `API Error ${status} ${text}: ${errorMessage}`.trim();
+      }
+    }
+  }
+
+  // Secure logging (never expose stack traces to the LLM, but log them internally)
+  console.error(
+    `[Tool Error] ${context ? `${context}: ` : ""}${errorMessage}`,
+    error
+  );
+
+  // Return sanitized message for the LLM
+  return `Tool execution failed${
+    context ? ` in ${context}` : ""
+  }: ${errorMessage}`;
+}
+
+/**
+ * Safely execute a tool function with standardized error handling
+ * @param fn The async tool execution function
+ * @param context Optional context name (e.g. tool name) for logging
+ */
+export async function safeToolExecute<T>(
+  fn: () => Promise<T>,
+  context?: string
+): Promise<T | ToolErrorResult> {
+  try {
+    return await fn();
+  } catch (error) {
+    const errorText = formatToolError(error, context);
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: errorText,
+        },
+      ],
+    };
+  }
+}