@mixio-pro/kalaasetu-mcp 2.1.0 → 2.1.1-beta

package/src/utils/openmeter.ts

@@ -0,0 +1,123 @@
+/**
+ * OpenMeter integration for tracking MCP tool call usage.
+ * Sends events to OpenMeter for billing and analytics.
+ */
+
+import { OpenMeter } from "@openmeter/sdk";
+import { getToolCredits } from "./tool-credits";
+import { logger } from "./logger";
+
+/**
+ * Internal OpenMeter configuration.
+ * API token is hardcoded - users only need to provide CLIENT_ID.
+ */
+const OPENMETER_CONFIG = {
+  apiToken:
+    "om_ftRYHNOtv5gRqPaXkItHlWmiiloAI9QD.73hmGa8o1a179gi1189QLn3beQq8wmKhB5eYnBOZwmw",
+  baseUrl: "https://openmeter.cloud",
+  source: "kalaasetu-mcp",
+} as const;
+
+let openmeterClient: OpenMeter | null = null;
+
+/**
+ * Get the client ID for usage tracking.
+ * CLIENT_ID must be set by the user - throws error if missing.
+ */
+export function getClientId(): string {
+  const clientId = process.env.CLIENT_ID;
+  if (!clientId) {
+    throw new Error(
+      "CLIENT_ID environment variable is required. Set CLIENT_ID to your customer identifier for usage tracking.",
+    );
+  }
+  return clientId;
+}
+
+/**
+ * Alias for getClientId - throws if CLIENT_ID is not set.
+ * Use this to enforce billing at tool execution time.
+ */
+export const requireClientId = getClientId;
+
+/**
+ * Initialize the OpenMeter client.
+ * Uses hardcoded API token - only requires CLIENT_ID from user.
+ */
+export function initOpenMeter(): OpenMeter | null {
+  // Validate CLIENT_ID is set (will throw if not)
+  const clientId = getClientId();
+
+  if (!openmeterClient) {
+    openmeterClient = new OpenMeter({
+      baseUrl: OPENMETER_CONFIG.baseUrl,
+      apiKey: OPENMETER_CONFIG.apiToken,
+    });
+    logger.info(`[OpenMeter] Client initialized`);
+  }
+
+  return openmeterClient;
+}
+
+/**
+ * Get the OpenMeter client instance (lazy initialization).
+ */
+export function getOpenMeter(): OpenMeter | null {
+  if (!openmeterClient) {
+    return initOpenMeter();
+  }
+  return openmeterClient;
+}
+
+/**
+ * Context for tracking a tool call.
+ */
+export interface ToolCallContext {
+  toolName: string;
+  projectId?: string;
+  sessionId?: string;
+}
+
+/**
+ * Track a successful tool call in OpenMeter.
+ * Uses CLIENT_ID as the subject for billing.
+ * Tracks all tools for analytics (credit=0 for non-chargeable tools).
+ */
+export async function trackToolCall(context: ToolCallContext): Promise<void> {
+  const clientId = getClientId(); // Will throw if not set
+  const client = getOpenMeter();
+
+  if (!client) {
+    return; // Silent fail if OpenMeter client failed
+  }
+
+  const creditConfig = getToolCredits(context.toolName);
+
+  try {
+    await client.events.ingest({
+      id: crypto.randomUUID(),
+      source: OPENMETER_CONFIG.source,
+      type: "tool_calls",
+      time: new Date(),
+      subject: clientId, // CLIENT_ID is the billing subject
+      data: {
+        value: 1,
+        provider: creditConfig.provider,
+        credit: creditConfig.credits,
+        mcp_name: "kalaasetu-mcp",
+        model_name: creditConfig.modelName || context.toolName,
+        project_id: context.projectId || "unknown",
+        session_id: context.sessionId || "unknown",
+        tool_name: context.toolName,
+        customer_id: clientId,
+      },
+    });
+
+    logger.info(
+      `[OpenMeter] Tracked tool call: ${context.toolName} (${creditConfig.credits} credits)`,
+    );
+  } catch (error) {
+    // Log but don't throw - tracking failure shouldn't break tool execution
+    logger.error("[OpenMeter] Failed to track tool call:", error);
+  }
+}

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

@@ -308,7 +308,9 @@ export let PROMPT_ENHANCER_PRESETS: Record<string, PromptEnhancerConfig> = {
  * Syncs the prompt enhancer configurations with the remote server.
  */
 export async function syncPromptEnhancerConfigs(): Promise<void> {
-  const remoteConfig = await syncRemoteConfig<Record<string, PromptEnhancerConfig>>({
+  const remoteConfig = await syncRemoteConfig<
+    Record<string, PromptEnhancerConfig>
+  >({
     name: "prompt-enhancers",
     remoteUrl: "https://config.mixio.pro/mcp/prompt-enhancers.json",
     envVar: "PROMPT_ENHANCER_CONFIG_PATH",
@@ -325,7 +327,7 @@ export async function syncPromptEnhancerConfigs(): Promise<void> {
     ...remoteConfig,
   };
 
-  console.log(`[Sync] Prompt Enhancer Presets updated. Total: ${Object.keys(PROMPT_ENHANCER_PRESETS).length}`);
+  // console.log(`[Sync] Prompt Enhancer Presets updated. Total: ${Object.keys(PROMPT_ENHANCER_PRESETS).length}`);
 }
 
 // =============================================================================
@@ -337,7 +339,7 @@ export async function syncPromptEnhancerConfigs(): Promise<void> {
  * Returns undefined if the preset doesn't exist.
  */
 export function getPromptEnhancer(
-  presetName: string
+  presetName: string,
 ): PromptEnhancer | undefined {
   const config = PROMPT_ENHANCER_PRESETS[presetName];
   if (!config) {
@@ -372,7 +374,7 @@ export function listVideoEnhancerPresets(): string[] {
  * Returns PASSTHROUGH enhancer if resolution fails.
  */
 export function resolveEnhancer(
-  input: string | PromptEnhancerConfig | undefined
+  input: string | PromptEnhancerConfig | undefined,
 ): PromptEnhancer {
   if (!input) {
     return PromptEnhancer.PASSTHROUGH;
@@ -382,7 +384,7 @@ export function resolveEnhancer(
     const enhancer = getPromptEnhancer(input);
     if (!enhancer) {
       console.warn(
-        `Prompt enhancer preset '${input}' not found, using passthrough.`
+        `Prompt enhancer preset '${input}' not found, using passthrough.`,
       );
       return PromptEnhancer.PASSTHROUGH;
     }

package/src/utils/remote-sync.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { logger } from "./logger";
 
 const CACHE_DIR = path.resolve(__dirname, "..", "..", ".cache");
 
@@ -36,18 +37,20 @@ export async function syncRemoteConfig<T>(options: SyncOptions<T>): Promise<T> {
         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}`);
+          logger.info(
+            `[Sync] Using local override from ${envVar}: ${localPath}`,
+          );
           return data as T;
         }
       }
     } catch (e) {
-      console.warn(`[Sync] Failed to read local override from ${envVar}: ${e}`);
+      logger.info(`[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}...`);
+    logger.info(`[Sync] Attempting to fetch ${name} from ${remoteUrl}...`);
     const response = await fetch(remoteUrl, {
       signal: AbortSignal.timeout(5000), // 5s timeout
     });
@@ -58,15 +61,19 @@ export async function syncRemoteConfig<T>(options: SyncOptions<T>): Promise<T> {
         // 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}`);
+        logger.info(
+          `[Sync] Successfully updated ${name} and cached at ${cachePath}`,
+        );
         return data as T;
       }
-      console.warn(`[Sync] Remote data for ${name} failed validation.`);
+      logger.info(`[Sync] Remote data for ${name} failed validation.`);
     } else {
-      console.warn(`[Sync] Remote fetch for ${name} failed with status: ${response.status}`);
+      logger.info(
+        `[Sync] Remote fetch for ${name} failed with status: ${response.status}`,
+      );
     }
   } catch (e) {
-    console.warn(`[Sync] Error fetching ${name} from remote: ${e}`);
+    logger.info(`[Sync] Error fetching ${name} from remote: ${e}`);
   }
 
   // 3. Fallback to Cache
@@ -75,15 +82,17 @@ export async function syncRemoteConfig<T>(options: SyncOptions<T>): Promise<T> {
       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}`);
+        logger.info(`[Sync] Using cached version of ${name} from ${cachePath}`);
         return data as T;
       }
     }
   } catch (e) {
-    console.warn(`[Sync] Failed to read cache for ${name}: ${e}`);
+    logger.info(`[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.`);
+  logger.info(
+    `[Sync] All sync methods failed for ${name}. Using internal defaults.`,
+  );
   return fallback;
 }

package/src/utils/tool-credits.ts

@@ -0,0 +1,104 @@
+/**
+ * Tool credits configuration for OpenMeter billing.
+ * Defines which tools are chargeable and their credit costs.
+ */
+
+export interface ToolCreditConfig {
+  credits: number;
+  provider: string;
+  chargeable: boolean;
+  modelName?: string;
+}
+
+/**
+ * Credit costs for each registered MCP tool.
+ * Non-chargeable tools (discovery, status, uploads) have 0 credits.
+ */
+export const TOOL_CREDITS: Record<string, ToolCreditConfig> = {
+  // Gemini Image Generation - 5 credits
+  generateImage: {
+    credits: 5,
+    provider: "google-gemini",
+    chargeable: true,
+    modelName: "imagen-3.0-generate-002",
+  },
+  editImage: {
+    credits: 5,
+    provider: "google-gemini",
+    chargeable: true,
+    modelName: "imagen-3.0-capability-001",
+  },
+
+  // Vertex AI Video Generation - 20 credits (premium)
+  generateVideoi2v: {
+    credits: 20,
+    provider: "google-vertex",
+    chargeable: true,
+    modelName: "veo-2.0-generate-001",
+  },
+
+  // FAL AI Video Generation - 15 credits
+  fal_ltx_image_to_video: {
+    credits: 15,
+    provider: "fal-ai",
+    chargeable: true,
+    modelName: "fal-ai/ltx-2/image-to-video",
+  },
+  fal_ltx_retake_video: {
+    credits: 15,
+    provider: "fal-ai",
+    chargeable: true,
+    modelName: "fal-ai/ltx-2/retake-video",
+  },
+
+  // Non-chargeable utility tools
+  fal_upload_file: {
+    credits: 0,
+    provider: "fal-ai",
+    chargeable: false,
+  },
+  fal_list_presets: {
+    credits: 0,
+    provider: "fal-ai",
+    chargeable: false,
+  },
+  fal_get_preset_details: {
+    credits: 0,
+    provider: "fal-ai",
+    chargeable: false,
+  },
+  get_generation_status: {
+    credits: 0,
+    provider: "internal",
+    chargeable: false,
+  },
+};
+
+/**
+ * Get credit config for a tool. Returns default (0 credits, not chargeable) for unknown tools.
+ */
+export function getToolCredits(toolName: string): ToolCreditConfig {
+  // Check for exact match first
+  const config = TOOL_CREDITS[toolName];
+  if (config) {
+    return config;
+  }
+
+  // Check for dynamic FAL tools (prefixed with fal_)
+  if (toolName.startsWith("fal_")) {
+    // Default FAL tool credits for dynamic presets
+    return {
+      credits: 15,
+      provider: "fal-ai",
+      chargeable: true,
+      modelName: toolName,
+    };
+  }
+
+  // Unknown tool - not chargeable
+  return {
+    credits: 0,
+    provider: "unknown",
+    chargeable: false,
+  };
+}

package/src/utils/tool-wrapper.ts

@@ -1,4 +1,10 @@
 import { z } from "zod";
+import { logger } from "./logger";
+import {
+  trackToolCall,
+  requireClientId,
+  type ToolCallContext,
+} from "./openmeter";
 
 /**
  * Standardized error result for MCP tools
@@ -11,6 +17,16 @@ export interface ToolErrorResult {
   }>;
 }
 
+/**
+ * Optional tracking context for tool execution
+ */
+export interface TrackingContext {
+  toolName: string;
+  projectId?: string;
+  sessionId?: string;
+  userId?: string;
+}
+
 /**
  * Helper to check if a result is a ToolErrorResult
  */
@@ -32,7 +48,7 @@ export function formatToolError(error: unknown, context?: string): string {
   // Enhanced Zod Error Handling
   if (error instanceof z.ZodError) {
     const issues = error.issues.map(
-      (issue) => `[${issue.path.join(".")}] ${issue.message}`
+      (issue) => `[${issue.path.join(".")}] ${issue.message}`,
     );
     errorMessage = `Validation Error: ${issues.join("; ")}`;
   } else {
@@ -49,9 +65,9 @@ export function formatToolError(error: unknown, context?: string): string {
   }
 
   // Secure logging (never expose stack traces to the LLM, but log them internally)
-  console.error(
+  logger.error(
     `[Tool Error] ${context ? `${context}: ` : ""}${errorMessage}`,
-    error
+    error,
   );
 
   // Return sanitized message for the LLM
@@ -61,16 +77,31 @@ export function formatToolError(error: unknown, context?: string): string {
 }
 
 /**
- * Safely execute a tool function with standardized error handling
+ * Safely execute a tool function with standardized error handling and optional usage tracking.
  * @param fn The async tool execution function
  * @param context Optional context name (e.g. tool name) for logging
+ * @param tracking Optional tracking context for OpenMeter billing
  */
 export async function safeToolExecute<T>(
   fn: () => Promise<T>,
-  context?: string
+  context?: string,
+  tracking?: TrackingContext,
 ): Promise<T | ToolErrorResult> {
   try {
-    return await fn();
+    // Validate CLIENT_ID is set before executing any tool
+    requireClientId();
+
+    const result = await fn();
+
+    // Track successful execution if tracking context provided
+    if (tracking) {
+      // Fire and forget - don't block on tracking
+      trackToolCall(tracking).catch((err) => {
+        logger.error("[OpenMeter] Tracking background error:", err);
+      });
+    }
+
+    return result;
   } catch (error) {
     const errorText = formatToolError(error, context);
     return {

package/src/utils/url-file.ts

@@ -3,6 +3,7 @@ import * as path from "path";
 import * as os from "os";
 import { getStorage } from "../storage";
 import { generateTimestampedFilename } from "./filename";
+import { logger } from "./logger";
 
 export interface LocalFileResult {
   path: string;
@@ -32,7 +33,7 @@ export async function ensureLocalFile(input: string): Promise<LocalFileResult> {
       const response = await fetch(input);
       if (!response.ok) {
         throw new Error(
-          `Failed to download URL: ${input} (${response.status} ${response.statusText})`
+          `Failed to download URL: ${input} (${response.status} ${response.statusText})`,
         );
       }
 
@@ -49,7 +50,7 @@ export async function ensureLocalFile(input: string): Promise<LocalFileResult> {
               fs.unlinkSync(tempFilePath);
             }
           } catch (e) {
-            console.error(`Failed to cleanup temp file ${tempFilePath}:`, e);
+            logger.error(`Failed to cleanup temp file ${tempFilePath}:`, e);
           }
         },
       };
@@ -78,7 +79,7 @@ export async function ensureLocalFile(input: string): Promise<LocalFileResult> {
         `File not found: ${input}\n` +
           `Resolved path: ${resolvedPath}\n` +
           `Is absolute: ${isAbsolute}\n` +
-          `CWD: ${process.cwd()}`
+          `CWD: ${process.cwd()}`,
       );
     }
 

package/src/test-context.ts

@@ -1,52 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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();