@mixio-pro/kalaasetu-mcp 1.0.1 → 1.0.3

package/README.md

@@ -2,6 +2,12 @@
 
 Kalaasetu MCP Server - A powerful Model Context Protocol server providing various AI tools for content generation and analysis.
 
+## Quick Start
+
+```bash
+npx @mixio-pro/kalaasetu-mcp@latest
+```
+
 ## Features
 
 ### 🎨 Gemini Tools
@@ -24,12 +30,163 @@ Kalaasetu MCP Server - A powerful Model Context Protocol server providing variou
 
 ## Installation
 
-To install dependencies:
+### Using npx (Recommended)
+
+Run directly without installation:
+
+```bash
+npx @mixio-pro/kalaasetu-mcp@latest
+```
+
+### Global Installation
+
+```bash
+npm install -g @mixio-pro/kalaasetu-mcp
+kalaasetu-mcp
+```
+
+### Local Development
+
+To install dependencies for local development:
 
 ```bash
 bun install
 ```
 
+## MCP Client Configuration
+
+### Cursor IDE
+
+Add to your Cursor settings (`~/.cursor/config.json` or via Settings → MCP):
+
+```json
+{
+  "mcpServers": {
+    "kalaasetu": {
+      "command": "npx",
+      "args": ["@mixio-pro/kalaasetu-mcp@latest"],
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-api-key",
+        "FAL_KEY": "your-fal-api-key",
+        "PERPLEXITY_API_KEY": "your-perplexity-api-key"
+      }
+    }
+  }
+}
+```
+
+### OpenCode IDE
+
+Add to your OpenCode MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "kalaasetu": {
+      "command": "npx",
+      "args": ["@mixio-pro/kalaasetu-mcp@latest"],
+      "environment": {
+        "GEMINI_API_KEY": "your-gemini-api-key",
+        "FAL_KEY": "your-fal-api-key",
+        "PERPLEXITY_API_KEY": "your-perplexity-api-key"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "kalaasetu": {
+      "command": "npx",
+      "args": ["@mixio-pro/kalaasetu-mcp@latest"],
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-api-key",
+        "FAL_KEY": "your-fal-api-key",
+        "PERPLEXITY_API_KEY": "your-perplexity-api-key"
+      }
+    }
+  }
+}
+```
+
+### OpenCode IDE
+
+Add to your OpenCode MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "kalaasetu": {
+      "type": "local",
+      "command": ["npx", "@mixio-pro/kalaasetu-mcp@latest"],
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-api-key",
+        "FAL_KEY": "your-fal-api-key",
+        "PERPLEXITY_API_KEY": "your-perplexity-api-key",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/gcp-credentials.json"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "kalaasetu": {
+      "command": "npx",
+      "args": ["@mixio-pro/kalaasetu-mcp@latest"],
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-api-key",
+        "FAL_KEY": "your-fal-api-key",
+        "PERPLEXITY_API_KEY": "your-perplexity-api-key",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/gcp-credentials.json"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+### Required API Keys
+
+| Variable | Description | Get API Key |
+|----------|-------------|-------------|
+| `GEMINI_API_KEY` | For Gemini image generation, TTS, video analysis, and Veo video generation | [Google AI Studio](https://aistudio.google.com/app/apikey) |
+| `FAL_KEY` | For Infinitalk and Hunyuan Avatar tools | [FAL AI](https://fal.ai/dashboard/keys) |
+| `PERPLEXITY_API_KEY` | For image and video search | [Perplexity API](https://www.perplexity.ai/settings/api) |
+
+### Setting Environment Variables
+
+#### For Command Line Usage
+
+```bash
+# macOS/Linux
+export GEMINI_API_KEY="your-gemini-api-key"
+export FAL_KEY="your-fal-api-key"
+export PERPLEXITY_API_KEY="your-perplexity-api-key"
+
+# Windows (PowerShell)
+$env:GEMINI_API_KEY="your-gemini-api-key"
+$env:FAL_KEY="your-fal-api-key"
+$env:PERPLEXITY_API_KEY="your-perplexity-api-key"
+```
+
+#### For MCP Clients
+
+Set the environment variables in your MCP client configuration as shown in the examples above.
+
 ## Configuration
 
 Set up the required API keys as environment variables:
@@ -48,17 +205,27 @@ export PERPLEXITY_API_KEY="your-perplexity-api-key"
 
 ## Running the Server
 
-To run:
+### Local Development
+
+To run the server locally:
 
 ```bash
-bun run index.ts
+bun run src/index.ts
 ```
 
-## Tool: Infinitalk
+Or with auto-reload:
+
+```bash
+bun run dev
+```
+
+## Available Tools
+
+### Infinitalk
 
 Generate talking avatar videos from images and audio using FAL AI's Infinitalk model.
 
-### Parameters
+#### Parameters
 
 - `image_url` (required): URL of the input image
 - `audio_url` (required): URL of the audio file for lip-sync
@@ -67,9 +234,8 @@ Generate talking avatar videos from images and audio using FAL AI's Infinitalk m
 - `resolution` (optional): Video resolution - "480p" or "720p" (default: "480p")
 - `seed` (optional): Random seed for reproducibility (default: 42)
 - `acceleration` (optional): Generation speed - "none", "regular", or "high" (default: "regular")
-- `fal_key` (optional): FAL API key (uses FAL_KEY env var if not provided)
 
-### Example Usage
+#### Example Usage
 
 ```json
 {
@@ -81,11 +247,11 @@ Generate talking avatar videos from images and audio using FAL AI's Infinitalk m
 }
 ```
 
-## Tool: Perplexity Images
+### Perplexity Images
 
 Search for images using Perplexity AI with advanced filtering options.
 
-### Parameters
+#### Parameters
 
 - `query` (required): The search query for images
 - `image_domain_filter` (optional): Array of domains to include or exclude (prefix with '-' to exclude)
@@ -93,7 +259,7 @@ Search for images using Perplexity AI with advanced filtering options.
 - `image_format_filter` (optional): Array of allowed image formats
   - Example: `["jpg", "png", "gif"]`
 
-### Example Usage
+#### Example Usage
 
 ```json
 {
@@ -103,17 +269,17 @@ Search for images using Perplexity AI with advanced filtering options.
 }
 ```
 
-## Tool: Perplexity Videos
+### Perplexity Videos
 
 Search for videos using Perplexity AI with domain filtering.
 
-### Parameters
+#### Parameters
 
 - `query` (required): The search query for videos
 - `search_domain_filter` (optional): Array of domains to limit search (use '-' prefix to exclude)
   - Example: `["youtube.com"]` or `["-tiktok.com"]`
 
-### Example Usage
+#### Example Usage
 
 ```json
 {
@@ -122,6 +288,19 @@ Search for videos using Perplexity AI with domain filtering.
 }
 ```
 
+## Testing
+
+You can test the MCP server using the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector npx @mixio-pro/kalaasetu-mcp@latest
+```
+
+## Requirements
+
+- **Bun**: This package requires Bun runtime. Install from [bun.sh](https://bun.sh)
+- **API Keys**: Obtain the necessary API keys from the providers listed above
+
 ## Project Info
 
 This project was created using `bun init` in bun v1.3.1. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/package.json

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

package/src/tools/gemini.ts

@@ -263,7 +263,7 @@ export const geminiSingleSpeakerTts = {
   description: "Generate single speaker voice audio from text using Gemini 2.5 Pro Preview TTS model",
   parameters: z.object({
     text: z.string().describe("Text to convert to speech"),
-    voice_name: z.string().describe("Voice name from supported options (e.g., 'Kore', 'Zephyr', 'Puck', etc.)"),
+    voice_name: z.string().describe("Voice name from supported options. Use Kore, Erinome or Despina for the female voices and Enceladus for male."),
     output_path: z.string().optional().describe("Output WAV file path (optional, defaults to timestamp-based filename)"),
   }),
   execute: async (args: { text: string; voice_name: string; output_path?: string }) => {
@@ -276,7 +276,7 @@ export const geminiSingleSpeakerTts = {
           speechConfig: {
             voiceConfig: {
               prebuiltVoiceConfig: { 
-                voiceName: args.voice_name 
+                voiceName: args.voice_name || 'Despina'
               },
             },
           },

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

@@ -1,49 +1,23 @@
 import { z } from "zod";
 import * as fs from "fs";
-import { GoogleAuth } from "google-auth-library";
-import { exec } from "child_process";
 import * as path from "path";
+import { GoogleGenAI } from "@google/genai";
 
 async function wait(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function fetchAccessToken(): Promise<string> {
-  try {
-    const auth = new GoogleAuth({ scopes: ["https://www.googleapis.com/auth/cloud-platform"] });
-    const client = await auth.getClient();
-    const token = await client.getAccessToken();
-    if (!token || !token.token || typeof token.token !== "string") {
-      throw new Error("No token from GoogleAuth");
-    }
-    return token.token;
-  } catch (e: any) {
-    // Fallback to gcloud
-    return await new Promise((resolve, reject) => {
-      exec("gcloud auth print-access-token", (err, stdout, stderr) => {
-        if (err) {
-          reject(new Error(`Failed to fetch an access token (ADC and gcloud): ${stderr || err.message}`));
-          return;
-        }
-        const t = (stdout || "").trim();
-        if (!t) {
-          reject(new Error("Failed to fetch an access token: empty token from gcloud"));
-          return;
-        }
-        resolve(t);
-      });
-    });
-  }
-}
-
 function fileToBase64(filePath: string): { data: string; mimeType: string } {
   if (!fs.existsSync(filePath)) {
     throw new Error(`File not found: ${filePath}`);
   }
   const buf = fs.readFileSync(filePath);
   const data = Buffer.from(buf).toString("base64");
-  // Default to PNG if not sure, similar to existing code
-  const mimeType = "image/png";
+  // Detect mime type from extension
+  const ext = path.extname(filePath).toLowerCase();
+  const mimeType = ext === '.jpg' || ext === '.jpeg' ? 'image/jpeg' : 
+                   ext === '.png' ? 'image/png' :
+                   ext === '.webp' ? 'image/webp' : 'image/png';
   return { data, mimeType };
 }
 
@@ -54,178 +28,134 @@ export const imageToVideo = {
     prompt: z.string().describe("Text description for the video"),
     image_path: z.string().optional().describe("Path to source image for image-to-video generation"),
     aspect_ratio: z.string().optional().describe("Video aspect ratio: '16:9' or '9:16' (default: '9:16')"),
-    duration_seconds: z.string().optional().describe("Video duration in seconds: '4', '6', or '8' (default: '6')"),
+    duration_seconds: z.number().optional().describe("Video duration in seconds: 4, 6, or 8 (default: 6)"),
     resolution: z.string().optional().describe("Video resolution: '720p' or '1080p' (default: '720p')"),
     negative_prompt: z.string().optional().describe("Text describing what not to include in the video"),
     person_generation: z.string().optional().describe("Controls generation of people: 'allow_adult' (default for image-to-video) or 'allow_all'"),
     reference_images: z.array(z.string()).optional().describe("Additional image paths for reference (max 3)"),
     output_path: z.string().optional().describe("Output MP4 file path (if multiple predictions, index suffix is added)"),
-    project_id: z.string().optional().describe("GCP Project ID (default: mixio-pro)"),
-    location_id: z.string().optional().describe("Vertex region (default: us-central1)"),
-    model_id: z.string().optional().describe("Model ID (default: veo-3.1-fast-generate-preview)"),
+    gemini_api_key: z.string().optional().describe("Gemini API key (uses GEMINI_API_KEY env var if not provided)"),
+    model_id: z.string().optional().describe("Model ID (default: veo-2.0-generate-001)"),
   }),
   execute: async (args: {
     prompt: string;
     image_path?: string;
     aspect_ratio?: string;
-    duration_seconds?: string;
+    duration_seconds?: number;
     resolution?: string;
     negative_prompt?: string;
     person_generation?: string;
     reference_images?: string[];
     output_path?: string;
-    project_id?: string;
-    location_id?: string;
+    gemini_api_key?: string;
     model_id?: string;
   }) => {
-    const projectId = args.project_id || "mixio-pro";
-    const location = args.location_id || "us-central1";
-    const modelId = args.model_id || "veo-3.1-fast-generate-preview";
-
-    const token = await fetchAccessToken();
-
-    const url = `https://${location}-aiplatform.googleapis.com/v1/projects/${projectId}/locations/${location}/publishers/google/models/${modelId}:predictLongRunning`;
-
-    let imagePart: any = undefined;
-    if (args.image_path) {
-      const { data, mimeType } = fileToBase64(args.image_path);
-      imagePart = {
-        image: {
-          bytesBase64Encoded: data,
-          mimeType,
-        },
-      };
+    const apiKey = args.gemini_api_key || process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      throw new Error("Gemini API key is required. Set GEMINI_API_KEY environment variable or pass gemini_api_key parameter. Get one at https://aistudio.google.com/app/apikey");
     }
 
-    let referenceImages: any[] | undefined = undefined;
-    if (args.reference_images) {
-      let refImages: string[];
-      if (typeof args.reference_images === 'string') {
-        const strValue = args.reference_images as string;
-        if (strValue.startsWith("[") && strValue.endsWith("]")) {
-          try {
-            refImages = JSON.parse(strValue);
-          } catch {
-            throw new Error("Invalid reference_images format");
-          }
-        } else {
-          refImages = [strValue];
-        }
-      } else if (Array.isArray(args.reference_images)) {
-        refImages = args.reference_images;
-      } else {
-        throw new Error("Invalid reference_images: must be array or string");
-      }
-
-      if (refImages.length > 0) {
-        referenceImages = refImages.slice(0, 3).map((p) => {
-          const { data, mimeType } = fileToBase64(p);
-          return {
-            image: {
-              bytesBase64Encoded: data,
-              mimeType,
-            },
-            referenceType: "asset",
-          };
-        });
-      }
+    const model = args.model_id || "veo-2.0-generate-001";
+    
+    // Initialize Google GenAI client
+    const genai = new GoogleGenAI({ apiKey });
+
+    // Build config for video generation
+    const config: any = {};
+    
+    if (args.duration_seconds !== undefined) {
+      config.duration_seconds = args.duration_seconds;
+    } else {
+      config.duration_seconds = 6; // default
+    }
+    
+    if (args.aspect_ratio) {
+      config.aspect_ratio = args.aspect_ratio;
     }
 
-    const personGeneration = args.person_generation || (args.image_path ? "allow_adult" : "allow_all");
-
-    const instances: any[] = [
-      {
+    try {
+      // Start video generation operation
+      console.log(`Starting video generation with model: ${model}`);
+      let operation = await genai.models.generateVideos({
+        model,
         prompt: args.prompt,
-        ...(imagePart || {}),
-        ...(referenceImages ? { referenceImages } : {}),
-      },
-    ];
-
-    const parameters: any = {
-      aspectRatio: args.aspect_ratio || "9:16",
-      durationSeconds: parseInt(args.duration_seconds || "6"),
-      resolution: args.resolution || "720p",
-      negativePrompt: args.negative_prompt,
-      generateAudio: false,
-      personGeneration,
-    };
-
-    const res = await fetch(url, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ instances, parameters }),
-    });
+        config,
+      });
 
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`Vertex request failed: ${res.status} ${text}`);
-    }
+      console.log("Operation started, waiting for completion...");
+      
+      // Poll until operation is complete (max 10 minutes)
+      let tries = 0;
+      const maxTries = 60; // 10 minutes with 10s intervals
+      
+      while (!operation.done && tries < maxTries) {
+        await wait(10000); // Wait 10 seconds
+        tries++;
+        console.log(`Polling attempt ${tries}/${maxTries}...`);
+        
+        operation = await genai.operations.getVideosOperation({
+          operation: operation,
+        });
+      }
 
-    const op: any = await res.json();
-    const name: string = (op as any).name || (op as any).operation || "";
-    if (!name) {
-      throw new Error("Vertex did not return an operation name for long-running request");
-    }
+      if (!operation.done) {
+        throw new Error("Video generation timed out after 10 minutes");
+      }
 
-    let current: any = op;
-    let done = !!(op as any).done;
-    let tries = 0;
+      console.log("Operation completed!");
+      console.log("Full Response:", JSON.stringify(operation.response, null, 2));
 
-    // Poll using fetchPredictOperation as per Vertex recommendation
-    const fetchUrl = `https://${location}-aiplatform.googleapis.com/v1/projects/${projectId}/locations/${location}/publishers/google/models/${modelId}:fetchPredictOperation`;
-    while (!done && tries < 60) {
-      await wait(10000);
-      const poll = await fetch(fetchUrl, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ operationName: name }),
-      });
-      if (!poll.ok) {
-        const text = await poll.text();
-        throw new Error(`Vertex operation poll failed: ${poll.status} ${text}`);
+      // Extract generated videos from response
+      const generatedVideos = operation.response?.generatedVideos || [];
+      
+      if (!generatedVideos || generatedVideos.length === 0) {
+        const respStr = JSON.stringify(operation.response, null, 2);
+        return `Video generation completed but no videos found in response.\n\nFull Response:\n${respStr.slice(0, 2000)}${respStr.length > 2000 ? '\n...(truncated)' : ''}`;
       }
-      current = await poll.json();
-      done = !!(current as any).done || !!(current as any).response;
-      tries++;
-    }
 
-    const resp = (current as any).response || current;
-    // Decode from response.videos[].bytesBase64Encoded only
-    const outputs: string[] = [];
-    const saveVideo = (base64: string, index: number) => {
-      if (!base64) return;
-      const filePath = args.output_path
-        ? (index === 0 ? args.output_path : args.output_path.replace(/\.mp4$/i, `_${index}.mp4`))
-        : `video_output_${Date.now()}${index === 0 ? '' : '_' + index}.mp4`;
-      const absPath = path.resolve(filePath);
-      const buf = Buffer.from(base64, 'base64');
-      fs.writeFileSync(absPath, buf);
-      outputs.push(absPath);
-    };
+      // Download and save videos
+      const outputs: string[] = [];
+      
+      for (let i = 0; i < generatedVideos.length; i++) {
+        const generatedVideo = generatedVideos[i];
+        const videoUri = generatedVideo?.video?.uri;
+        
+        if (!videoUri) {
+          console.warn(`Video ${i} has no URI`);
+          continue;
+        }
 
-    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') {
-          saveVideo(v.bytesBase64Encoded, i);
+        console.log(`Downloading video ${i + 1}/${generatedVideos.length}...`);
+        
+        // Download video from URI
+        const videoUrl = `${videoUri}&key=${apiKey}`;
+        const response = await fetch(videoUrl);
+        
+        if (!response.ok) {
+          throw new Error(`Failed to download video: ${response.status} ${response.statusText}`);
         }
+        
+        const buffer = await response.arrayBuffer();
+        
+        // Save video to file
+        const filePath = args.output_path
+          ? (i === 0 ? args.output_path : args.output_path.replace(/\.mp4$/i, `_${i}.mp4`))
+          : `video_output_${Date.now()}${i === 0 ? '' : '_' + i}.mp4`;
+        const absPath = path.resolve(filePath);
+        
+        fs.writeFileSync(absPath, Buffer.from(buffer));
+        outputs.push(absPath);
+        console.log(`Saved video to: ${absPath}`);
+      }
+
+      if (outputs.length > 0) {
+        return `Video(s) saved successfully:\n${outputs.map((p, i) => `${i + 1}. ${p}`).join('\n')}`;
       }
-    }
-    if (outputs.length > 0) {
-      return `Video(s) saved: ${outputs.join(', ')}`;
-    }
 
-    // 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=${name}. json_head150=${head150} json_tail50=${tail50}`;
+      return "Video generation completed but no videos were saved.";
+      
+    } catch (error: any) {
+      throw new Error(`Video generation failed: ${error.message || JSON.stringify(error)}`);
+    }
   },
 };