@vespermcp/mcp-server 1.2.30 → 1.3.1

package/build/lib/mcp-analytics.js

@@ -0,0 +1,164 @@
+import { getSupabaseAdminClient, resolveUserIdFromApiKey } from "./plan-resolve.js";
+import { inferSourceFromDatasetId, normalizeProviderSource, PLAN_GATE_EXEMPT_TOOLS, } from "./plan-gate.js";
+function truncateDatasetName(raw) {
+    const t = raw.trim();
+    if (!t)
+        return "unknown";
+    return t.length > 256 ? t.slice(0, 253) + "..." : t;
+}
+function pickDatasetName(args) {
+    const a = args || {};
+    const candidates = [
+        a.dataset_id,
+        a.query,
+        a.datasetId,
+        a.url,
+        a.file_path,
+    ];
+    for (const c of candidates) {
+        if (typeof c === "string" && c.trim()) {
+            return truncateDatasetName(c);
+        }
+    }
+    return "unknown";
+}
+function pickSource(toolName, args) {
+    const a = args || {};
+    const explicit = normalizeProviderSource(String(a.source ?? ""));
+    if (explicit)
+        return explicit;
+    const fromId = inferSourceFromDatasetId(String(a.dataset_id ?? a.query ?? ""));
+    if (fromId)
+        return fromId;
+    if (toolName === "vesper_web_find" && Array.isArray(a.sources) && a.sources.length > 0) {
+        return String(a.sources[0]).toLowerCase();
+    }
+    return null;
+}
+function pickFormat(args) {
+    const a = args || {};
+    const f = a.format ?? a.target_format ?? a.output_format;
+    if (typeof f === "string" && f.trim())
+        return f.trim().toLowerCase().slice(0, 32);
+    return null;
+}
+function mapToolToEvent(toolName) {
+    switch (toolName) {
+        case "vesper_search":
+        case "discover_datasets":
+        case "vesper_web_find":
+        case "vesper.extract_web":
+        case "get_dataset_info":
+            return { event_type: "dataset_search" };
+        case "download_dataset":
+        case "vesper_download_assets":
+            return { event_type: "dataset_download" };
+        case "quality_analyze":
+        case "analyze_quality":
+        case "analyze_image_quality":
+        case "analyze_media_quality":
+        case "generate_quality_report":
+        case "preview_cleaning":
+            return { event_type: "quality_analysis" };
+        case "prepare_dataset":
+            return { event_type: "dataset_prepare" };
+        case "export_dataset":
+        case "vesper_convert_format":
+            return { event_type: "export" };
+        default:
+            return { event_type: "data_processed" };
+    }
+}
+function mapToolToEventWithArgs(toolName, args) {
+    if (toolName === "unified_dataset_api") {
+        const op = String(args.operation ?? "").trim().toLowerCase();
+        if (op === "discover" || op === "providers" || op === "info") {
+            return { event_type: "dataset_search" };
+        }
+        if (op === "download") {
+            return { event_type: "dataset_download" };
+        }
+    }
+    return mapToolToEvent(toolName);
+}
+async function hasAnalyticsConsent(userId) {
+    const supabase = getSupabaseAdminClient();
+    if (!supabase)
+        return false;
+    const { data, error } = await supabase
+        .from("analytics_consent")
+        .select("consented")
+        .eq("user_id", userId)
+        .maybeSingle();
+    if (error) {
+        return false;
+    }
+    return data?.consented === true;
+}
+/**
+ * After each MCP tool call: insert one row into `analytics_events` (same table as
+ * `/api/analytics/ingest` and the landing Operations tab) when the user has opted in
+ * and `VESPER_API_KEY` / `api_key` resolves to a user.
+ */
+export async function recordMcpToolAnalyticsAfterCall(opts) {
+    if (process.env.VESPER_DISABLE_MCP_ANALYTICS === "1" || process.env.VESPER_DISABLE_MCP_ANALYTICS === "true") {
+        return;
+    }
+    const toolName = String(opts.toolName || "").trim();
+    if (!toolName || PLAN_GATE_EXEMPT_TOOLS.has(toolName)) {
+        return;
+    }
+    const supabase = getSupabaseAdminClient();
+    if (!supabase) {
+        return;
+    }
+    const args = opts.args || {};
+    const apiKey = String(args.api_key ?? process.env.VESPER_API_KEY ?? "").trim();
+    if (!apiKey) {
+        return;
+    }
+    const userId = await resolveUserIdFromApiKey(apiKey);
+    if (!userId) {
+        return;
+    }
+    if (!(await hasAnalyticsConsent(userId))) {
+        return;
+    }
+    const { event_type } = mapToolToEventWithArgs(toolName, args);
+    const dataset_name = pickDatasetName(args);
+    const source = pickSource(toolName, args);
+    const format = pickFormat(args);
+    const metadata = {
+        mcp_tool: toolName,
+        ok: opts.result !== undefined && opts.result.isError !== true,
+    };
+    if (opts.result?.isError) {
+        const first = opts.result.content?.[0];
+        if (first && typeof first.text === "string") {
+            metadata.error_preview = first.text.slice(0, 500);
+        }
+    }
+    const row = {
+        user_id: userId,
+        event_type,
+        dataset_name,
+        source: source || null,
+        format: format || null,
+        size_bytes: null,
+        quality_score: null,
+        metadata,
+        created_at: new Date().toISOString(),
+    };
+    let { error } = await supabase.from("analytics_events").insert(row);
+    // Older DBs may lack `dataset_prepare` in CHECK constraint — fall back.
+    if (error && event_type === "dataset_prepare" && /check|constraint/i.test(error.message || "")) {
+        ({ error } = await supabase.from("analytics_events").insert({
+            ...row,
+            event_type: "data_processed",
+            metadata: { ...metadata, event_type_fallback: "dataset_prepare" },
+        }));
+    }
+    if (error) {
+        console.error("[mcp-analytics] insert failed:", error.message);
+    }
+}

package/build/lib/plan-entitlements.js

@@ -0,0 +1,103 @@
+/**
+ * Mirrors `landing/lib/plan-entitlements.ts` — keep rules in sync when changing tiers.
+ */
+const PRICING_URL = "https://getvesper.dev/pricing";
+const FREE_ALLOWED_SOURCES = new Set(["huggingface", "openml", "s3", "local", "url"]);
+const PRO_ONLY_TOOLS = new Set(["custom_clean"]);
+const PRO_ONLY_DATASET_OPS = new Set(["compare_datasets", "fuse_datasets"]);
+const ADVANCED_EXPORT_FORMATS = new Set(["feather", "jsonl", "arrow"]);
+function asRecord(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function normalizeText(value) {
+    return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function readToolName(body, metadata) {
+    const candidates = [
+        body.tool,
+        body.operation,
+        body.feature,
+        body.action,
+        metadata.tool,
+        metadata.operation,
+        metadata.feature,
+        metadata.action,
+    ];
+    for (const candidate of candidates) {
+        const normalized = normalizeText(candidate);
+        if (normalized) {
+            return normalized;
+        }
+    }
+    return "";
+}
+function hasAdvancedExportOptions(body, metadata, format) {
+    if (ADVANCED_EXPORT_FORMATS.has(format)) {
+        return true;
+    }
+    const optionSources = [body, metadata, asRecord(metadata.options)];
+    for (const source of optionSources) {
+        if (!source || typeof source !== "object") {
+            continue;
+        }
+        const compression = normalizeText(source.compression);
+        if (compression && compression !== "uncompressed") {
+            return true;
+        }
+        if (typeof source.sample_rows === "number" && source.sample_rows > 0) {
+            return true;
+        }
+        if (Array.isArray(source.columns) && source.columns.length > 0) {
+            return true;
+        }
+        if (source.preview === true) {
+            return true;
+        }
+    }
+    return false;
+}
+export function evaluatePlanEntitlements(input) {
+    if (input.plan !== "free") {
+        return { allowed: true };
+    }
+    const body = asRecord(input.body);
+    const metadata = asRecord(input.metadata);
+    const source = normalizeText(input.source ?? body.source ?? metadata.source);
+    const format = normalizeText(input.format ?? body.format ?? metadata.format);
+    const toolName = readToolName(body, metadata);
+    if (source && !FREE_ALLOWED_SOURCES.has(source)) {
+        return {
+            allowed: false,
+            status: 403,
+            code: "feature_locked_source",
+            message: `Source '${source}' is a Pro feature. Free supports public sources only (huggingface, openml, s3). Upgrade at ${PRICING_URL}.`,
+        };
+    }
+    if (PRO_ONLY_TOOLS.has(toolName)) {
+        return {
+            allowed: false,
+            status: 403,
+            code: "feature_locked_custom_clean",
+            message: `custom_clean is available on Pro only. Upgrade at ${PRICING_URL}.`,
+        };
+    }
+    if (PRO_ONLY_DATASET_OPS.has(toolName)) {
+        return {
+            allowed: false,
+            status: 403,
+            code: "feature_locked_fusion_compare",
+            message: `${toolName} is available on Pro only. Upgrade at ${PRICING_URL}.`,
+        };
+    }
+    if (toolName === "export_dataset" || toolName === "vesper_export" || input.eventType === "export") {
+        if (hasAdvancedExportOptions(body, metadata, format)) {
+            return {
+                allowed: false,
+                status: 403,
+                code: "feature_locked_advanced_export",
+                message: `Advanced export options are Pro-only. Free supports basic csv/parquet export. Upgrade at ${PRICING_URL}.`,
+            };
+        }
+    }
+    return { allowed: true };
+}

package/build/lib/plan-gate.js

@@ -0,0 +1,243 @@
+/** Tools that never hit paid data-plane rules (config, registry, lineage meta). */
+export const PLAN_GATE_EXEMPT_TOOLS = new Set([
+    "configure_keys",
+    "lineage",
+    "get_lineage",
+    "diff_lineage_versions",
+    "vesper_list_datasets",
+    "check_job_status",
+]);
+const DATASET_ID_SOURCE = /^(kaggle|huggingface|hf|openml|dataworld|arxiv|github|s3|local|url|bigquery|gcs|azure):/i;
+export function normalizeProviderSource(raw) {
+    if (!raw)
+        return undefined;
+    const t = raw.trim().toLowerCase();
+    if (!t || t === "auto" || t === "unknown")
+        return undefined;
+    if (t === "hf")
+        return "huggingface";
+    return t;
+}
+export function inferSourceFromDatasetId(datasetId) {
+    if (!datasetId)
+        return undefined;
+    const m = String(datasetId).match(DATASET_ID_SOURCE);
+    if (!m)
+        return undefined;
+    const s = m[1].toLowerCase();
+    return s === "hf" ? "huggingface" : s;
+}
+export function buildToolPlanCheckInput(toolName, args) {
+    const a = args || {};
+    const op = String(a.operation ?? "").trim().toLowerCase();
+    switch (toolName) {
+        case "unified_dataset_api": {
+            if (op === "providers") {
+                return {
+                    eventType: "dataset_search",
+                    body: { tool: "unified_dataset_api", operation: "providers" },
+                };
+            }
+            if (op === "discover") {
+                const src = normalizeProviderSource(String(a.source ?? "")) ?? inferSourceFromDatasetId(String(a.query ?? ""));
+                return {
+                    eventType: "dataset_search",
+                    source: src,
+                    body: { tool: "unified_dataset_api", operation: "discover" },
+                    metadata: { source: a.source },
+                };
+            }
+            if (op === "download") {
+                const ds = String(a.dataset_id ?? "");
+                const src = normalizeProviderSource(String(a.source ?? "")) || inferSourceFromDatasetId(ds);
+                return {
+                    eventType: "dataset_download",
+                    source: src,
+                    body: { tool: "unified_dataset_api", operation: "download", dataset_id: ds },
+                    metadata: { source: a.source },
+                };
+            }
+            if (op === "info") {
+                const ds = String(a.dataset_id ?? "");
+                return {
+                    eventType: "dataset_search",
+                    source: inferSourceFromDatasetId(ds),
+                    body: { tool: "unified_dataset_api", operation: "info", dataset_id: ds },
+                };
+            }
+            return {
+                eventType: "dataset_search",
+                body: { tool: "unified_dataset_api", operation: op || "unknown" },
+            };
+        }
+        case "vesper_search": {
+            const q = String(a.query ?? "");
+            return {
+                eventType: "dataset_search",
+                source: inferSourceFromDatasetId(q),
+                body: { tool: "vesper_search" },
+            };
+        }
+        case "discover_datasets": {
+            return {
+                eventType: "dataset_search",
+                source: normalizeProviderSource(String(a.source ?? "")),
+                body: { tool: "discover_datasets" },
+            };
+        }
+        case "download_dataset": {
+            return {
+                eventType: "dataset_download",
+                source: normalizeProviderSource(String(a.source ?? "huggingface")),
+                body: { tool: "download_dataset" },
+            };
+        }
+        case "vesper_download_assets": {
+            return {
+                eventType: "dataset_download",
+                source: normalizeProviderSource(String(a.source ?? "")),
+                body: { tool: "vesper_download_assets" },
+            };
+        }
+        case "get_dataset_info": {
+            const ds = String(a.dataset_id ?? "");
+            return {
+                eventType: "dataset_search",
+                source: inferSourceFromDatasetId(ds),
+                body: { tool: "get_dataset_info" },
+            };
+        }
+        case "vesper_web_find": {
+            const sources = Array.isArray(a.sources) ? a.sources : [];
+            const first = sources.length > 0 ? String(sources[0]).toLowerCase() : "github";
+            return {
+                eventType: "dataset_search",
+                source: normalizeProviderSource(first) || first,
+                body: { tool: "vesper_web_find" },
+            };
+        }
+        case "vesper.extract_web": {
+            return {
+                eventType: "dataset_search",
+                source: "url",
+                body: { tool: "vesper.extract_web" },
+            };
+        }
+        case "vesper.fuse": {
+            return {
+                eventType: "data_processed",
+                body: { tool: "fuse_datasets", operation: "web" },
+                metadata: { tool: "fuse_datasets" },
+            };
+        }
+        case "quality_analyze":
+        case "analyze_quality":
+        case "analyze_image_quality":
+        case "analyze_media_quality":
+        case "generate_quality_report": {
+            const ds = String(a.dataset_id ?? a.path ?? "");
+            return {
+                eventType: "quality_analysis",
+                source: inferSourceFromDatasetId(ds),
+                body: { tool: toolName },
+            };
+        }
+        case "preview_cleaning": {
+            const ds = String(a.dataset_id ?? "");
+            return {
+                eventType: "quality_analysis",
+                source: inferSourceFromDatasetId(ds),
+                body: { tool: "preview_cleaning" },
+            };
+        }
+        case "custom_clean": {
+            const ds = String(a.dataset_id ?? "");
+            return {
+                eventType: "dataset_prepare",
+                source: inferSourceFromDatasetId(ds),
+                body: { tool: "custom_clean" },
+                metadata: { tool: "custom_clean" },
+            };
+        }
+        case "prepare_dataset": {
+            const q = String(a.query ?? a.dataset_id ?? "");
+            return {
+                eventType: "dataset_prepare",
+                source: inferSourceFromDatasetId(q),
+                body: { tool: "prepare_dataset" },
+            };
+        }
+        case "compare_datasets": {
+            return {
+                eventType: "data_processed",
+                body: { tool: "compare_datasets" },
+                metadata: { tool: "compare_datasets" },
+            };
+        }
+        case "export_dataset": {
+            const fmt = String(a.format ?? "feather").trim().toLowerCase();
+            return {
+                eventType: "export",
+                format: fmt,
+                source: inferSourceFromDatasetId(String(a.dataset_id ?? "")),
+                body: {
+                    tool: "export_dataset",
+                    format: fmt,
+                    compression: a.compression,
+                    preview: a.preview,
+                    sample_rows: a.sample_rows,
+                    columns: a.columns,
+                },
+                metadata: {
+                    options: {
+                        compression: a.compression,
+                        sample_rows: a.sample_rows,
+                        columns: a.columns,
+                        preview: a.preview,
+                    },
+                },
+            };
+        }
+        case "vesper_convert_format": {
+            const tf = String(a.target_format ?? "").trim().toLowerCase();
+            return {
+                eventType: "export",
+                format: tf,
+                body: { tool: "vesper_convert_format", format: tf },
+            };
+        }
+        case "vesper_normalize_schema": {
+            const of = String(a.output_format ?? "jsonl").trim().toLowerCase();
+            return {
+                eventType: "data_processed",
+                format: of,
+                body: { tool: "vesper_normalize_schema", format: of },
+            };
+        }
+        case "fuse":
+        case "fuse_datasets": {
+            const outputFormat = String(a.output_format ?? "parquet").trim().toLowerCase();
+            const compression = a.compression ? String(a.compression) : undefined;
+            const preview = a.preview === true;
+            return {
+                eventType: "data_processed",
+                format: outputFormat,
+                body: {
+                    tool: "fuse_datasets",
+                    format: outputFormat,
+                    compression,
+                    preview,
+                },
+                metadata: {
+                    tool: "fuse_datasets",
+                    options: { compression, preview },
+                },
+            };
+        }
+        default:
+            return {
+                eventType: "dataset_search",
+                body: { tool: toolName },
+            };
+    }
+}

package/build/lib/plan-resolve.js

@@ -0,0 +1,109 @@
+import { createClient } from "@supabase/supabase-js";
+import { evaluatePlanEntitlements, } from "./plan-entitlements.js";
+import { buildToolPlanCheckInput, PLAN_GATE_EXEMPT_TOOLS, } from "./plan-gate.js";
+let supabaseClient = null;
+function getSupabase() {
+    const url = process.env.SUPABASE_URL?.trim();
+    const key = process.env.SUPABASE_SERVICE_ROLE_KEY?.trim();
+    if (!url || !key) {
+        return null;
+    }
+    if (!supabaseClient) {
+        supabaseClient = createClient(url, key);
+    }
+    return supabaseClient;
+}
+export function isPlanGateConfigured() {
+    return getSupabase() !== null;
+}
+/**
+ * When false, skip plan checks (local dev without Supabase).
+ * Set VESPER_ENFORCE_PLAN=true to require API key + Supabase when testing locally.
+ */
+export function isPlanEnforcementEnabled() {
+    if (process.env.VESPER_ENFORCE_PLAN === "0" || process.env.VESPER_ENFORCE_PLAN === "false") {
+        return false;
+    }
+    return isPlanGateConfigured();
+}
+async function getUserPlanForUserId(userId) {
+    const supabase = getSupabase();
+    if (!supabase) {
+        return "pro";
+    }
+    const { data, error } = await supabase
+        .from("user_plans")
+        .select("plan")
+        .eq("user_id", userId)
+        .maybeSingle();
+    if (error || !data?.plan) {
+        return "free";
+    }
+    const plan = String(data.plan).toLowerCase();
+    if (plan === "pro" || plan === "startup") {
+        return plan;
+    }
+    return "free";
+}
+async function lookupUserByApiKey(apiKey) {
+    const supabase = getSupabase();
+    if (!supabase)
+        return null;
+    const { data, error } = await supabase
+        .from("api_keys")
+        .select("user_id, revoked_at")
+        .eq("key", apiKey)
+        .maybeSingle();
+    if (error || !data?.user_id || data.revoked_at) {
+        return null;
+    }
+    return { userId: data.user_id };
+}
+/** For analytics / profile sync — same lookup as plan gate. */
+export async function resolveUserIdFromApiKey(apiKey) {
+    const row = await lookupUserByApiKey(apiKey);
+    return row?.userId ?? null;
+}
+export function getSupabaseAdminClient() {
+    return getSupabase();
+}
+/**
+ * Central gate: same rules as `landing/lib/plan-entitlements` + landing analytics ingest.
+ */
+export async function enforcePlanGateForTool(toolName, args) {
+    if (PLAN_GATE_EXEMPT_TOOLS.has(toolName)) {
+        return { ok: true };
+    }
+    if (!isPlanEnforcementEnabled()) {
+        return { ok: true };
+    }
+    const rawArgs = args || {};
+    const apiKey = String(rawArgs.api_key ?? process.env.VESPER_API_KEY ?? "").trim();
+    if (!apiKey) {
+        return {
+            ok: false,
+            message: "Plan enforcement is enabled (Supabase configured). Set `VESPER_API_KEY` in the MCP env or pass `api_key` on tool calls to your Vesper API key so your tier can be verified.",
+        };
+    }
+    const user = await lookupUserByApiKey(apiKey);
+    if (!user) {
+        return {
+            ok: false,
+            message: "Invalid or revoked API key. Create a key in the Vesper profile and set VESPER_API_KEY or pass api_key on tool calls.",
+        };
+    }
+    const plan = await getUserPlanForUserId(user.userId);
+    const checkInput = buildToolPlanCheckInput(toolName, rawArgs);
+    const ent = evaluatePlanEntitlements({
+        plan,
+        eventType: checkInput.eventType,
+        source: checkInput.source,
+        format: checkInput.format,
+        metadata: checkInput.metadata,
+        body: checkInput.body,
+    });
+    if (!ent.allowed) {
+        return { ok: false, message: ent.message };
+    }
+    return { ok: true };
+}

package/package.json

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