@vespermcp/mcp-server 1.2.18 → 1.2.19

package/build/index.js

@@ -451,6 +451,7 @@ jobManager.on("processJob", async (job, execute) => {
  * Logic for preparing a dataset (Search + Ingest + Process)
  */
 async function handlePrepareJob(jobId, query, requirements) {
+    hydrateExternalKeys();
     const update = (updates) => jobManager.updateJob(jobId, updates);
     const requestedRows = extractRequestedRows(query, requirements);
     let selectedDataset;
@@ -480,7 +481,8 @@ async function handlePrepareJob(jobId, query, requirements) {
             datasetIdForDownload = explicitId.replace(/^dataworld:/i, "");
         }
         else {
-            source = "kaggle";
+            // Default to HuggingFace for ambiguous refs (user/dataset without prefix)
+            source = "huggingface";
             datasetIdForDownload = explicitId;
         }
         update({
@@ -490,11 +492,21 @@ async function handlePrepareJob(jobId, query, requirements) {
     }
     else {
         update({ progress: 10, status_text: "Searching for best dataset matching query..." });
-        const results = await searchEngine.search(query, { limit: 1 });
+        const results = await searchEngine.search(query, { limit: 10 });
         if (results.length === 0) {
             throw new Error("No datasets found matching the query. Try refining your search terms.");
         }
-        selectedDataset = results[0];
+        // Pick the best result that we can actually download (skip sources requiring missing credentials)
+        const hasKaggleCreds = !!(process.env.KAGGLE_USERNAME && process.env.KAGGLE_KEY && process.env.KAGGLE_USERNAME !== "YOUR_KAGGLE_USERNAME");
+        const hasDwToken = hasDataWorldToken();
+        selectedDataset = results.find(r => {
+            const s = (r.source || "").toLowerCase();
+            if (s === "kaggle" && !hasKaggleCreds)
+                return false;
+            if (s === "dataworld" && !hasDwToken)
+                return false;
+            return true;
+        }) || results[0]; // Fallback to first if all require credentials
         datasetIdForDownload = selectedDataset.id;
         source = selectedDataset.source;
         update({
@@ -502,13 +514,16 @@ async function handlePrepareJob(jobId, query, requirements) {
             status_text: `Matched: ${selectedDataset.name} (${selectedDataset.source})`
         });
     }
-    // Pre-check credentials for Kaggle
+    // Pre-check credentials for sources that require them
     if (source === "kaggle") {
-        if (!process.env.KAGGLE_USERNAME || !process.env.KAGGLE_KEY ||
-            process.env.KAGGLE_USERNAME === "YOUR_KAGGLE_USERNAME") {
-            throw new Error("Kaggle credentials not set. Use 'kaggle login' or set KAGGLE_USERNAME/KAGGLE_KEY.");
+        const hasKaggleCreds = !!(process.env.KAGGLE_USERNAME && process.env.KAGGLE_KEY && process.env.KAGGLE_USERNAME !== "YOUR_KAGGLE_USERNAME");
+        if (!hasKaggleCreds) {
+            throw new Error("Kaggle credentials not set. Use the configure_keys tool or set KAGGLE_USERNAME/KAGGLE_KEY environment variables.");
         }
     }
+    if (source === "dataworld" && !hasDataWorldToken()) {
+        throw new Error("data.world token not set. Use the configure_keys tool or set DW_AUTH_TOKEN environment variable.");
+    }
     update({ progress: 30, status_text: `Starting download from ${source}...` });
     // ensureData handles download and returns path to the raw file
     let rawFilePath = await dataIngestor.ensureData(datasetIdForDownload, source, (msg, prog) => {
@@ -604,22 +619,49 @@ async function handlePrepareJob(jobId, query, requirements) {
  */
 async function handleCleanJob(jobId, datasetId, ops) {
     const update = (updates) => jobManager.updateJob(jobId, updates);
-    const safeId = datasetId.replace(/\//g, "_");
-    const parquetPath = path.join(dataRoot, "data", "raw", `${safeId}.parquet`);
-    const csvPath = path.join(dataRoot, "data", "raw", `${safeId}.csv`);
-    let filePath = parquetPath;
-    if (!fs.existsSync(filePath)) {
-        filePath = csvPath;
-    }
-    if (datasetId === "demo" || !fs.existsSync(filePath)) {
+    // Resolve dataset file path from multiple sources
+    let filePath;
+    // 1. Check registry (most reliable - includes prepared/fused datasets)
+    const regEntry = getRegistryEntry(datasetId);
+    const regPath = regEntry?.local_path || regEntry?.path;
+    if (regPath && fs.existsSync(regPath)) {
+        filePath = regPath;
+    }
+    // 2. Check download status from metadata store
+    if (!filePath) {
+        const dlStatus = metadataStore.getDownloadStatus(datasetId);
+        if (dlStatus?.local_path && fs.existsSync(dlStatus.local_path)) {
+            filePath = dlStatus.local_path;
+        }
+    }
+    // 3. Check standard raw data paths
+    if (!filePath) {
+        const safeId = datasetId.replace(/\//g, "_");
+        const parquetPath = path.join(dataRoot, "data", "raw", `${safeId}.parquet`);
+        const csvPath = path.join(dataRoot, "data", "raw", `${safeId}.csv`);
+        const featherPath = path.join(dataRoot, "data", "raw", `${safeId}.feather`);
+        if (fs.existsSync(parquetPath))
+            filePath = parquetPath;
+        else if (fs.existsSync(csvPath))
+            filePath = csvPath;
+        else if (fs.existsSync(featherPath))
+            filePath = featherPath;
+    }
+    // 4. Check if it's a direct file path
+    if (!filePath && fs.existsSync(datasetId)) {
+        filePath = datasetId;
+    }
+    // 5. Demo fallback
+    if (!filePath && datasetId === "demo") {
         const demoParquetPath = path.join(dataRoot, "e2e_demo_output", "raw_data.parquet");
         const demoCsvPath = path.join(dataRoot, "e2e_demo_output", "raw_data.csv");
         if (fs.existsSync(demoParquetPath))
             filePath = demoParquetPath;
         else if (fs.existsSync(demoCsvPath))
             filePath = demoCsvPath;
-        else
-            throw new Error(`Data file not found for ${datasetId}`);
+    }
+    if (!filePath) {
+        throw new Error(`Data file not found for '${datasetId}'. Download the dataset first using download_dataset or prepare_dataset.`);
     }
     update({ status_text: "Cleaning dataset..." });
     const result = await dataCleaner.clean(filePath, ops);
@@ -684,14 +726,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "download_dataset",
-                description: "Download a dataset by source and ID/slug into local Vesper storage. Kaggle requires optional API key.",
+                description: "Download a dataset by source and ID/slug into local Vesper storage. Defaults to HuggingFace. Kaggle and data.world require API keys (use configure_keys first).",
                 inputSchema: {
                     type: "object",
                     properties: {
                         source: {
                             type: "string",
                             enum: ["huggingface", "kaggle", "openml", "dataworld"],
-                            description: "Dataset source.",
+                            description: "Dataset source (default: huggingface). HuggingFace and OpenML work without credentials.",
                         },
                         dataset_id: {
                             type: "string",
@@ -702,7 +744,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Optional target directory for downloaded files.",
                         }
                     },
-                    required: ["source", "dataset_id"],
+                    required: ["dataset_id"],
                 },
             },
             {
@@ -793,7 +835,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "custom_clean",
-                description: "Apply specific cleaning operations to a dataset as an asynchronous job.",
+                description: "Apply specific cleaning operations to a dataset as an asynchronous job. Supports: RemoveDuplicates, DropColumns, FillMissing, FixTypes, RemoveOutliers, EncodeCategories. The dataset must be downloaded first.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -818,7 +860,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "prepare_dataset",
-                description: "Full pipeline: Analyze, Clean, Split, and Export as an asynchronous job.",
+                description: "Full pipeline: Search, Download, Analyze, Clean, Split, and Install a dataset as an asynchronous job. Automatically selects the best available source (prefers HuggingFace/OpenML when no Kaggle credentials are set). Use check_job_status to monitor progress.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -1110,7 +1152,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (source === "kaggle") {
                     if (!dataIngestor.hasKaggleCredentials()) {
                         return {
-                            content: [{ type: "text", text: `Kaggle support requires API key. Run 'vespermcp config keys' (30 seconds).` }],
+                            content: [{ type: "text", text: `Kaggle requires API credentials. Use the configure_keys tool to set kaggle_username and kaggle_key, or try source='huggingface' which works without credentials.` }],
                             isError: true,
                         };
                     }
@@ -1166,20 +1208,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         case "download_dataset": {
             hydrateExternalKeys();
-            const source = String(request.params.arguments?.source || "").toLowerCase();
+            const source = String(request.params.arguments?.source || "huggingface").toLowerCase();
             const datasetId = String(request.params.arguments?.dataset_id || "").trim();
-            if (!source || !datasetId) {
-                throw new McpError(ErrorCode.InvalidParams, "source and dataset_id are required");
+            if (!datasetId) {
+                throw new McpError(ErrorCode.InvalidParams, "dataset_id is required");
             }
             if (source === "kaggle" && !dataIngestor.hasKaggleCredentials()) {
                 return {
-                    content: [{ type: "text", text: `Kaggle support requires API key. Run 'vespermcp config keys' (30 seconds).` }],
+                    content: [{ type: "text", text: `Kaggle requires API credentials. Use the configure_keys tool to set kaggle_username and kaggle_key, or switch to source='huggingface' which works without credentials.` }],
                     isError: true,
                 };
             }
             if (source === "dataworld" && !hasDataWorldToken()) {
                 return {
-                    content: [{ type: "text", text: "data.world requires API token. Run 'vespermcp config keys' and set dataworld_token." }],
+                    content: [{ type: "text", text: "data.world requires API token. Use the configure_keys tool to set dataworld_token, or switch to source='huggingface' which works without credentials." }],
                     isError: true,
                 };
             }
@@ -1460,18 +1502,45 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         case "custom_clean": {
             const datasetId = String(request.params.arguments?.dataset_id);
             const ops = request.params.arguments?.operations;
+            if (!datasetId || datasetId === "undefined") {
+                throw new McpError(ErrorCode.InvalidParams, "dataset_id is required");
+            }
+            if (!ops || !Array.isArray(ops) || ops.length === 0) {
+                throw new McpError(ErrorCode.InvalidParams, "operations array is required and must not be empty. Supported operations: RemoveDuplicates, DropColumns, FillMissing, FixTypes, RemoveOutliers, EncodeCategories");
+            }
+            // Pre-check: verify dataset file exists before starting the job
+            const cleanRegEntry = getRegistryEntry(datasetId);
+            const cleanRegPath = cleanRegEntry?.local_path || cleanRegEntry?.path;
+            const cleanDlStatus = metadataStore.getDownloadStatus(datasetId);
+            const cleanSafeId = datasetId.replace(/\//g, "_");
+            const cleanDataExists = (cleanRegPath && fs.existsSync(cleanRegPath)) ||
+                (cleanDlStatus?.local_path && fs.existsSync(cleanDlStatus.local_path)) ||
+                fs.existsSync(path.join(dataRoot, "data", "raw", `${cleanSafeId}.parquet`)) ||
+                fs.existsSync(path.join(dataRoot, "data", "raw", `${cleanSafeId}.csv`)) ||
+                fs.existsSync(path.join(dataRoot, "data", "raw", `${cleanSafeId}.feather`)) ||
+                fs.existsSync(datasetId);
+            if (!cleanDataExists) {
+                return {
+                    content: [{ type: "text", text: `Dataset '${datasetId}' not found locally. Download it first using download_dataset or prepare_dataset, then run custom_clean.` }],
+                    isError: true,
+                };
+            }
             const job = jobManager.createJob("clean", 0, { datasetId, ops });
             return {
-                content: [{ type: "text", text: `Job started successfully. ID: ${job.id}. Use check_job_status to monitor progress.` }]
+                content: [{ type: "text", text: `Cleaning job started. ID: ${job.id}. Use check_job_status to monitor progress.` }]
             };
         }
         case "prepare_dataset": {
+            hydrateExternalKeys();
             const query = String(request.params.arguments?.query);
             const requirements = request.params.arguments?.requirements ? String(request.params.arguments?.requirements) : undefined;
             const downloadImages = request.params.arguments?.download_images === true;
+            if (!query || query === "undefined") {
+                throw new McpError(ErrorCode.InvalidParams, "query is required - describe the dataset you need or provide a dataset ID");
+            }
             const job = jobManager.createJob("prepare", 0, { query, requirements, downloadImages });
             return {
-                content: [{ type: "text", text: `Preparation job started. ID: ${job.id}. Vesper is finding and preparing the best dataset for you.` }]
+                content: [{ type: "text", text: `Preparation job started. ID: ${job.id}. Vesper is finding and preparing the best dataset for you. Use check_job_status to monitor progress.` }]
             };
         }
         case "compare_datasets": {

package/package.json

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

package/scripts/wizard.js

@@ -118,7 +118,7 @@ function getAllAgentConfigs() {
 
 function installMcpToAgent(agent) {
   const npxCmd = IS_WIN ? 'npx.cmd' : 'npx';
-  const serverEntry = { command: npxCmd, args: ['-y', '-p', '@vespermcp/mcp-server@latest', 'vespermcp'] };
+  const serverEntry = { command: npxCmd, args: ['-y', '@vespermcp/mcp-server@latest'] };
 
   try {
     if (agent.format === 'toml') {
@@ -156,7 +156,7 @@ function installMcpToAgent(agent) {
 async function checkServerHealth() {
   try {
     // Quick stdio check — spawn server and see if it responds
-    const result = spawnSync(IS_WIN ? 'npx.cmd' : 'npx', ['-y', '-p', '@vespermcp/mcp-server@latest', 'vespermcp', '--version'], {
+    const result = spawnSync(IS_WIN ? 'npx.cmd' : 'npx', ['-y', '@vespermcp/mcp-server@latest', '--version'], {
       timeout: 10000,
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -202,13 +202,13 @@ async function main() {
   console.log(`\n  ${dim('[')}${cyan('4/6')}${dim(']')} Installing Vesper MCP server...`);
   try {
     const npmCmd = IS_WIN ? 'npx.cmd' : 'npx';
-    spawnSync(npmCmd, ['-y', '-p', '@vespermcp/mcp-server@latest', 'vespermcp', '--setup', '--silent'], {
+    spawnSync(npmCmd, ['-y', '@vespermcp/mcp-server@latest', '--setup', '--silent'], {
       stdio: 'inherit',
       timeout: 120000,
     });
     console.log(`      ${green('✓')} @vespermcp/mcp-server installed`);
   } catch {
-    console.log(`      ${yellow('⚠')} Could not auto-install — run manually: npx -y -p @vespermcp/mcp-server@latest vespermcp --setup`);
+    console.log(`      ${yellow('⚠')} Could not auto-install — run manually: npx -y @vespermcp/mcp-server@latest --setup`);
   }
 
   // ─── Step 5: Auto-configure all detected IDEs ──────────────