@mixio-pro/kalaasetu-mcp 2.0.8-beta → 2.0.10-beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixio-pro/kalaasetu-mcp",
-  "version": "2.0.8-beta",
+  "version": "2.0.10-beta",
   "description": "A powerful Model Context Protocol server providing AI tools for content generation and analysis",
   "type": "module",
   "module": "src/index.ts",
@@ -52,7 +52,7 @@
     "@google/genai": "^1.28.0",
     "@types/node": "^24.10.1",
     "@types/wav": "^1.0.4",
-    "fastmcp": "^3.22.0",
+    "fastmcp": "3.26.8",
     "form-data": "^4.0.5",
     "google-auth-library": "^10.5.0",
     "wav": "^1.0.2",

package/src/index.ts

@@ -11,46 +11,47 @@ import { geminiEditImage, geminiTextToImage } from "./tools/gemini";
 import { imageToVideo } from "./tools/image-to-video";
 import { getGenerationStatus } from "./tools/get-status";
 
+import { syncFalConfig } from "./tools/fal/config";
+import { syncPromptEnhancerConfigs } from "./utils/prompt-enhancer-presets";
+
 const server = new FastMCP({
   name: "Kalaasetu MCP Server",
   version: pkg.version as any,
 });
 
-// Gemini Image Tools
-server.addTool(geminiTextToImage);
-server.addTool(geminiEditImage);
-// server.addTool(geminiAnalyzeImages);
-
-// Gemini TTS Tool
-// server.addTool(geminiSingleSpeakerTts);
+async function main() {
+  console.log("🚀 Initializing Kalaasetu MCP Server...");
 
-// Gemini Video Analysis Tool
-// server.addTool(geminiAnalyzeVideos);
+  // 1. Sync Remote Configs
+  await Promise.all([syncFalConfig(), syncPromptEnhancerConfigs()]);
 
-// YouTube Analyzer Tool
-// server.addTool(analyzeYoutubeVideo);
+  // 2. Add Gemini Tools
+  server.addTool(geminiTextToImage);
+  server.addTool(geminiEditImage);
+  server.addTool(imageToVideo);
 
-// Vertex AI Image-to-Video Tool
-server.addTool(imageToVideo);
+  // 3. Add Discovery Tools
+  server.addTool(falListPresets);
+  server.addTool(falGetPresetDetails);
+  server.addTool(falUploadFile);
 
-// Perplexity Search Tools
-// server.addTool(perplexityImages);
-// server.addTool(perplexityVideos);
+  // 4. Register Dynamic FAL AI Tools
+  // These are now based on potentially synced remote config
+  const falTools = createAllFalTools();
+  for (const tool of falTools) {
+    server.addTool(tool);
+  }
 
-// Discovery and Utility Tools
-server.addTool(falListPresets);
-server.addTool(falGetPresetDetails);
-server.addTool(falUploadFile);
+  // 5. Add Status Tool
+  server.addTool(getGenerationStatus);
 
-// Dynamic FAL AI Tools - each preset becomes a separate tool (prefixed with fal_)
-const falTools = createAllFalTools();
-for (const tool of falTools) {
-  server.addTool(tool);
+  console.log("✅ Starting server transport...");
+  server.start({
+    transportType: "stdio",
+  });
 }
 
-// Unified Status Tool (works with both FAL and Vertex AI)
-server.addTool(getGenerationStatus);
-
-server.start({
-  transportType: "stdio",
+main().catch((err) => {
+  console.error("❌ Failed to start server:", err);
+  process.exit(1);
 });

package/src/tools/fal/config.ts

@@ -129,58 +129,32 @@ export const DEFAULT_PRESETS: FalPresetConfig[] = [
   },
 ];
 
-/**
- * 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 {
-  let configPath = process.env.FAL_CONFIG_JSON_PATH;
-
-  // Fallback to default file search if no env var
-  if (!configPath) {
-    const potentialPaths = [
-      "fal-config.json", // in CWD
-      path.join(__dirname, "../../fal-config.json"), // from src/tools/fal in source
-      path.join(__dirname, "../../../fal-config.json"), // from dist/tools/fal in build
-    ];
-
-    for (const p of potentialPaths) {
-      if (fs.existsSync(p)) {
-        configPath = p;
-        break;
-      }
-    }
-  }
-
-  if (!configPath) {
-    console.error(
-      "FAL_CONFIG_JSON_PATH not set and no fal-config.json found. Using internal default presets."
-    );
-    return { presets: DEFAULT_PRESETS };
-  }
+import { syncRemoteConfig } from "../../utils/remote-sync";
 
-  try {
-    const absolutePath = path.resolve(configPath);
+let currentConfig: FalConfig = { presets: DEFAULT_PRESETS };
 
-    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.");
-    }
+/**
+ * Syncs the FAL configuration with the remote server.
+ */
+export async function syncFalConfig(): Promise<FalConfig> {
+  currentConfig = await syncRemoteConfig<FalConfig>({
+    name: "fal-config",
+    remoteUrl: "https://config.mixio.pro/mcp/fal/config.json",
+    envVar: "FAL_CONFIG_JSON_PATH",
+    fallback: { presets: DEFAULT_PRESETS },
+    validate: (data: any): data is FalConfig => {
+      return data && Array.isArray(data.presets);
+    },
+  });
+  return currentConfig;
+}
 
-    return config;
-  } catch (error: any) {
-    console.error(`Error loading FAL config: ${error.message}`);
-    return { presets: DEFAULT_PRESETS };
-  }
+/**
+ * Load the FAL configuration.
+ * Returns the currently synced config or internal defaults.
+ */
+export function loadFalConfig(): FalConfig {
+  return currentConfig;
 }
 
 /**

package/src/utils/prompt-enhancer-presets.ts

@@ -126,7 +126,38 @@ export const VIDEO_PRESETS: Record<string, PromptEnhancerConfig> = {
     styleGuide:
       "cinematic composition, present tense, flowing narrative, clear camera language, atmospheric lighting, emotive expressions through physical cues",
     negativeElements:
-      "text, logos, signage, brand names, complex physics, chaotic motion, jumping, juggling, conflicting light sources, overloaded scene, too many characters, internal emotional states without visual cues",
+      "text, logos, signage, brand names, complex physics, chaotic motion, jumping, juggling, conflicting light sources, overloaded scene, too many characters, internal emotional states without visual cues, high-frequency patterns, brick walls, mesh, micro-check fabrics, moiré",
+    guidelines:
+      "LTX-2 requires a narrative, screenplay-like approach. 1. Establish the shot (cinematography, scale, focal length). 2. Set the scene (lighting, atmosphere, textures). 3. Describe subject and action as a natural sequence flowing from start to end. 4. Specify camera movements relative to the subject. Describe what happens after the movement for coherence.",
+    dos: [
+      "Write in single flowing paragraphs (4-8 sentences)",
+      "Use present tense for all actions (e.g., 'glides', 'turns')",
+      "Describe cinematography first to anchor the frame",
+      "Express emotion through physical cues (e.g., 'furrows brow', 'eyes widen')",
+      "Match detail level to shot scale (close-ups need more detail)",
+      "Use lens and shutter language (e.g., '50mm', '180° shutter equivalent')",
+      "Describe audio as SFX or spoken dialogue in quotation marks",
+    ],
+    donts: [
+      "Avoid 'vibe dumping' (e.g., 'epic amazing 4K')",
+      "Don't use internal emotional labels (e.g., 'feels sad')",
+      "Avoid high-frequency patterns that cause moiré (bricks, mesh)",
+      "Don't request abrupt reframing or chaotic handheld motion",
+      "Avoid complex physics or multiple interacting subjects",
+      "No readable text or logos",
+    ],
+    examples: [
+      {
+        input: "A girl puppet singing in the rain",
+        output:
+          "A close-up of a cheerful girl puppet with curly auburn yarn hair and wide button eyes, holding a small red umbrella above her head. Rain falls gently around her. She looks upward and begins to sing with joy in English: 'It's raining, it's raining, I love it when its raining.' Her fabric mouth opening and closing to a melodic tune. Her hands grip the umbrella handle as she sways slightly from side to side in rhythm. The camera holds steady as the rain sparkles against the soft lighting. Her eyes blink occasionally as she sings.",
+      },
+      {
+        input: "A woman exploring an abandoned town",
+        output:
+          "A cinematic medium-wide shot of an abandoned town street at dawn with light mist clinging to the cracked pavement. An explorer in a leather satchel and messy brown hair walks slowly along the empty street. The camera begins slightly behind her, then performs a smooth tracking shot as she turns her head to look at the boarded-up windows. The camera pulls out as she continues walking, revealing the scale of the quiet, empty town. Soft primary colors and Kodak 2383 film look.",
+      },
+    ],
   },
 
   /**
@@ -223,20 +254,80 @@ export const VIDEO_PRESETS: Record<string, PromptEnhancerConfig> = {
     negativeElements:
       "wide shot, distant, cold lighting, static expression, fast movement",
   },
+  /**
+   * Google Veo specific preset based on official prompting guidelines.
+   * Focuses on subject, action, context, and cinematography.
+   */
+  veo: {
+    prefix: "A cinematic video.",
+    styleGuide:
+      "high-fidelity, fluid motion, accurate physics, complex lighting, detailed textures, consistent subjects",
+    negativeElements:
+      "warped limbs, flickering artifacts, low resolution, jumping frames, blurry faces, text, logo",
+    guidelines:
+      "Veo excels at detailed cinematography. Follow the structure: 1. Subject (Specific) 2. Action (Precise) 3. Context (Environment/Lighting) 4. Cinematography (Movement/Angle). Optionally add SFX: descriptions at the end.",
+    dos: [
+      "Use 'cinematic' and 'photorealistic' for high quality",
+      "Clearly define camera movements like 'arc shot' or 'dolly zoom'",
+      "Add specific lighting like 'golden hour' or 'neon glow'",
+      "Describe audio using 'SFX:' prefix if needed",
+      "Use (no subtitles) if you want to avoid text overlays",
+    ],
+    donts: [
+      "Don't be vague about the setting",
+      "Avoid repetitive words",
+      "Don't overload the frame with too many subjects",
+      "Minimize the use of negative words like 'no' within the prompt (use the negative elements section instead)",
+    ],
+    examples: [
+      {
+        input: "A cowboy in a desert",
+        output:
+          "A cinematic medium shot of a rugged cowboy in a weathered leather hat standing in a vast, sun-scorched desert. The camera performs a slow 180-degree arc shot around him as dust swirls at his feet. SFX: The howling wind and the distant clink of spurs.",
+      },
+      {
+        input: "A futuristic city",
+        output:
+          "A wide aerial tracking shot over a sprawling neon-lit futuristic city at night. Rain slicks the metallic surfaces, reflecting the vibrant purple and teal lights. Flying vehicles navigate between towering skyscrapers with seamless, fluid motion. SFX: The ambient hum of a high-tech metropolis.",
+      },
+    ],
+  },
 };
 
-// =============================================================================
-// COMBINED PRESETS DICTIONARY
-// =============================================================================
+import { syncRemoteConfig } from "./remote-sync";
 
 /**
- * All available prompt enhancer presets.
+ * Dynamic registry for prompt enhancer presets.
  */
-export const PROMPT_ENHANCER_PRESETS: Record<string, PromptEnhancerConfig> = {
+export let PROMPT_ENHANCER_PRESETS: Record<string, PromptEnhancerConfig> = {
   ...IMAGE_PRESETS,
   ...VIDEO_PRESETS,
 };
 
+/**
+ * Syncs the prompt enhancer configurations with the remote server.
+ */
+export async function syncPromptEnhancerConfigs(): Promise<void> {
+  const remoteConfig = await syncRemoteConfig<Record<string, PromptEnhancerConfig>>({
+    name: "prompt-enhancers",
+    remoteUrl: "https://config.mixio.pro/mcp/prompt-enhancers.json",
+    envVar: "PROMPT_ENHANCER_CONFIG_PATH",
+    fallback: {},
+    validate: (data: any): data is Record<string, PromptEnhancerConfig> => {
+      return data && typeof data === "object" && !Array.isArray(data);
+    },
+  });
+
+  // Merge remote settings into the defaults
+  PROMPT_ENHANCER_PRESETS = {
+    ...IMAGE_PRESETS,
+    ...VIDEO_PRESETS,
+    ...remoteConfig,
+  };
+
+  console.log(`[Sync] Prompt Enhancer Presets updated. Total: ${Object.keys(PROMPT_ENHANCER_PRESETS).length}`);
+}
+
 // =============================================================================
 // HELPER FUNCTIONS
 // =============================================================================

package/src/utils/prompt-enhancer.ts

@@ -24,6 +24,16 @@ export interface PromptEnhancerConfig {
    * Example: "A cinematic shot of {prompt}, dramatic lighting"
    */
   wrapTemplate?: string;
+  /** Detailed system instructions for LLM-based enhancement */
+  llmSystemPrompt?: string;
+  /** Do's for the prompt (e.g. ['Use active voice', 'Describe motion']) */
+  dos?: string[];
+  /** Don'ts for the prompt (e.g. ['Avoid jargon', 'No technical camera terms']) */
+  donts?: string[];
+  /** Generic guidelines or reference text */
+  guidelines?: string;
+  /** Few-shot examples for the LLM { input: string, output: string } */
+  examples?: Array<{ input: string; output: string }>;
 }
 
 /**
@@ -177,6 +187,73 @@ export class PromptEnhancer {
     );
   }
 
+  /**
+   * Generates a comprehensive system prompt for an LLM to follow when enhancing a prompt.
+   */
+  getSystemPrompt(): string {
+    const lines: string[] = [];
+
+    if (this.config.llmSystemPrompt) {
+      lines.push(this.config.llmSystemPrompt);
+    } else {
+      lines.push(
+        "You are an expert prompt engineer specializing in AI image and video generation."
+      );
+      lines.push(
+        "Your task is to expand and enhance the user's input prompt into a high-quality, detailed description."
+      );
+    }
+
+    if (this.config.guidelines) {
+      lines.push("");
+      lines.push("### GUIDELINES");
+      lines.push(this.config.guidelines);
+    }
+
+    if (this.config.styleGuide) {
+      lines.push("");
+      lines.push("### STYLE AND QUALITY");
+      lines.push(`Incorporate these elements: ${this.config.styleGuide}`);
+    }
+
+    if (this.config.dos && this.config.dos.length > 0) {
+      lines.push("");
+      lines.push("### DO'S");
+      this.config.dos.forEach((item) => lines.push(`- ${item}`));
+    }
+
+    if (this.config.donts && this.config.donts.length > 0) {
+      lines.push("");
+      lines.push("### DON'TS");
+      this.config.donts.forEach((item) => lines.push(`- ${item}`));
+    }
+
+    if (this.config.negativeElements) {
+      lines.push("");
+      lines.push("### NEGATIVE PROMPT (AVOID)");
+      lines.push(this.config.negativeElements);
+    }
+
+    if (this.config.examples && this.config.examples.length > 0) {
+      lines.push("");
+      lines.push("### EXAMPLES");
+      this.config.examples.forEach((example, index) => {
+        lines.push(`Example ${index + 1}:`);
+        lines.push(`Input: ${example.input}`);
+        lines.push(`Output: ${example.output}`);
+        lines.push("");
+      });
+    }
+
+    lines.push("");
+    lines.push("### OUTPUT FORMAT");
+    lines.push(
+      "Return ONLY the enhanced prompt text. No explanations or conversational filler."
+    );
+
+    return lines.join("\n").trim();
+  }
+
   /**
    * Export the enhancer's configuration.
    */

package/src/utils/remote-sync.ts

@@ -0,0 +1,89 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+const CACHE_DIR = path.join(process.cwd(), ".cache");
+
+/**
+ * Options for remote configuration syncing.
+ */
+interface SyncOptions<T> {
+  /** The name of the config (used for file naming in cache) */
+  name: string;
+  /** The remote URL to fetch from */
+  remoteUrl: string;
+  /** Environment variable that overrides the remote URL or providing a local path */
+  envVar?: string;
+  /** Internal default to use if both remote and cache fail */
+  fallback: T;
+  /** Optional validation function */
+  validate?: (data: any) => data is T;
+}
+
+/**
+ * Syncs a configuration from a remote source, local file, or environment variable.
+ * Implements a caching strategy to ensure availability even when the remote is down.
+ */
+export async function syncRemoteConfig<T>(options: SyncOptions<T>): Promise<T> {
+  const { name, remoteUrl, envVar, fallback, validate } = options;
+  const cachePath = path.join(CACHE_DIR, `${name}.json`);
+
+  // 1. Check for Environment Variable Override (Local Path)
+  if (envVar && process.env[envVar]) {
+    const localPath = process.env[envVar]!;
+    try {
+      if (fs.existsSync(localPath)) {
+        const content = await readFile(localPath, "utf-8");
+        const data = JSON.parse(content);
+        if (!validate || validate(data)) {
+          console.log(`[Sync] Using local override from ${envVar}: ${localPath}`);
+          return data as T;
+        }
+      }
+    } catch (e) {
+      console.warn(`[Sync] Failed to read local override from ${envVar}: ${e}`);
+    }
+  }
+
+  // 2. Attempt to Fetch from Remote
+  try {
+    console.log(`[Sync] Attempting to fetch ${name} from ${remoteUrl}...`);
+    const response = await fetch(remoteUrl, {
+      signal: AbortSignal.timeout(5000), // 5s timeout
+    });
+
+    if (response.ok) {
+      const data = await response.json();
+      if (!validate || validate(data)) {
+        // Cache the successful fetch
+        await mkdir(CACHE_DIR, { recursive: true });
+        await writeFile(cachePath, JSON.stringify(data, null, 2));
+        console.log(`[Sync] Successfully updated ${name} and cached at ${cachePath}`);
+        return data as T;
+      }
+      console.warn(`[Sync] Remote data for ${name} failed validation.`);
+    } else {
+      console.warn(`[Sync] Remote fetch for ${name} failed with status: ${response.status}`);
+    }
+  } catch (e) {
+    console.warn(`[Sync] Error fetching ${name} from remote: ${e}`);
+  }
+
+  // 3. Fallback to Cache
+  try {
+    if (fs.existsSync(cachePath)) {
+      const cacheContent = await readFile(cachePath, "utf-8");
+      const data = JSON.parse(cacheContent);
+      if (data && (!validate || validate(data))) {
+        console.log(`[Sync] Using cached version of ${name} from ${cachePath}`);
+        return data as T;
+      }
+    }
+  } catch (e) {
+    console.warn(`[Sync] Failed to read cache for ${name}: ${e}`);
+  }
+
+  // 4. Final Fallback to Internal Defaults
+  console.warn(`[Sync] All sync methods failed for ${name}. Using internal defaults.`);
+  return fallback;
+}