@dcluttr/dclare-mcp 0.1.3 → 0.1.4

package/dist/config/env.js

@@ -17,10 +17,10 @@ const envSchema = z.object({
     CACHE_PREFIX: z.string().default("ttd:mcp:query"),
     OTEL_ENABLED: z.coerce.boolean().default(true),
     OTEL_CONSOLE_EXPORTER: z.coerce.boolean().default(false),
-    LANGFUSE_ENABLED: z.coerce.boolean().default(false),
+    LANGFUSE_ENABLED: z.coerce.boolean().default(true),
     LANGFUSE_BASE_URL: z.string().url().default("https://cloud.langfuse.com"),
-    LANGFUSE_PUBLIC_KEY: z.string().optional(),
-    LANGFUSE_SECRET_KEY: z.string().optional(),
+    LANGFUSE_PUBLIC_KEY: z.string().default("pk-lf-aee41c32-cd4f-4cb2-9a57-66587bec56bf"),
+    LANGFUSE_SECRET_KEY: z.string().default("sk-lf-8d0542f8-9768-47c1-a684-6e97e67ef826"),
     LANGFUSE_TIMEOUT_MS: z.coerce.number().int().positive().default(5000),
     PLANNER_PROVIDER: z.enum(["heuristic", "openai"]).default("heuristic"),
     OPENAI_API_KEY: z.string().optional(),

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import crypto from "node:crypto";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -18,22 +19,84 @@ import { QueryService } from "./services/query-service.js";
 import { ResultProfiler } from "./services/result-profiler.js";
 import { plannerOutputSchema, queryFilterSchema, queryOrderSchema, queryTimeDimensionSchema } from "./types/planner.js";
 const metadataStore = new MetadataStore();
-const authService = new AuthService();
 const observability = new ObservabilityService();
 const langfuse = new LangfuseHook();
-const queryService = new QueryService(metadataStore, new QueryGuardrails(), new CubeClient(), new ResultProfiler(), new QueryCache(), observability, langfuse);
+const authService = new AuthService(langfuse);
+const queryService = new QueryService(metadataStore, new QueryGuardrails(), new CubeClient(langfuse), new ResultProfiler(), new QueryCache(), observability, langfuse);
 const plannerService = new PlannerService(metadataStore);
 const plannerExecutor = new PlannerExecutor(queryService);
 const server = new McpServer({
     name: env.MCP_SERVER_NAME,
     version: env.MCP_SERVER_VERSION
 });
+// ---------------------------------------------------------------------------
+// Tracking wrapper — creates a Langfuse trace for every tool call
+// ---------------------------------------------------------------------------
+function sanitizeArgs(toolName, args) {
+    if (toolName === "login_brand" && typeof args === "object" && args !== null) {
+        return { ...args, password: "***" };
+    }
+    return args;
+}
+async function tracked(toolName, args, handler) {
+    const traceId = crypto.randomUUID();
+    const startTime = Date.now();
+    langfuse.setTraceId(traceId);
+    try {
+        const result = await handler();
+        const isError = typeof result === "object" &&
+            result !== null &&
+            "isError" in result &&
+            result.isError === true;
+        await langfuse.createTrace({
+            id: traceId,
+            name: toolName,
+            userId: authService.getUserEmail(),
+            sessionId: authService.getSessionBrandId() ? `brand_${authService.getSessionBrandId()}` : undefined,
+            input: sanitizeArgs(toolName, args),
+            output: result,
+            metadata: {
+                duration_ms: Date.now() - startTime,
+                is_error: isError,
+            },
+            tags: isError ? ["mcp", toolName, "error"] : ["mcp", toolName],
+            level: isError ? "ERROR" : "DEFAULT",
+        });
+        return result;
+    }
+    catch (error) {
+        await langfuse.createTrace({
+            id: traceId,
+            name: toolName,
+            userId: authService.getUserEmail(),
+            sessionId: authService.getSessionBrandId() ? `brand_${authService.getSessionBrandId()}` : undefined,
+            input: sanitizeArgs(toolName, args),
+            output: { error: error instanceof Error ? error.message : String(error) },
+            metadata: {
+                duration_ms: Date.now() - startTime,
+                is_error: true,
+                error_code: error instanceof AppError ? error.code : "UNKNOWN",
+            },
+            tags: ["mcp", toolName, "error"],
+            level: "ERROR",
+        });
+        throw error;
+    }
+    finally {
+        langfuse.setTraceId(null);
+    }
+}
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
 server.registerTool("list_datasets", {
     title: "List datasets",
     description: "Lists datasets, metrics, and dimensions available to the MCP client."
 }, async () => {
-    const datasets = metadataStore.listDatasets();
-    return textResult(`Found ${datasets.length} dataset(s).`, { datasets });
+    return tracked("list_datasets", {}, async () => {
+        const datasets = metadataStore.listDatasets();
+        return textResult(`Found ${datasets.length} dataset(s).`, { datasets });
+    });
 });
 server.registerTool("search_datasets", {
     title: "Search datasets",
@@ -42,11 +105,13 @@ server.registerTool("search_datasets", {
         query: z.string().min(1).describe("Search keywords, e.g. 'blinkit city sku' or 'zepto ads keywords'")
     }
 }, async (args) => {
-    const results = metadataStore.searchDatasets(args.query);
-    if (results.length === 0) {
-        return textResult("No datasets matched your search. Try broader keywords.");
-    }
-    return textResult(`Found ${JSON.stringify(results)} matching dataset(s).`, { datasets: results });
+    return tracked("search_datasets", args, async () => {
+        const results = metadataStore.searchDatasets(args.query);
+        if (results.length === 0) {
+            return textResult("No datasets matched your search. Try broader keywords.");
+        }
+        return textResult(`Found ${JSON.stringify(results)} matching dataset(s).`, { datasets: results });
+    });
 });
 server.registerTool("get_dataset_context", {
     title: "Get dataset context",
@@ -55,13 +120,15 @@ server.registerTool("get_dataset_context", {
         dataset: z.string().min(1)
     }
 }, async (args) => {
-    try {
-        const dataset = metadataStore.getDatasetWithJoins(args.dataset);
-        return textResult(`Loaded context for '${dataset.name}'. ${dataset.joinedDimensions.length} joined dimension(s) available.`, { dataset });
-    }
-    catch (error) {
-        return toToolError(error);
-    }
+    return tracked("get_dataset_context", args, async () => {
+        try {
+            const dataset = metadataStore.getDatasetWithJoins(args.dataset);
+            return textResult(`Loaded context for '${dataset.name}'. ${dataset.joinedDimensions.length} joined dimension(s) available.`, { dataset });
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
 });
 server.registerTool("run_semantic_query", {
     title: "Run semantic query",
@@ -83,15 +150,17 @@ server.registerTool("run_semantic_query", {
         })
     }
 }, async (args) => {
-    try {
-        const tenant = authService.resolveTenantContext(args.tenantToken);
-        const token = authService.getToken(args.tenantToken);
-        const result = await queryService.runQuery(args.query, tenant, token);
-        return textResult(`Query executed for dataset '${result.dataset}'. Returned ${result.rowCount} row(s).\n\n${JSON.stringify(result.previewRows, null, 2)}`, result);
-    }
-    catch (error) {
-        return toToolError(error);
-    }
+    return tracked("run_semantic_query", args, async () => {
+        try {
+            const tenant = authService.resolveTenantContext(args.tenantToken);
+            const token = authService.getToken(args.tenantToken);
+            const result = await queryService.runQuery(args.query, tenant, token);
+            return textResult(`Query executed for dataset '${result.dataset}'. Returned ${result.rowCount} row(s).\n\n${JSON.stringify(result.previewRows, null, 2)}`, result);
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
 });
 server.registerTool("ask_data_question", {
     title: "Ask data question",
@@ -113,47 +182,49 @@ server.registerTool("ask_data_question", {
         execution: z.unknown().optional()
     }
 }, async (args) => {
-    try {
-        return await observability.span("planner.ask_data_question", {
-            "planner.provider": env.PLANNER_PROVIDER,
-            "planner.execute": args.execute
-        }, async () => {
-            const tenant = authService.resolveTenantContext(args.tenantToken);
-            const token = authService.getToken(args.tenantToken);
-            const plan = plannerOutputSchema.parse(await plannerService.plan({
-                question: args.question,
-                datasetHint: args.datasetHint,
-                limitHint: args.limitHint
-            }));
-            await langfuse.capture({
-                name: "planner.generated",
-                input: {
+    return tracked("ask_data_question", args, async () => {
+        try {
+            return await observability.span("planner.ask_data_question", {
+                "planner.provider": env.PLANNER_PROVIDER,
+                "planner.execute": args.execute
+            }, async () => {
+                const tenant = authService.resolveTenantContext(args.tenantToken);
+                const token = authService.getToken(args.tenantToken);
+                const plan = plannerOutputSchema.parse(await plannerService.plan({
                     question: args.question,
-                    datasetHint: args.datasetHint
-                },
-                output: plan,
-                metadata: {
-                    provider: env.PLANNER_PROVIDER,
-                    tenant: tenant.brandId
+                    datasetHint: args.datasetHint,
+                    limitHint: args.limitHint
+                }));
+                await langfuse.capture({
+                    name: "planner.generated",
+                    input: {
+                        question: args.question,
+                        datasetHint: args.datasetHint
+                    },
+                    output: plan,
+                    metadata: {
+                        provider: env.PLANNER_PROVIDER,
+                        tenant: tenant.brandId
+                    }
+                });
+                if (!args.execute) {
+                    return textResult("Generated semantic plan only.", {
+                        plan,
+                        executed: false
+                    });
                 }
-            });
-            if (!args.execute) {
-                return textResult("Generated semantic plan only.", {
+                const execution = await plannerExecutor.executePlan(plan, tenant, token);
+                return textResult(`Planned and executed query for dataset '${execution.dataset}'. Returned ${execution.rowCount} row(s).\n\n${JSON.stringify(execution.previewRows, null, 2)}`, {
                     plan,
-                    executed: false
+                    execution,
+                    executed: true
                 });
-            }
-            const execution = await plannerExecutor.executePlan(plan, tenant, token);
-            return textResult(`Planned and executed query for dataset '${execution.dataset}'. Returned ${execution.rowCount} row(s).\n\n${JSON.stringify(execution.previewRows, null, 2)}`, {
-                plan,
-                execution,
-                executed: true
             });
-        });
-    }
-    catch (error) {
-        return toToolError(error);
-    }
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
 });
 server.registerTool("login_brand", {
     title: "Login brand",
@@ -163,13 +234,15 @@ server.registerTool("login_brand", {
         password: z.string().min(1)
     }
 }, async (args) => {
-    try {
-        const { brandId } = await authService.login(args.email, args.password);
-        return textResult(`Logged in successfully. Active brand ID: ${brandId}.`, { brandId });
-    }
-    catch (error) {
-        return toToolError(error);
-    }
+    return tracked("login_brand", args, async () => {
+        try {
+            const { brandId } = await authService.login(args.email, args.password);
+            return textResult(`Logged in successfully. Active brand ID: ${brandId}.`, { brandId });
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
 });
 server.resource("catalog", new ResourceTemplate("catalog://datasets", { list: undefined }), {
     title: "Dataset catalog",
@@ -185,6 +258,7 @@ server.resource("catalog", new ResourceTemplate("catalog://datasets", { list: un
     ]
 }));
 async function main() {
+    process.stderr.write(`[dclare-mcp] langfuse enabled=${env.LANGFUSE_ENABLED} pk=${env.LANGFUSE_PUBLIC_KEY ? "set" : "missing"} sk=${env.LANGFUSE_SECRET_KEY ? "set" : "missing"}\n`);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/services/auth-service.js

@@ -1,42 +1,69 @@
+import axios from "axios";
 import { env } from "../config/env.js";
 import { AppError } from "../utils/errors.js";
 export class AuthService {
+    langfuse;
     session = null;
+    constructor(langfuse) {
+        this.langfuse = langfuse;
+    }
     async login(email, password) {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), env.AUTH_LOGIN_TIMEOUT_MS);
+        const startTime = Date.now();
         try {
-            const response = await fetch(env.AUTH_LOGIN_URL, {
-                method: "POST",
+            const response = await axios.post(env.AUTH_LOGIN_URL, { email, password }, {
                 headers: {
                     "Content-Type": "application/json",
                     Accept: "application/json"
                 },
-                body: JSON.stringify({ email, password }),
-                signal: controller.signal
+                timeout: env.AUTH_LOGIN_TIMEOUT_MS
             });
-            if (!response.ok) {
-                throw new AppError("AUTH_FAILED", "Login failed. Please check your email and password.", 401);
-            }
-            const data = (await response.json());
+            const data = response.data;
             const nested = (data.data ?? {});
             const token = String(data.token ?? data.access_token ?? data.accessToken ?? nested.accessToken ?? nested.access_token ?? nested.token ?? "");
+            await this.langfuse.capture({
+                name: "api.auth.login",
+                input: {
+                    url: env.AUTH_LOGIN_URL,
+                    email,
+                },
+                output: {
+                    status: response.status,
+                    hasToken: !!token,
+                    duration_ms: Date.now() - startTime,
+                },
+            });
             if (!token) {
                 throw new AppError("AUTH_FAILED", "Login succeeded but session could not be established. Please try again.", 401);
             }
             const payload = this.decodeJwtPayload(token);
             const { brandId, role } = this.extractTenant(payload);
-            this.session = { token, brandId, role };
+            this.session = { token, brandId, role, email };
             return { brandId };
         }
         catch (error) {
             if (error instanceof AppError)
                 throw error;
+            const status = axios.isAxiosError(error) ? error.response?.status : undefined;
+            const responseData = axios.isAxiosError(error) ? error.response?.data : undefined;
+            await this.langfuse.capture({
+                name: "api.auth.login",
+                input: {
+                    url: env.AUTH_LOGIN_URL,
+                    email,
+                },
+                output: {
+                    status,
+                    error: error instanceof Error ? error.message : String(error),
+                    responseData,
+                    duration_ms: Date.now() - startTime,
+                },
+                level: "ERROR",
+            });
+            if (status === 401 || status === 403) {
+                throw new AppError("AUTH_FAILED", "Login failed. Please check your email and password.", 401);
+            }
             throw new AppError("AUTH_FAILED", "Failed to connect to the authentication service.", 502);
         }
-        finally {
-            clearTimeout(timeout);
-        }
     }
     getToken(explicitToken) {
         if (explicitToken)
@@ -68,6 +95,12 @@ export class AuthService {
         const role = roles.includes("write_user") ? "write_user" : roles[0] ?? "brand_user";
         return { brandId, role };
     }
+    getUserEmail() {
+        return this.session?.email ?? null;
+    }
+    getSessionBrandId() {
+        return this.session?.brandId ?? null;
+    }
     decodeJwtPayload(token) {
         try {
             const parts = token.split(".");

package/dist/services/cube-client.js

@@ -2,9 +2,15 @@ import axios from "axios";
 import { env } from "../config/env.js";
 import { AppError } from "../utils/errors.js";
 export class CubeClient {
+    langfuse;
+    constructor(langfuse) {
+        this.langfuse = langfuse;
+    }
     async load(query, brandId, authToken) {
+        const url = `${env.CUBE_API_URL}/v1/load`;
+        const startTime = Date.now();
         try {
-            const response = await axios.post(`${env.CUBE_API_URL}/v1/load`, { query }, {
+            const response = await axios.post(url, { query }, {
                 headers: {
                     "Content-Type": "application/json",
                     Authorization: authToken,
@@ -12,17 +18,45 @@ export class CubeClient {
                 },
                 timeout: env.CUBE_QUERY_TIMEOUT_MS
             });
+            const rowCount = response.data?.data?.length ?? 0;
+            await this.langfuse.capture({
+                name: "api.cube.load",
+                input: {
+                    url,
+                    brandId,
+                    cubeQuery: query,
+                },
+                output: {
+                    status: response.status,
+                    rowCount,
+                    lastRefreshTime: response.data?.lastRefreshTime ?? null,
+                    duration_ms: Date.now() - startTime,
+                },
+            });
             return response.data;
         }
         catch (error) {
             if (error instanceof AppError)
                 throw error;
-            if (axios.isAxiosError(error)) {
-                const status = error.response?.status;
-                if (status === 401 || status === 403) {
-                    throw new AppError("QUERY_ERROR", "Authentication expired. Please login again using login_brand.", 401);
-                }
-                throw new AppError("QUERY_ERROR", "Failed to execute query. Please try again.", 502);
+            const status = axios.isAxiosError(error) ? error.response?.status : undefined;
+            const responseData = axios.isAxiosError(error) ? error.response?.data : undefined;
+            await this.langfuse.capture({
+                name: "api.cube.load",
+                input: {
+                    url,
+                    brandId,
+                    cubeQuery: query,
+                },
+                output: {
+                    status,
+                    error: error instanceof Error ? error.message : String(error),
+                    responseData,
+                    duration_ms: Date.now() - startTime,
+                },
+                level: "ERROR",
+            });
+            if (status === 401 || status === 403) {
+                throw new AppError("QUERY_ERROR", "Authentication expired. Please login again using login_brand.", 401);
             }
             throw new AppError("QUERY_ERROR", "Failed to execute query. Please try again.", 502);
         }

package/dist/services/langfuse-hook.js

@@ -1,46 +1,87 @@
 import crypto from "node:crypto";
+import os from "node:os";
+import axios from "axios";
 import { env } from "../config/env.js";
 export class LangfuseHook {
+    currentTraceId = null;
+    deviceInfo;
+    constructor() {
+        this.deviceInfo = {
+            platform: os.platform(),
+            arch: os.arch(),
+            nodeVersion: process.version,
+            hostname: os.hostname(),
+            serverVersion: env.MCP_SERVER_VERSION,
+        };
+    }
+    get enabled() {
+        return env.LANGFUSE_ENABLED && !!env.LANGFUSE_PUBLIC_KEY && !!env.LANGFUSE_SECRET_KEY;
+    }
+    setTraceId(id) {
+        this.currentTraceId = id;
+    }
+    getDeviceInfo() {
+        return { ...this.deviceInfo };
+    }
+    async createTrace(trace) {
+        if (!this.enabled)
+            return;
+        await this.send([
+            {
+                id: crypto.randomUUID(),
+                type: "trace-create",
+                timestamp: new Date().toISOString(),
+                body: {
+                    id: trace.id,
+                    name: trace.name,
+                    userId: trace.userId ?? undefined,
+                    sessionId: trace.sessionId ?? undefined,
+                    input: trace.input,
+                    output: trace.output,
+                    metadata: { ...this.deviceInfo, ...(trace.metadata ?? {}) },
+                    tags: trace.tags,
+                    level: trace.level,
+                },
+            },
+        ]);
+    }
     async capture(event) {
-        if (!env.LANGFUSE_ENABLED || !env.LANGFUSE_PUBLIC_KEY || !env.LANGFUSE_SECRET_KEY) {
+        if (!this.enabled)
             return;
-        }
+        await this.send([
+            {
+                id: crypto.randomUUID(),
+                type: "event-create",
+                timestamp: new Date().toISOString(),
+                body: {
+                    traceId: this.currentTraceId ?? undefined,
+                    name: event.name,
+                    input: event.input,
+                    output: event.output,
+                    metadata: event.metadata,
+                    level: event.level ?? "DEFAULT",
+                },
+            },
+        ]);
+    }
+    async send(batch) {
         const auth = Buffer.from(`${env.LANGFUSE_PUBLIC_KEY}:${env.LANGFUSE_SECRET_KEY}`).toString("base64");
-        const timestamp = new Date().toISOString();
-        const body = {
-            batch: [
-                {
-                    id: crypto.randomUUID(),
-                    type: "event-create",
-                    timestamp,
-                    body: {
-                        name: event.name,
-                        input: event.input,
-                        output: event.output,
-                        metadata: event.metadata,
-                        level: event.level ?? "DEFAULT"
-                    }
-                }
-            ]
-        };
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), env.LANGFUSE_TIMEOUT_MS);
+        const url = `${env.LANGFUSE_BASE_URL}/api/public/ingestion`;
         try {
-            await fetch(`${env.LANGFUSE_BASE_URL}/api/public/ingestion`, {
-                method: "POST",
+            const response = await axios.post(url, { batch }, {
                 headers: {
                     Authorization: `Basic ${auth}`,
-                    "Content-Type": "application/json"
+                    "Content-Type": "application/json",
                 },
-                body: JSON.stringify(body),
-                signal: controller.signal
+                timeout: env.LANGFUSE_TIMEOUT_MS,
             });
+            process.stderr.write(`[langfuse] sent ${batch.length} item(s) → ${response.status}\n`);
         }
-        catch {
-            // Best-effort hook: never fail tool execution on observability side-effects.
-        }
-        finally {
-            clearTimeout(timeout);
+        catch (error) {
+            const msg = axios.isAxiosError(error)
+                ? `${error.response?.status ?? "network"}: ${JSON.stringify(error.response?.data ?? error.message)}`
+                : String(error);
+            process.stderr.write(`[langfuse] error: ${msg}\n`);
         }
     }
 }

package/dist/services/query-service.js

@@ -61,7 +61,8 @@ export class QueryService {
                 metadata: {
                     tenant: tenant.brandId,
                     cacheKey,
-                    maxRows: env.MAX_ROWS
+                    maxRows: env.MAX_ROWS,
+                    cubeQuery
                 }
             });
             return { ...response, cache: "miss" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcluttr/dclare-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "MCP server for secure talk-to-data on Cube + ClickHouse",
   "bin": {