@vespermcp/mcp-server 1.0.3 → 1.0.5

package/README.md

@@ -55,9 +55,16 @@ pip install opencv-python pillow numpy librosa soundfile
 
 ## ⚙️ MCP Configuration
 
-Add Vesper to your MCP settings file:
-
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+### For Cursor
+1. Go to **Settings** > **Features** > **MCP**
+2. Click **Add New MCP Server**
+3. Enter:
+   - **Name**: `vesper`
+   - **Type**: `command`
+   - **Command**: `vesper`
+
+### For Claude Desktop
+Vesper attempts to auto-configure itself! Restart Claude and check. If not:
 
 ```json
 {

package/build/index.js

@@ -57,6 +57,13 @@ jobManager.on("jobUpdated", (job) => {
         data: `${emoji} [Job ${job.id.substring(0, 8)}] ${progress} ${job.status_text}`
     });
 });
+// IMPORTANT: Execute jobs when the manager emits them
+// This connects the queue logic to the execution context
+jobManager.on("processJob", async (job, execute) => {
+    // The JobManager controls concurrency, so if we receive this event,
+    // we should execute the job immediately.
+    await execute();
+});
 // Create the server
 const server = new Server({
     name: "vesper",
@@ -379,35 +386,51 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const job = jobManager.createJob("prepare", 0, { query });
             // Orchestrated Background Task
             jobManager.runJob(job.id, async (update) => {
-                update({ progress: 10, status_text: "Searching for best dataset matching query..." });
-                const results = await searchEngine.search(query, { limit: 1 });
-                if (results.length === 0)
-                    throw new Error("No datasets found matching the query.");
-                const topDataset = results[0];
-                // Phase 6: Real Ingestion
-                update({
-                    progress: 20,
-                    status_text: `Matched: ${topDataset.name} (${topDataset.source})`
-                });
-                const source = topDataset.source;
-                const filePath = await dataIngestor.ensureData(topDataset.id, source, (msg, prog) => {
+                try {
+                    update({ progress: 10, status_text: "Searching for best dataset matching query..." });
+                    const results = await searchEngine.search(query, { limit: 1 });
+                    if (results.length === 0) {
+                        throw new Error("No datasets found matching the query. Try refining your search terms.");
+                    }
+                    const topDataset = results[0];
+                    // Phase 6: Real Ingestion
                     update({
-                        status_text: msg,
-                        progress: prog !== undefined ? 20 + Math.floor(prog * 0.3) : undefined // 20% -> 50%
+                        progress: 20,
+                        status_text: `Matched: ${topDataset.name} (${topDataset.source})`
                     });
-                });
-                update({ progress: 55, status_text: "Analyzing dataset quality..." });
-                const quality = await qualityAnalyzer.analyze(filePath);
-                const pipelineResult = await pipelineExecutor.runPipeline(topDataset.id, filePath, "csv", (msg) => {
-                    update({ status_text: msg });
-                });
-                update({ progress: 90, status_text: "Installing dataset into codebase..." });
-                const installPath = await installService.install(topDataset.id, pipelineResult.final_output_path);
-                update({ progress: 100, status_text: "Preparation complete!" });
-                const message = `✅ Preparation complete for ${topDataset.name}.\n` +
-                    `📦 Dataset installed to: ${installPath}\n` +
-                    `🚀 You can now use this dataset for training your models.`;
-                return message;
+                    const source = topDataset.source;
+                    // Pre-check credentials for Kaggle to fail fast with helpful message
+                    if (source === "kaggle" && !dataIngestor.hasKaggleCredentials()) {
+                        const errorMsg = dataIngestor.getKaggleCredentialError();
+                        throw new Error(errorMsg);
+                    }
+                    const filePath = await dataIngestor.ensureData(topDataset.id, source, (msg, prog) => {
+                        update({
+                            status_text: msg,
+                            progress: prog !== undefined ? 20 + Math.floor(prog * 0.3) : undefined // 20% -> 50%
+                        });
+                    });
+                    update({ progress: 55, status_text: "Analyzing dataset quality..." });
+                    const quality = await qualityAnalyzer.analyze(filePath);
+                    const pipelineResult = await pipelineExecutor.runPipeline(topDataset.id, filePath, "csv", (msg) => {
+                        update({ status_text: msg });
+                    });
+                    update({ progress: 90, status_text: "Installing dataset into codebase..." });
+                    const installPath = await installService.install(topDataset.id, pipelineResult.final_output_path);
+                    update({ progress: 100, status_text: "Preparation complete!" });
+                    const message = `✅ Preparation complete for ${topDataset.name}.\n` +
+                        `📦 Dataset installed to: ${installPath}\n` +
+                        `🚀 You can now use this dataset for training your models.`;
+                    return message;
+                }
+                catch (error) {
+                    // Re-throw with enhanced error message for credential issues
+                    const errorMessage = error.message || String(error);
+                    if (errorMessage.includes("Kaggle credentials") || errorMessage.includes("KAGGLE")) {
+                        throw new Error(errorMessage);
+                    }
+                    throw error;
+                }
             });
             return {
                 content: [{ type: "text", text: `Autonomous preparation job started. ID: ${job.id}. Use check_job_status to monitor progress.` }]

package/build/ingestion/ingestor.js

@@ -18,6 +18,18 @@ export class DataIngestor {
         this.hfDownloader = new HFDownloader();
         this.kaggleDownloader = new KaggleDownloader();
     }
+    /**
+     * Check if Kaggle credentials are available
+     */
+    hasKaggleCredentials() {
+        return this.kaggleDownloader.hasCredentials();
+    }
+    /**
+     * Get helpful error message if Kaggle credentials are missing
+     */
+    getKaggleCredentialError() {
+        return this.kaggleDownloader.getCredentialError();
+    }
     /**
      * Ensures a dataset is available locally
      */
@@ -55,6 +67,12 @@ export class DataIngestor {
             }
         }
         else if (source === "kaggle") {
+            // Check credentials early and provide helpful error
+            if (!this.kaggleDownloader.hasCredentials()) {
+                const errorMsg = this.kaggleDownloader.getCredentialError();
+                this.failDownload(datasetId, errorMsg);
+                throw new Error(errorMsg);
+            }
             const safeId = datasetId.replace("kaggle:", "").replace(/\//g, "_");
             const targetDir = path.join(this.rawDataDir, `kaggle_${safeId}`);
             this.store.registerDownload(datasetId, targetDir, "downloading");

package/build/ingestion/kaggle-downloader.js

@@ -11,13 +11,36 @@ export class KaggleDownloader {
         this.key = key || process.env.KAGGLE_KEY || "";
         this.downloader = new RobustDownloader();
     }
+    /**
+     * Check if Kaggle credentials are available
+     */
+    hasCredentials() {
+        return !!(this.username && this.key);
+    }
+    /**
+     * Get a helpful error message if credentials are missing
+     */
+    getCredentialError() {
+        if (!this.username && !this.key) {
+            return "Kaggle credentials missing. Please set KAGGLE_USERNAME and KAGGLE_KEY environment variables.\n" +
+                "💡 Tip: Get your API token from https://www.kaggle.com/settings → API → Create New Token\n" +
+                "💡 Alternative: Download the dataset manually and use analyze_quality() on local files.";
+        }
+        if (!this.username) {
+            return "KAGGLE_USERNAME is missing. Please set it in your MCP config or environment variables.";
+        }
+        if (!this.key) {
+            return "KAGGLE_KEY is missing. Please set it in your MCP config or environment variables.";
+        }
+        return "";
+    }
     /**
      * Downloads and extracts a Kaggle dataset
      * returns the path to the primary data file
      */
     async download(repoId, targetDir, onProgress) {
-        if (!this.username || !this.key) {
-            throw new Error("Kaggle credentials missing (KAGGLE_USERNAME, KAGGLE_KEY)");
+        if (!this.hasCredentials()) {
+            throw new Error(this.getCredentialError());
         }
         const auth = Buffer.from(`${this.username}:${this.key}`).toString('base64');
         const url = `https://www.kaggle.com/api/v1/datasets/download/${repoId}`;

package/build/quality/image-analyzer.js

@@ -23,22 +23,64 @@ export class ImageAnalyzer {
             process.stderr.on("data", (data) => {
                 stderr += data.toString();
             });
+            process.on("error", (err) => {
+                if (err.code === "ENOENT") {
+                    // Python not found - return a graceful failure report
+                    resolve({
+                        total_images: 1,
+                        ok_images: 0,
+                        failed_images: 1,
+                        details: [{
+                                status: "error",
+                                error: "Python not installed or not in PATH. Please install Python to use image analysis features."
+                            }]
+                    });
+                }
+                else {
+                    reject(new Error(`Failed to start image analysis process: ${err.message}`));
+                }
+            });
             process.on("close", (code) => {
                 if (code !== 0) {
-                    reject(new Error(`Image Analyzer failed (code ${code}): ${stderr}`));
+                    // Handle case where script fails
+                    resolve({
+                        total_images: 1,
+                        ok_images: 0,
+                        failed_images: 1,
+                        details: [{
+                                status: "error",
+                                error: `Image Analyzer process failed (code ${code}): ${stderr || "Unknown error"}`
+                            }]
+                    });
                     return;
                 }
                 try {
                     const result = JSON.parse(stdout);
                     if (result.error) {
-                        reject(new Error(result.error));
+                        resolve({
+                            total_images: 1,
+                            ok_images: 0,
+                            failed_images: 1,
+                            details: [{
+                                    status: "error",
+                                    error: result.error
+                                }]
+                        });
                     }
                     else {
                         resolve(result);
                     }
                 }
                 catch (e) {
-                    reject(new Error(`Failed to parse image analyzer output: ${stdout}`));
+                    resolve({
+                        total_images: 1,
+                        ok_images: 0,
+                        failed_images: 1,
+                        details: [{
+                                status: "error",
+                                error: `Failed to parse image analyzer output: ${stdout}`
+                            }]
+                    });
                 }
             });
         });

package/build/quality/media-analyzer.js

@@ -23,22 +23,65 @@ export class MediaAnalyzer {
             process.stderr.on("data", (data) => {
                 stderr += data.toString();
             });
+            process.on("error", (err) => {
+                if (err.code === "ENOENT") {
+                    // Python not found - return a graceful failure report
+                    resolve({
+                        total_files: 1,
+                        ok_files: 0,
+                        failed_files: 1,
+                        details: [{
+                                status: "error",
+                                error: "Python not installed or not in PATH. Please install Python to use media analysis features."
+                            }]
+                    });
+                }
+                else {
+                    reject(new Error(`Failed to start media analysis process: ${err.message}`));
+                }
+            });
             process.on("close", (code) => {
                 if (code !== 0) {
-                    reject(new Error(`Media Analyzer failed (code ${code}): ${stderr}`));
+                    // Handle case where python exists but script fails
+                    resolve({
+                        total_files: 1,
+                        ok_files: 0,
+                        failed_files: 1,
+                        details: [{
+                                status: "error",
+                                error: `Media Analyzer process failed (code ${code}): ${stderr || "Unknown error"}`
+                            }]
+                    });
                     return;
                 }
                 try {
                     const result = JSON.parse(stdout);
                     if (result.error) {
-                        reject(new Error(result.error));
+                        // Return error as part of report instead of rejecting
+                        resolve({
+                            total_files: 1,
+                            ok_files: 0,
+                            failed_files: 1,
+                            details: [{
+                                    status: "error",
+                                    error: result.error
+                                }]
+                        });
                     }
                     else {
                         resolve(result);
                     }
                 }
                 catch (e) {
-                    reject(new Error(`Failed to parse media analyzer output: ${stdout}`));
+                    resolve({
+                        total_files: 1,
+                        ok_files: 0,
+                        failed_files: 1,
+                        details: [{
+                                status: "error",
+                                error: `Failed to parse media analyzer output: ${stdout}`
+                            }]
+                    });
                 }
             });
         });

package/build/tools/formatter.js

@@ -21,10 +21,16 @@ export function formatJobStatus(job) {
     output += `Progress: ${bar} ${job.progress}%\n`;
     output += `Activity: ${job.status_text}\n`;
     if (job.result_url) {
-        output += `Result: ${job.result_url}\n`;
+        output += `\n✅ Result: ${job.result_url}\n`;
     }
     if (job.error) {
-        output += `Error: ${job.error}\n`;
+        output += `\n❌ ERROR:\n`;
+        // Format multi-line errors nicely
+        const errorLines = job.error.split('\n');
+        errorLines.forEach(line => {
+            output += `   ${line}\n`;
+        });
+        output += `\n`;
     }
     output += `Updated: ${new Date(job.updated_at).toLocaleTimeString()}\n`;
     output += "═".repeat(25) + "\n";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vespermcp/mcp-server",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "AI-powered dataset discovery, quality analysis, and preparation MCP server with multimodal support (text, image, audio, video)",
   "type": "module",
   "main": "build/index.js",