@codingmantra/mcp-server 0.1.4 → 0.2.2

package/README.md

@@ -1,73 +1,186 @@
 # @codingmantra/mcp-server
 
-A **Model Context Protocol (MCP)** server that connects AI agents (like Claude Desktop, Cursor, and Cline) to CodingMantra's AI generation tools.
+The official **Model Context Protocol (MCP)** server connecting AI assistants (Claude Desktop, Cursor, Cline, and Antigravity) to CodingMantra's generative AI media engines.
 
-## Features
+## What's New in v0.2.2
+- **Current API coverage:** Story Teller, HeyGen Talking Avatar IV, and Jewellery Rate Poster tools.
+- **Video contract alignment:** Required prompt/model/duration/resolution/aspect ratio, character descriptions, seed, guidance, and local reference-image resolution.
+- **Terminal job handling:** Polling stops for completed, failed, or cancelled jobs.
 
-- **Product Photography** — Generate AI studio product photos with custom scenes, templates, and dynamic logo/text overlays. Supports advanced options including `model`, `resolution` (1K, 2K, 4K), and `aspectRatio`.
-- **Logo Creator** — Generate AI brand logos with style, references, and color customization. Supports advanced options including `modelId`, `resolution` (1K, 2K), and `aspectRatio`.
-- **QR Code Generator** — Create custom QR codes (URL, text, WiFi, vCard, UPI, email) with branding and colors.
-- **Video Generation** — Asynchronously generate high-quality AI videos. Supports:
-  - Product Videography
-  - Apparel Try-On Videos
-  - Festival & Event Videos
-  - Jewelry Showcase Videos
-  - Logo Animation
-- **Asynchronous Job Polling** — Tools support a polling mechanism (`check_video_job_status`) to track long-running video generation tasks.
+- 🖼️ **Native MCP Image Output**: Generated images (including QR codes, logos, try-on shots, and product photos) return standard MCP `ImageContent` so they render directly in your AI assistant's chat window.
+- 📁 **Local File Path Resolution**: Pass local paths (e.g. `./shoe.png` or `/Users/.../portrait.jpg`) directly in tool arguments—the server automatically reads and encodes them as base64 data URIs.
+- ⚡ **Expanded Tool Suite (28 Tools)**: Expanded image generation support including Passport Photos, Baby Milestones, YouTube Thumbnails, Blog Images, Nano Banana, Professional Photography, Sketch-to-Real, Human Builder, Apparel/Product/Jewelry Try-On, Festival Posts, Upscaling, and Discovery.
+- 🎯 **Advanced Model & Resolution Parameters**: Direct support for `model`, `modelId`, `promptId`, custom reference images, and server-side credit synchronization.
+- 🛡️ **Graceful Error Handling & 120s Timeout**: Informative error diagnostics when API keys are missing or requests time out, with clean stdio protocol execution.
 
-## Setup
+---
 
-### 1. Get an API Key
+## Features & Tool Suite
 
+The server exposes **28 specialized generative and utility tools** over standard I/O (`stdio`):
+
+### 1. Synchronous Image Generation (Immediate Inline Image Output)
+- **`generate_product_photo`** — Generates studio-grade commercial product photos with custom background scenes, ambient occlusion contact shadows, camera optics, resolutions (1K, 2K, 4K), aspect ratios, and dynamic logo/text overlays.
+- **`generate_logo`** — Generates bespoke vector-style or 3D brand logos with customizable typography, colors, industries, and reference images.
+- **`try_on_jewelry`** — Virtual luxury jewelry try-on with model styling, metal & gemstone preservation, Fresnel light dispersion, and anatomical contact shadows.
+- **`try_on_apparel`** — Virtual fashion apparel try-on with natural gravitational folds, realistic fabric tension, and ground contact shadows.
+- **`try_on_product`** — Universal commercial product staging and virtual try-on across footwear, accessories, cosmetics, eyewear, and furniture with 3-point studio lighting.
+- **`generate_festival_post`** — High-conversion festival marketing graphics, holiday greetings (Diwali, Eid, Christmas, New Year), and promotional banners with product and logo integration.
+- **`build_human`** — Creates photorealistic AI human models tailored for brand photography, fashion, and marketing with complete demographic, facial, hair, and body customization, plus multi-view character sheets (2×2 grid).
+- **`generate_youtube_thumbnail`** — High-CTR YouTube thumbnails with rule-of-thirds composition, emotional human expressions, vibrant contrast separation, and legible bold text overlays.
+- **`generate_passport_photo`** — Converts any portrait into an official, compliant passport or visa identity photo with pixel-level facial identity preservation.
+- **`sketch_to_real`** — Transforms hand-drawn sketches, line drawings, or product drafts into photorealistic commercial images while preserving ground-truth silhouettes.
+- **`edit_professional_photo`** — Transforms and grades portraits and personal photos into magazine-grade studio or editorial photography with natural dermal micro-pores and optical depth of field.
+- **`edit_nano_banana`** — Creative multi-reference image editor and compositor combining multiple subjects, backgrounds, and artistic styles (figurines, chibi, anime, retro, 3D renders).
+- **`generate_blog_image`** — Generates high-impact, editorial blog hero images, article thumbnails, and banners with clean composition, visual hierarchy, intentional negative space, and exact text overlays.
+- **`generate_baby_milestone`** — Creates magical baby milestone keepsake portraits with pristine subject preservation, seamless background cutout, and organic milestone text integration.
+- **`upscale_image`** — Restores a reference image with Pro AI at 4K (60 credits), checks output size and proportions, and returns the image synchronously. Fine details can change; review the result.
+
+- **`generate_jewellery_rate_poster`** — Branded gold and silver rate posters using caller-supplied rates, business details, and optional product/logo images.
+
+### 2. QR Code Tools
+- **`generate_qr_code`** — Full-featured custom QR code generator supporting URLs, plain text, Wi-Fi credentials, vCards, emails, and UPI payment strings with custom styling, colors, and error correction.
+- **`generate_qr_code_simple`** — Lightweight single-parameter QR code generation from text or URL.
+
+### 3. Account & Discovery Utilities
+- **`get_user_credits`** — Checks your current CodingMantra AI wallet credit balance in real time.
+- **`list_image_models`** — Queries all available CodingMantra AI image generation models (Gemini Flash, Pro, Grok Imagine 2.0, GPT Image 2.5 Flare), supported resolutions, aspect ratios, and credit costs.
+
+### 4. Asynchronous Video Tools (with Job Polling)
+- **`generate_product_video`** — Commercial product videography (Google Veo 3.1 & OpenRouter Wan 3.0).
+- **`generate_apparel_video`** — Model runway and apparel try-on video showcase.
+- **`generate_festival_video`** — Festive event greetings and celebratory motion graphics.
+- **`generate_jewelry_video`** — High-end luxury jewelry videography with realistic optical brilliance dispersion.
+- **`generate_logo_video`** — 3D logo reveal and motion graphic intros.
+- **`generate_story_video`** — Cinematic stories with character descriptions, sound effects, and visual atmosphere.
+- **`generate_talking_avatar`** — HeyGen Avatar IV portrait animation with a script, HeyGen voice ID, and performance controls.
+- **`check_video_job_status`** — Real-time polling tool to track background video rendering status (`pending` → `processing` → `completed` / `failed` / `cancelled`).
+
+All generations automatically deduct credits from your CodingMantra wallet and persist outputs directly to your online media gallery at [https://codingmantra.com/my-gallery](https://codingmantra.com/my-gallery).
+
+---
+
+## Video parameters
+
+General video tools require `prompt` (10–5000 characters), `model`, `timeDuration`, `resolution`, and `aspectRatio`. Use model-supported settings; Veo requires 8 seconds for 1080p, references, or an end frame. Choose one image mode: main image, frames, or references. Reference images accept URLs, data URIs, or local paths (up to 3 for Veo). Optional settings include characters, seed, guidanceScale, soundEffects, and styleAmbiance.
+
+Talking Avatar requires `image` (local PNG/JPEG/WebP path or data URI, not a public URL), `script`, and a HeyGen `voiceId`. Optional controls include targetDuration (5–120 seconds, default 15), speed (0.5–1.5), performancePreset, expressiveness, motionPrompt, backgroundMode/backgroundColor, captions, title, resolution (720p or 1080p, default 1080p), and aspectRatio (9:16, 1:1, or 16:9, default 9:16). Scripts must fit the duration budget; credits are calculated by the backend. Poll every 15–30 seconds until completed, failed, or cancelled.
+
+---
+
+## Quick Setup
+
+### 1. Obtain Your API Key
 Generate an API key from your [CodingMantra Dashboard → My API Keys](https://codingmantra.com/my-api).
 
-### 2. Configure Claude Desktop
+### 2. Configure Your AI Client
 
-Add the following to your `claude_desktop_config.json`:
+#### A. Claude Desktop
+Add to your `claude_desktop_config.json`:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
     "codingmantra": {
       "command": "npx",
-      "args": ["-y", "@codingmantra/mcp-server"],
+      "args": ["-y", "@codingmantra/mcp-server@latest"],
       "env": {
-        "CODINGMANTRA_API_KEY": "YOUR_API_KEY"
+        "CODINGMANTRA_API_KEY": "YOUR_CODINGMANTRA_API_KEY"
       }
     }
   }
 }
 ```
 
-### 3. Restart Claude Desktop
-
-After saving the config, restart Claude Desktop. You can now ask Claude to:
+#### B. Cursor
+Add to `.cursor/mcp.json` in your project or global settings:
 
-- *"Generate a product photo of this watch on a marble surface"*
-- *"Create a minimalist logo for my company TechFlow"*
-- *"Generate a QR code for https://codingmantra.com"*
-- *"Generate a 4-second jewelry video showcasing this ring with a cinematic camera spin, and then check its status until it completes."*
+```json
+{
+  "mcpServers": {
+    "codingmantra": {
+      "command": "npx",
+      "args": ["-y", "@codingmantra/mcp-server@latest"],
+      "env": {
+        "CODINGMANTRA_API_KEY": "YOUR_CODINGMANTRA_API_KEY"
+      }
+    }
+  }
+}
+```
 
-## Development
+#### C. Cline (VS Code Extension)
+In Cline Settings → MCP Servers, add:
 
-```bash
-# Install dependencies
-npm install
+```json
+{
+  "codingmantra": {
+    "command": "npx",
+    "args": ["-y", "@codingmantra/mcp-server@latest"],
+    "env": {
+      "CODINGMANTRA_API_KEY": "YOUR_CODINGMANTRA_API_KEY"
+    }
+  }
+}
+```
 
-# Build
-npm run build
+#### D. Antigravity / Agentic Workspace
+Add to `.agents/mcp_config.json`:
 
-# Run locally
-CODINGMANTRA_API_KEY=your_key npm start
+```json
+{
+  "mcpServers": {
+    "codingmantra": {
+      "command": "npx",
+      "args": ["-y", "@codingmantra/mcp-server@latest"],
+      "env": {
+        "CODINGMANTRA_API_KEY": "YOUR_CODINGMANTRA_API_KEY"
+      }
+    }
+  }
+}
 ```
 
+---
+
+## Example Natural Language Prompts
+
+Once configured, restart your AI assistant and try prompts like:
+
+- *"How many credits do I have left in my CodingMantra account?"*
+- *"Generate a luxury product photo of this perfume bottle on a dark reflective obsidian pedestal with subtle mist."*
+- *"Virtually try on this diamond necklace on an elegant editorial model wearing a black velvet evening gown."*
+- *"Create a YouTube thumbnail for my video 'Top 10 AI Tools of 2026' with bold text and high contrast."*
+- *"Create a modern minimalist geometric logo for a fintech company called 'Acuity'."*
+- *"Generate a UPI payment QR code for merchant@upi with an amount of 500."*
+- *"Create a 4-second jewelry video showing this diamond ring rotating on a black velvet pedestal with cinematic sunbeam flares, and check its progress until it's finished."*
+
+---
+
 ## Environment Variables
 
-| Variable | Required | Description |
-|---|---|---|
-| `CODINGMANTRA_API_KEY` | ✅ | Your CodingMantra developer API key |
-| `CODINGMANTRA_API_URL` | ❌ | Custom API base URL (default: `https://codingmantra.com/api`) |
+| Variable | Required | Description | Default |
+|---|---|---|---|
+| `CODINGMANTRA_API_KEY` | ✅ | Your CodingMantra developer API key (`cm_...`) | None |
+| `CODINGMANTRA_API_URL` | ❌ | Custom API base URL | `https://codingmantra.com/api` |
+
+---
+
+## Local Development
+
+```bash
+# Build TypeScript
+npm run build
+
+# Verify stdio contracts with a mock API (no credits spent)
+npm test
+
+# Start server directly on stdio
+CODINGMANTRA_API_KEY=your_key node build/index.js
+```
 
 ## License
 
-Private — Part of the CodingMantra Web Portal.
+Private & Proprietary — Part of the CodingMantra Web Portal © 2026. All rights reserved.

package/build/api-client.js

@@ -1,33 +1,63 @@
 import dotenv from 'dotenv';
-dotenv.config();
-const API_KEY = process.env.CODINGMANTRA_API_KEY;
-const API_BASE_URL = process.env.CODINGMANTRA_API_URL || 'https://codingmantra.com/api';
-if (!API_KEY) {
-    console.error('CRITICAL: CODINGMANTRA_API_KEY environment variable is missing.');
-    console.error('Please set it in your environment or .env file before running this server.');
-    process.exit(1);
+dotenv.config({ quiet: true });
+const DEFAULT_TIMEOUT_MS = 120_000; // 2 minutes for heavy generation tasks
+export function getApiKey() {
+    return process.env.CODINGMANTRA_API_KEY;
+}
+export function getApiBaseUrl() {
+    return process.env.CODINGMANTRA_API_URL || 'https://codingmantra.com/api';
+}
+if (!getApiKey()) {
+    console.error('[CodingMantra MCP] WARNING: CODINGMANTRA_API_KEY environment variable is not set.');
+    console.error('[CodingMantra MCP] Please configure your API key in your MCP client settings or .env file.');
+    console.error('[CodingMantra MCP] Generate an API key from https://codingmantra.com/my-api');
 }
 /**
  * Helper to make authenticated requests to the CodingMantra API.
  */
 export async function apiClient(endpoint, options = {}) {
-    const url = `${API_BASE_URL}${endpoint.startsWith('/') ? endpoint : `/${endpoint}`}`;
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        throw new Error('CODINGMANTRA_API_KEY environment variable is missing. ' +
+            'Please set your API key in your MCP server configuration. ' +
+            'You can generate an API key at https://codingmantra.com/my-api');
+    }
+    const baseUrl = getApiBaseUrl();
+    const url = `${baseUrl}${endpoint.startsWith('/') ? endpoint : `/${endpoint}`}`;
     const headers = new Headers(options.headers || {});
-    headers.set('Authorization', `Bearer ${API_KEY}`);
+    headers.set('Authorization', `Bearer ${apiKey}`);
     if (!(options.body instanceof FormData)) {
         headers.set('Content-Type', 'application/json');
     }
-    const response = await fetch(url, {
-        ...options,
-        headers,
-    });
+    // Set timeout if no external abort signal provided
+    const signal = options.signal || AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            headers,
+            signal,
+        });
+    }
+    catch (fetchError) {
+        if (fetchError?.name === 'TimeoutError' || fetchError?.name === 'AbortError') {
+            throw new Error(`CodingMantra API request timed out after ${DEFAULT_TIMEOUT_MS / 1000}s for ${endpoint}`);
+        }
+        throw new Error(`Failed to connect to CodingMantra API at ${url}: ${fetchError?.message || fetchError}`);
+    }
     if (!response.ok) {
-        let errorMsg = `API request failed with status ${response.status} ${response.statusText}`;
+        let errorMsg = `API request failed (${response.status} ${response.statusText})`;
         try {
             const errorData = await response.json();
-            if (errorData?.error?.message) {
+            if (typeof errorData?.error === 'string') {
+                errorMsg += `: ${errorData.error}`;
+            }
+            else if (errorData?.error?.message) {
                 errorMsg += `: ${errorData.error.message}`;
             }
+            else if (errorData?.message) {
+                errorMsg += `: ${errorData.message}`;
+            }
             else {
                 errorMsg += `: ${JSON.stringify(errorData)}`;
             }

package/build/image-utils.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Extracts raw base64 data and MIME type from a data URI.
+ */
+export function parseDataUri(dataUri) {
+    if (!dataUri || typeof dataUri !== 'string')
+        return null;
+    const match = dataUri.match(/^data:([^;]+);base64,(.+)$/);
+    if (match && match[1] && match[2]) {
+        return {
+            mimeType: match[1],
+            data: match[2],
+        };
+    }
+    return null;
+}
+/**
+ * Detects MIME type from a file path extension.
+ */
+function getMimeTypeFromExt(filePath) {
+    const ext = path.extname(filePath).toLowerCase().replace('.', '');
+    switch (ext) {
+        case 'png':
+            return 'image/png';
+        case 'jpg':
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'webp':
+            return 'image/webp';
+        case 'svg':
+            return 'image/svg+xml';
+        case 'gif':
+            return 'image/gif';
+        default:
+            return 'image/png';
+    }
+}
+/**
+ * Resolves an image input string. If it's a local file path on disk,
+ * reads it and converts to a base64 data URI.
+ * If already a URL or data URI, returns as is.
+ */
+export function resolveImageInput(input) {
+    if (!input || typeof input !== 'string')
+        return '';
+    const trimmed = input.trim();
+    // Already a remote URL or data URI
+    if (trimmed.startsWith('data:') || trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+        return trimmed;
+    }
+    // Check if it's a local file path
+    try {
+        const resolvedPath = path.isAbsolute(trimmed) ? trimmed : path.resolve(process.cwd(), trimmed);
+        if (fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isFile()) {
+            const buffer = fs.readFileSync(resolvedPath);
+            const mimeType = getMimeTypeFromExt(resolvedPath);
+            return `data:${mimeType};base64,${buffer.toString('base64')}`;
+        }
+    }
+    catch {
+        // If any filesystem read error, fall through
+    }
+    return trimmed;
+}
+/**
+ * Helper to resolve an array of images or single image inputs.
+ */
+export function resolveImagesArray(images) {
+    if (!images || !Array.isArray(images))
+        return [];
+    return images.map(item => {
+        const rawSrc = item.dataUrl || item.path || item.url || '';
+        const resolved = resolveImageInput(rawSrc);
+        if (resolved.startsWith('data:')) {
+            return { ...item, dataUrl: resolved };
+        }
+        return { ...item, url: resolved };
+    });
+}
+/**
+ * Standardizes synchronous image generation responses into MCP content.
+ * Returns both native ImageContent (for visual render in Claude/Cursor)
+ * and rich Markdown text.
+ */
+export function formatImageToolResult(result, successTitle) {
+    const content = [];
+    const rawData = result?.data || result;
+    // Extract all potential image data URIs
+    const dataUris = [];
+    if (rawData?.photoDataUri)
+        dataUris.push(rawData.photoDataUri);
+    if (Array.isArray(rawData?.photoDataUris)) {
+        for (const uri of rawData.photoDataUris) {
+            if (uri && !dataUris.includes(uri))
+                dataUris.push(uri);
+        }
+    }
+    if (rawData?.qrCodeDataUrl)
+        dataUris.push(rawData.qrCodeDataUrl);
+    if (rawData?.upscaledImage)
+        dataUris.push(rawData.upscaledImage);
+    if (rawData?.output && typeof rawData.output === 'string' && rawData.output.startsWith('data:')) {
+        dataUris.push(rawData.output);
+    }
+    // Add native ImageContent blocks for each generated image
+    for (const uri of dataUris) {
+        const parsed = parseDataUri(uri);
+        if (parsed) {
+            content.push({
+                type: 'image',
+                data: parsed.data,
+                mimeType: parsed.mimeType,
+            });
+        }
+    }
+    // Build Markdown text summary
+    let text = `### ✅ ${successTitle}\n\n`;
+    const publicUrls = [];
+    if (rawData?.imageUrl)
+        publicUrls.push(rawData.imageUrl);
+    if (Array.isArray(rawData?.imageUrls)) {
+        for (const u of rawData.imageUrls) {
+            if (u && !publicUrls.includes(u))
+                publicUrls.push(u);
+        }
+    }
+    if (publicUrls.length > 0) {
+        if (publicUrls.length === 1) {
+            text += `**Public Image URL:** [View Full Resolution](${publicUrls[0]})\n\n`;
+        }
+        else {
+            text += `**Public Image URLs:**\n` + publicUrls.map((u, i) => `- [Image ${i + 1}](${u})`).join('\n') + `\n\n`;
+        }
+    }
+    if (dataUris.length > 0) {
+        text += `🖼️ **Inline Media:** Generated ${dataUris.length} image(s) rendered directly above.\n`;
+    }
+    text += `\n📁 **Gallery:** Output saved to your [CodingMantra Media Gallery](https://codingmantra.com/my-gallery).\n`;
+    content.push({
+        type: 'text',
+        text: text.trim(),
+    });
+    return { content };
+}