@mixio-pro/kalaasetu-mcp 1.0.0 → 1.0.1-beta

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,127 @@ 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",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/gcp-credentials.json"
+      }
+    }
+  }
+}
+```
+
+### 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, and video analysis | [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) |
+| `GOOGLE_APPLICATION_CREDENTIALS` | For Vertex AI Image-to-Video (Veo) | [GCP Console](https://console.cloud.google.com/apis/credentials) |
+
+### 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"
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/gcp-credentials.json"
+
+# 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"
+$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\gcp-credentials.json"
+```
+
+#### 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 +169,27 @@ export PERPLEXITY_API_KEY="your-perplexity-api-key"
 
 ## Running the Server
 
-To run:
+### Local Development
+
+To run the server locally:
+
+```bash
+bun run src/index.ts
+```
+
+Or with auto-reload:
 
 ```bash
-bun run index.ts
+bun run dev
 ```
 
-## Tool: Infinitalk
+## 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 +198,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 +211,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 +223,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 +233,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 +252,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/bin/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+// Wrapper to run with Bun if available, otherwise Node
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const indexPath = join(__dirname, '..', 'src', 'index.ts');
+
+// Try to run with Bun first
+const bunProcess = spawn('bun', [indexPath], {
+  stdio: 'inherit',
+  shell: true
+});
+
+bunProcess.on('error', (error) => {
+  if (error.code === 'ENOENT') {
+    console.error('Error: This package requires Bun to be installed.');
+    console.error('Please install Bun from https://bun.sh');
+    console.error('');
+    console.error('Install with:');
+    console.error('  curl -fsSL https://bun.sh/install | bash');
+    process.exit(1);
+  } else {
+    throw error;
+  }
+});
+
+bunProcess.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@mixio-pro/kalaasetu-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1-beta",
   "description": "A powerful Model Context Protocol server providing AI tools for content generation and analysis",
   "type": "module",
   "module": "src/index.ts",
   "main": "src/index.ts",
   "bin": {
-    "kalaasetu-mcp": "./src/index.ts"
+    "kalaasetu-mcp": "./bin/cli.js"
   },
   "files": [
     "src",
+    "bin",
     "README.md",
     "LICENSE"
   ],