@dcluttr/dclare-mcp 0.1.2

package/dist/config/env.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+const envSchema = z.object({
+    NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+    MCP_SERVER_NAME: z.string().default("@dcluttr/dclare-mcp"),
+    MCP_SERVER_VERSION: z.string().default("0.1.0"),
+    JWT_SECRET: z.string().min(16).optional(),
+    REQUIRE_AUTH_TOKEN: z.coerce.boolean().default(true),
+    DEFAULT_BRAND_ID: z.string().default("1131"),
+    MAX_ROWS: z.coerce.number().int().positive().default(40_000),
+    MAX_PREVIEW_ROWS: z.coerce.number().int().positive().default(200),
+    CUBE_API_URL: z.string().url().default("https://apollo.dcluttr.ai/cubejs-api"),
+    CUBE_API_TOKEN: z.string().optional(),
+    CUBE_QUERY_TIMEOUT_MS: z.coerce.number().int().positive().default(20_000),
+    METADATA_PATH: z.string().default("context/datasets.json"),
+    REDIS_URL: z.string().url().optional(),
+    CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(120),
+    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_BASE_URL: z.string().url().default("https://cloud.langfuse.com"),
+    LANGFUSE_PUBLIC_KEY: z.string().optional(),
+    LANGFUSE_SECRET_KEY: z.string().optional(),
+    LANGFUSE_TIMEOUT_MS: z.coerce.number().int().positive().default(5000),
+    PLANNER_PROVIDER: z.enum(["heuristic", "openai"]).default("heuristic"),
+    OPENAI_API_KEY: z.string().optional(),
+    OPENAI_BASE_URL: z.string().url().default("https://api.openai.com/v1"),
+    OPENAI_MODEL: z.string().default("gpt-4.1-mini"),
+    AUTH_LOGIN_URL: z.string().url().default("https://auth.dcluttr.ai/auth/login"),
+    AUTH_LOGIN_TIMEOUT_MS: z.coerce.number().int().positive().default(15000)
+});
+export const env = envSchema.parse(process.env);

package/dist/index.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { env } from "./config/env.js";
+import { AppError } from "./utils/errors.js";
+import { textResult } from "./utils/result.js";
+import { AuthService } from "./services/auth-service.js";
+import { CubeClient } from "./services/cube-client.js";
+import { LangfuseHook } from "./services/langfuse-hook.js";
+import { MetadataStore } from "./services/metadata-store.js";
+import { ObservabilityService } from "./services/observability-service.js";
+import { PlannerExecutor } from "./services/planner-executor.js";
+import { PlannerService } from "./services/planner-service.js";
+import { QueryCache } from "./services/query-cache.js";
+import { QueryGuardrails } from "./services/query-guardrails.js";
+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 plannerService = new PlannerService(metadataStore);
+const plannerExecutor = new PlannerExecutor(queryService);
+const server = new McpServer({
+    name: env.MCP_SERVER_NAME,
+    version: env.MCP_SERVER_VERSION
+});
+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 });
+});
+server.registerTool("search_datasets", {
+    title: "Search datasets",
+    description: "Searches datasets by keyword against names, descriptions, metrics, and column names. Returns the top 10 matches ranked by relevance. Use this BEFORE ask_data_question or run_semantic_query to find the correct dataset name.",
+    inputSchema: {
+        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 });
+});
+server.registerTool("get_dataset_context", {
+    title: "Get dataset context",
+    description: "Returns full context, columns, metrics, examples, and available dimensions for a dataset.",
+    inputSchema: {
+        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);
+    }
+});
+server.registerTool("run_semantic_query", {
+    title: "Run semantic query",
+    description: "Runs a semantic query against the data platform with guardrails. " +
+        "IMPORTANT: Brand-specific datasets contain both the user's brand AND competitor data. " +
+        "When the user asks about their own brand's performance, include the 'curr_brand' segment to filter to their brand only. " +
+        "When the user asks for competitor analysis or market-wide comparison, do NOT include 'curr_brand' so all brands are returned.",
+    inputSchema: {
+        tenantToken: z.string().optional(),
+        query: z.object({
+            dataset: z.string(),
+            metrics: z.array(z.string()).optional(),
+            dimensions: z.array(z.string()).optional(),
+            segments: z.array(z.string()).optional(),
+            filters: z.array(queryFilterSchema).optional(),
+            order: z.array(queryOrderSchema).optional(),
+            timeDimensions: z.array(queryTimeDimensionSchema).optional(),
+            limit: z.number().int().positive().optional()
+        })
+    }
+}, 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);
+    }
+});
+server.registerTool("ask_data_question", {
+    title: "Ask data question",
+    description: "Converts natural language to a strict semantic query plan and optionally executes it with tenant guardrails. " +
+        "IMPORTANT: Always call search_datasets first to resolve the exact dataset name and pass it as datasetHint. Do NOT guess dataset names. " +
+        "Brand-specific datasets contain both the user's brand AND competitor data. " +
+        "When the question is about the user's own brand, the plan should include the 'curr_brand' segment. " +
+        "When the question involves competitor analysis or market-wide data, do NOT include 'curr_brand'.",
+    inputSchema: {
+        tenantToken: z.string().optional(),
+        question: z.string().min(5),
+        datasetHint: z.string().optional(),
+        limitHint: z.number().int().positive().optional(),
+        execute: z.boolean().default(true)
+    },
+    outputSchema: {
+        plan: plannerOutputSchema,
+        executed: z.boolean(),
+        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: {
+                    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
+                });
+            }
+            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);
+    }
+});
+server.registerTool("login_brand", {
+    title: "Login brand",
+    description: "Authenticates with the Dcluttr auth service using email and password. Stores the session so subsequent queries run under the correct brand without requiring a manual token.",
+    inputSchema: {
+        email: z.string().email(),
+        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);
+    }
+});
+server.resource("catalog", new ResourceTemplate("catalog://datasets", { list: undefined }), {
+    title: "Dataset catalog",
+    description: "Complete metadata catalog for dataset, columns, and metric context.",
+    mimeType: "application/json"
+}, async () => ({
+    contents: [
+        {
+            uri: "catalog://datasets",
+            mimeType: "application/json",
+            text: JSON.stringify(metadataStore.getCatalog(), null, 2)
+        }
+    ]
+}));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function toToolError(error) {
+    if (error instanceof AppError) {
+        return {
+            isError: true,
+            ...textResult(error.message)
+        };
+    }
+    if (error instanceof z.ZodError) {
+        return {
+            isError: true,
+            ...textResult("Invalid input. Please check your query parameters and try again.")
+        };
+    }
+    return {
+        isError: true,
+        ...textResult("Something went wrong. Please try again.")
+    };
+}
+main().catch((error) => {
+    process.stderr.write("Failed to start MCP server.\n");
+    process.exit(1);
+});

package/dist/scripts/create-token.js

@@ -0,0 +1,9 @@
+import jwt from "jsonwebtoken";
+const secret = process.env.JWT_SECRET;
+if (!secret) {
+    throw new Error("JWT_SECRET is required");
+}
+const brandId = process.argv[2] ?? "demo-brand";
+const role = process.argv[3] ?? "brand_user";
+const token = jwt.sign({ brandId, role }, secret, { expiresIn: "12h" });
+process.stdout.write(`${token}\n`);

package/dist/services/auth-service.js

@@ -0,0 +1,84 @@
+import { env } from "../config/env.js";
+import { AppError } from "../utils/errors.js";
+export class AuthService {
+    session = null;
+    async login(email, password) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), env.AUTH_LOGIN_TIMEOUT_MS);
+        try {
+            const response = await fetch(env.AUTH_LOGIN_URL, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Accept: "application/json"
+                },
+                body: JSON.stringify({ email, password }),
+                signal: controller.signal
+            });
+            if (!response.ok) {
+                throw new AppError("AUTH_FAILED", "Login failed. Please check your email and password.", 401);
+            }
+            const data = (await response.json());
+            const nested = (data.data ?? {});
+            const token = String(data.token ?? data.access_token ?? data.accessToken ?? nested.accessToken ?? nested.access_token ?? nested.token ?? "");
+            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 };
+            return { brandId };
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            throw new AppError("AUTH_FAILED", "Failed to connect to the authentication service.", 502);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    getToken(explicitToken) {
+        if (explicitToken)
+            return explicitToken;
+        if (this.session)
+            return this.session.token;
+        throw new AppError("AUTH_REQUIRED", "Not logged in. Use the login_brand tool to authenticate first.", 401);
+    }
+    resolveTenantContext(token) {
+        if (token) {
+            const payload = this.decodeJwtPayload(token);
+            return this.extractTenant(payload);
+        }
+        if (this.session) {
+            return { brandId: this.session.brandId, role: this.session.role };
+        }
+        if (!env.REQUIRE_AUTH_TOKEN) {
+            return { brandId: env.DEFAULT_BRAND_ID, role: "brand_user" };
+        }
+        throw new AppError("AUTH_REQUIRED", "No authentication token provided. Use the login_brand tool to authenticate first.", 401);
+    }
+    extractTenant(payload) {
+        const brandEntry = payload.organizationAuthorities?.organizationBrandAuthorities?.[0];
+        const brandId = String(brandEntry?.brandId ?? "");
+        if (!brandId) {
+            throw new AppError("AUTH_INVALID_TOKEN", "Token does not contain a brandId.", 401);
+        }
+        const roles = payload.authorities?.map((a) => a.role) ?? [];
+        const role = roles.includes("write_user") ? "write_user" : roles[0] ?? "brand_user";
+        return { brandId, role };
+    }
+    decodeJwtPayload(token) {
+        try {
+            const parts = token.split(".");
+            if (parts.length !== 3)
+                throw new Error("Not a JWT");
+            const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+            const json = Buffer.from(padded, "base64").toString("utf8");
+            return JSON.parse(json);
+        }
+        catch {
+            throw new AppError("AUTH_INVALID_TOKEN", "Failed to decode authentication token.", 401);
+        }
+    }
+}

package/dist/services/cube-client.js

@@ -0,0 +1,30 @@
+import axios from "axios";
+import { env } from "../config/env.js";
+import { AppError } from "../utils/errors.js";
+export class CubeClient {
+    async load(query, brandId, authToken) {
+        try {
+            const response = await axios.post(`${env.CUBE_API_URL}/v1/load`, { query }, {
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: authToken,
+                    brandid: brandId
+                },
+                timeout: env.CUBE_QUERY_TIMEOUT_MS
+            });
+            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);
+            }
+            throw new AppError("QUERY_ERROR", "Failed to execute query. Please try again.", 502);
+        }
+    }
+}

package/dist/services/langfuse-hook.js

@@ -0,0 +1,46 @@
+import crypto from "node:crypto";
+import { env } from "../config/env.js";
+export class LangfuseHook {
+    async capture(event) {
+        if (!env.LANGFUSE_ENABLED || !env.LANGFUSE_PUBLIC_KEY || !env.LANGFUSE_SECRET_KEY) {
+            return;
+        }
+        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);
+        try {
+            await fetch(`${env.LANGFUSE_BASE_URL}/api/public/ingestion`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Basic ${auth}`,
+                    "Content-Type": "application/json"
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal
+            });
+        }
+        catch {
+            // Best-effort hook: never fail tool execution on observability side-effects.
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}

package/dist/services/metadata-store.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { env } from "../config/env.js";
+import { AppError } from "../utils/errors.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, "../..");
+export class MetadataStore {
+    catalog;
+    constructor() {
+        const absolutePath = path.isAbsolute(env.METADATA_PATH)
+            ? env.METADATA_PATH
+            : path.resolve(PKG_ROOT, env.METADATA_PATH);
+        const file = fs.readFileSync(absolutePath, "utf8");
+        this.catalog = JSON.parse(file);
+    }
+    getCatalog() {
+        return this.catalog;
+    }
+    listDatasets() {
+        return this.catalog.datasets.map((dataset) => ({
+            name: dataset.name,
+            description: dataset.description,
+            grain: dataset.grain,
+            owner: dataset.owner,
+            metrics: dataset.metrics.map((metric) => metric.name),
+            dimensions: dataset.columns.map((column) => column.name),
+            joins: dataset.joins?.map((j) => j.cube)
+        }));
+    }
+    getDataset(name) {
+        const dataset = this.catalog.datasets.find((item) => item.name === name);
+        if (!dataset) {
+            throw new AppError("DATASET_NOT_FOUND", `Dataset '${name}' is not configured.`, 404);
+        }
+        return dataset;
+    }
+    getDatasetWithJoins(name) {
+        const dataset = this.getDataset(name);
+        const joinedDimensions = this.resolveJoinedDimensions(dataset);
+        return {
+            ...dataset,
+            joinedDimensions
+        };
+    }
+    resolveJoinedDimensions(dataset) {
+        if (!dataset.joins || dataset.joins.length === 0)
+            return [];
+        return dataset.joins.flatMap((join) => {
+            const joinedCube = this.catalog.datasets.find((d) => d.name === join.cube);
+            if (!joinedCube)
+                return [];
+            return joinedCube.columns.map((col) => ({
+                name: `${join.cube}.${col.name}`,
+                dataType: col.dataType,
+                description: col.description,
+                fromCube: join.cube,
+                relationship: join.relationship
+            }));
+        });
+    }
+    searchDatasets(query) {
+        const tokens = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((t) => t.length > 1);
+        if (tokens.length === 0)
+            return this.listDatasets();
+        const scored = this.catalog.datasets.map((dataset) => {
+            const haystack = [
+                dataset.name,
+                dataset.description,
+                dataset.owner,
+                ...dataset.metrics.map((m) => `${m.name} ${m.description}`),
+                ...dataset.columns.map((c) => `${c.name} ${c.description} ${(c.synonyms ?? []).join(" ")}`),
+                ...(dataset.joins ?? []).map((j) => j.cube)
+            ]
+                .join(" ")
+                .toLowerCase();
+            const hits = tokens.filter((t) => haystack.includes(t)).length;
+            return { dataset, score: hits / tokens.length };
+        });
+        return scored
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 10)
+            .map((s) => ({
+            name: s.dataset.name,
+            description: s.dataset.description,
+            grain: s.dataset.grain,
+            owner: s.dataset.owner,
+            score: s.score,
+            metrics: s.dataset.metrics.map((m) => m.name),
+            dimensions: s.dataset.columns.map((c) => c.name),
+            joins: s.dataset.joins?.map((j) => j.cube),
+            joinedDimensions: this.resolveJoinedDimensions(s.dataset).map((d) => d.name)
+        }));
+    }
+    isDatasetAllowed(name) {
+        return this.catalog.datasets.some((dataset) => dataset.name === name);
+    }
+}

package/dist/services/observability-service.js

@@ -0,0 +1,49 @@
+import { trace, context, SpanStatusCode } from "@opentelemetry/api";
+import { BasicTracerProvider, BatchSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
+import { Resource } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import { env } from "../config/env.js";
+let initialized = false;
+function ensureTracerProvider() {
+    if (initialized || !env.OTEL_ENABLED) {
+        return;
+    }
+    const provider = new BasicTracerProvider({
+        resource: new Resource({
+            [ATTR_SERVICE_NAME]: env.MCP_SERVER_NAME,
+            [ATTR_SERVICE_VERSION]: env.MCP_SERVER_VERSION
+        })
+    });
+    if (env.OTEL_CONSOLE_EXPORTER) {
+        provider.addSpanProcessor(new BatchSpanProcessor(new ConsoleSpanExporter()));
+    }
+    trace.setGlobalTracerProvider(provider);
+    initialized = true;
+}
+export class ObservabilityService {
+    tracer = trace.getTracer("talk-to-data-mcp");
+    constructor() {
+        ensureTracerProvider();
+        this.tracer = trace.getTracer(env.MCP_SERVER_NAME);
+    }
+    async span(name, attributes, fn) {
+        return await this.tracer.startActiveSpan(name, { attributes }, async (span) => {
+            try {
+                const result = await context.with(context.active(), fn);
+                span.setStatus({ code: SpanStatusCode.OK });
+                return result;
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error)
+                });
+                span.recordException(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+}

package/dist/services/planner-executor.js

@@ -0,0 +1,9 @@
+export class PlannerExecutor {
+    queryService;
+    constructor(queryService) {
+        this.queryService = queryService;
+    }
+    async executePlan(plan, tenant, authToken) {
+        return await this.queryService.runQuery(plan.semanticQuery, tenant, authToken);
+    }
+}