@dcluttr/dclare-mcp 0.1.2

package/dist/services/planner-service.js

@@ -0,0 +1,131 @@
+import { env } from "../config/env.js";
+import { plannerOutputSchema } from "../types/planner.js";
+import { AppError } from "../utils/errors.js";
+import { tryParseJsonObject } from "../utils/json.js";
+export class PlannerService {
+    metadataStore;
+    constructor(metadataStore) {
+        this.metadataStore = metadataStore;
+    }
+    async plan(input) {
+        if (env.PLANNER_PROVIDER === "openai") {
+            const modelPlan = await this.planWithOpenAI(input);
+            return plannerOutputSchema.parse(modelPlan);
+        }
+        return this.planHeuristic(input);
+    }
+    planHeuristic(input) {
+        const datasets = this.metadataStore.getCatalog().datasets;
+        const dataset = input.datasetHint
+            ? this.metadataStore.getDataset(input.datasetHint)
+            : this.pickHeuristicDataset(input.question, datasets) ?? datasets[0];
+        if (!dataset) {
+            throw new AppError("PLANNER_ERROR", "No dataset available in metadata catalog.", 400);
+        }
+        const metric = dataset.metrics[0]?.name;
+        const timeDimension = dataset.timeDimension;
+        const tenantSegment = dataset.tenantEnforcement?.mode === "segment" ? dataset.tenantEnforcement.segmentName ?? "curr_brand" : undefined;
+        const semanticQuery = {
+            dataset: dataset.name,
+            metrics: metric ? [metric] : undefined,
+            dimensions: [],
+            segments: tenantSegment ? [tenantSegment] : undefined,
+            filters: [],
+            timeDimensions: timeDimension
+                ? [
+                    {
+                        member: timeDimension,
+                        dateRange: "last 30 days",
+                        granularity: "day"
+                    }
+                ]
+                : undefined,
+            limit: input.limitHint
+        };
+        return plannerOutputSchema.parse({
+            semanticQuery,
+            rationale: "Heuristic planner selected dataset by name match and default metric/time pattern.",
+            assumptions: ["Question intent is trend/summary oriented", "Use default 30-day horizon when timeframe is omitted"],
+            confidence: 0.55
+        });
+    }
+    matchesDataset(question, datasetName) {
+        return question.toLowerCase().includes(datasetName.toLowerCase());
+    }
+    pickHeuristicDataset(question, datasets) {
+        const q = question.toLowerCase();
+        const platformKeys = ["blinkit", "instamart", "zepto", "bbnow", "fkmin", "amazonnow"];
+        for (const platform of platformKeys) {
+            if (q.includes(platform)) {
+                const preferred = `${platform}_date_insights`;
+                const dataset = datasets.find((item) => item.name === preferred);
+                if (dataset)
+                    return dataset;
+            }
+        }
+        return datasets.find((item) => this.matchesDataset(question, item.name));
+    }
+    async planWithOpenAI(input) {
+        if (!env.OPENAI_API_KEY) {
+            throw new AppError("PLANNER_ERROR", "Query planner is not configured. Please contact support.", 500);
+        }
+        const catalog = this.metadataStore.getCatalog();
+        const prompt = [
+            "You are a query planner for Cube semantic queries.",
+            "Return JSON only, no markdown.",
+            "Respect dataset, metric, and dimension names exactly from catalog.",
+            "Planner output JSON schema:",
+            JSON.stringify({
+                semanticQuery: {
+                    dataset: "string",
+                    metrics: ["string"],
+                    dimensions: ["string"],
+                    filters: [{ member: "string", operator: "equals", values: ["string"] }],
+                    order: [{ member: "string", direction: "asc|desc" }],
+                    timeDimensions: [{ member: "string", dateRange: "last 30 days", granularity: "day" }],
+                    limit: 1000
+                },
+                rationale: "string",
+                assumptions: ["string"],
+                confidence: 0.8
+            }, null, 2),
+            "Catalog:",
+            JSON.stringify(catalog),
+            "User question:",
+            input.question,
+            input.datasetHint ? `Dataset hint: ${input.datasetHint}` : "",
+            input.limitHint ? `Limit hint: ${input.limitHint}` : ""
+        ]
+            .filter(Boolean)
+            .join("\n\n");
+        const response = await fetch(`${env.OPENAI_BASE_URL}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${env.OPENAI_API_KEY}`
+            },
+            body: JSON.stringify({
+                model: env.OPENAI_MODEL,
+                temperature: 0,
+                messages: [
+                    { role: "system", content: "You output strict JSON only." },
+                    { role: "user", content: prompt }
+                ],
+                response_format: { type: "json_object" }
+            })
+        });
+        if (!response.ok) {
+            throw new AppError("PLANNER_ERROR", "Failed to generate query plan. Please try again.", 502);
+        }
+        const payload = (await response.json());
+        const content = payload.choices?.[0]?.message?.content;
+        if (!content) {
+            throw new AppError("PLANNER_ERROR", "Failed to generate query plan. Please try again.", 502);
+        }
+        const parsed = tryParseJsonObject(content);
+        if (!parsed) {
+            throw new AppError("PLANNER_ERROR", "Failed to generate query plan. Please try again.", 502);
+        }
+        return parsed;
+    }
+}

package/dist/services/query-cache.js

@@ -0,0 +1,46 @@
+import { Redis } from "ioredis";
+import { env } from "../config/env.js";
+export class QueryCache {
+    redis = null;
+    constructor() {
+        if (env.REDIS_URL) {
+            this.redis = new Redis(env.REDIS_URL, {
+                lazyConnect: true,
+                maxRetriesPerRequest: 1,
+                enableOfflineQueue: false
+            });
+        }
+    }
+    isEnabled() {
+        return this.redis !== null;
+    }
+    async get(key) {
+        if (!this.redis) {
+            return null;
+        }
+        try {
+            if (this.redis.status === "wait") {
+                await this.redis.connect();
+            }
+            const raw = await this.redis.get(key);
+            return raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(key, value) {
+        if (!this.redis) {
+            return;
+        }
+        try {
+            if (this.redis.status === "wait") {
+                await this.redis.connect();
+            }
+            await this.redis.set(key, JSON.stringify(value), "EX", env.CACHE_TTL_SECONDS);
+        }
+        catch {
+            // Best-effort cache
+        }
+    }
+}

package/dist/services/query-guardrails.js

@@ -0,0 +1,120 @@
+import { env } from "../config/env.js";
+import { AppError } from "../utils/errors.js";
+function normalizeMemberName(member) {
+    const index = member.lastIndexOf(".");
+    return index >= 0 ? member.slice(index + 1) : member;
+}
+function isJoinedMember(member) {
+    return member.includes(".");
+}
+function buildJoinedCubeMap(dataset, allDatasets) {
+    const map = new Map();
+    for (const join of dataset.joins ?? []) {
+        const joinedDataset = allDatasets.find((d) => d.name === join.cube);
+        if (joinedDataset) {
+            map.set(join.cube, new Set(joinedDataset.columns.map((c) => c.name)));
+        }
+    }
+    return map;
+}
+function validateMember(member, allowedLocal, joinedCubes, label) {
+    if (isJoinedMember(member)) {
+        const dotIndex = member.indexOf(".");
+        const cubeName = member.slice(0, dotIndex);
+        const columnName = member.slice(dotIndex + 1);
+        const stripped = normalizeMemberName(columnName);
+        const joinedColumns = joinedCubes.get(cubeName);
+        if (joinedColumns && joinedColumns.has(stripped)) {
+            return `${cubeName}.${stripped}`;
+        }
+        throw new AppError("INVALID_QUERY", `${label} '${member}' is not allowed for this dataset.`, 400);
+    }
+    const normalized = normalizeMemberName(member);
+    if (allowedLocal.has(normalized)) {
+        return normalized;
+    }
+    throw new AppError("INVALID_QUERY", `${label} '${member}' is not allowed for this dataset.`, 400);
+}
+export class QueryGuardrails {
+    sanitizeAndBuildCubeQuery(input, dataset, allDatasets) {
+        const allowedColumns = new Set(dataset.columns.map((column) => column.name));
+        const allowedMetrics = new Set(dataset.metrics.map((metric) => metric.name));
+        const allowedSegments = new Set((dataset.segments ?? []).map((segment) => segment.name));
+        const joinedCubes = buildJoinedCubeMap(dataset, allDatasets ?? []);
+        const validatedDimensions = (input.dimensions ?? []).map((d) => validateMember(d, allowedColumns, joinedCubes, "Dimension"));
+        for (const metric of input.metrics ?? []) {
+            const normalized = normalizeMemberName(metric);
+            if (!allowedMetrics.has(normalized)) {
+                throw new AppError("INVALID_QUERY", `Metric '${metric}' is not allowed for this dataset.`, 400);
+            }
+        }
+        for (const segment of input.segments ?? []) {
+            const normalized = normalizeMemberName(segment);
+            if (!allowedSegments.has(normalized)) {
+                throw new AppError("INVALID_QUERY", `Segment '${segment}' is not allowed for this dataset.`, 400);
+            }
+        }
+        const validatedTimeDimensions = (input.timeDimensions ?? []).map((item) => {
+            const resolved = validateMember(item.member, allowedColumns, joinedCubes, "Time dimension");
+            return { ...item, member: resolved };
+        });
+        const validFilters = this.validateFilters(input.filters ?? [], allowedColumns, joinedCubes);
+        const allFilters = [...validFilters];
+        const order = this.validateOrder(input.order ?? [], allowedColumns, allowedMetrics, joinedCubes, dataset.cubeName);
+        const normalizedSegments = (input.segments ?? []).map((segment) => normalizeMemberName(segment));
+        const limit = Math.min(Math.max(1, input.limit ?? env.MAX_PREVIEW_ROWS), env.MAX_ROWS);
+        return {
+            measures: (input.metrics ?? []).map((metric) => this.toMember(dataset.cubeName, normalizeMemberName(metric))),
+            dimensions: validatedDimensions.map((d) => (d.includes(".") ? d : this.toMember(dataset.cubeName, d))),
+            segments: normalizedSegments.map((segment) => this.toMember(dataset.cubeName, segment)),
+            filters: allFilters.map((filter) => ({
+                member: filter.member.includes(".") ? filter.member : this.toMember(dataset.cubeName, filter.member),
+                operator: filter.operator,
+                values: filter.values
+            })),
+            order,
+            timeDimensions: validatedTimeDimensions.map((item) => ({
+                dimension: item.member.includes(".") ? item.member : this.toMember(dataset.cubeName, item.member),
+                dateRange: item.dateRange,
+                granularity: item.granularity
+            })),
+            limit
+        };
+    }
+    validateFilters(filters, allowedColumns, joinedCubes) {
+        return filters.map((filter) => {
+            const resolved = validateMember(filter.member, allowedColumns, joinedCubes, "Filter member");
+            if (!Array.isArray(filter.values) || filter.values.length === 0) {
+                throw new AppError("INVALID_QUERY", `Filter '${filter.member}' must include at least one value.`, 400);
+            }
+            return {
+                ...filter,
+                member: resolved
+            };
+        });
+    }
+    validateOrder(order, allowedColumns, allowedMetrics, joinedCubes, cubeName) {
+        const validated = {};
+        for (const item of order) {
+            let member;
+            try {
+                member = validateMember(item.member, allowedColumns, joinedCubes, "Order member");
+            }
+            catch {
+                const normalized = normalizeMemberName(item.member);
+                if (allowedMetrics.has(normalized)) {
+                    member = normalized;
+                }
+                else {
+                    throw new AppError("INVALID_QUERY", `Order member '${item.member}' is not allowed.`, 400);
+                }
+            }
+            const qualified = member.includes(".") ? member : this.toMember(cubeName, member);
+            validated[qualified] = item.direction;
+        }
+        return validated;
+    }
+    toMember(cubeName, member) {
+        return member.includes(".") ? member : `${cubeName}.${member}`;
+    }
+}

package/dist/services/query-service.js

@@ -0,0 +1,84 @@
+import { env } from "../config/env.js";
+import { sha256 } from "../utils/hash.js";
+import { stableStringify } from "../utils/json.js";
+export class QueryService {
+    metadataStore;
+    guardrails;
+    cubeClient;
+    profiler;
+    cache;
+    observability;
+    langfuse;
+    constructor(metadataStore, guardrails, cubeClient, profiler, cache, observability, langfuse) {
+        this.metadataStore = metadataStore;
+        this.guardrails = guardrails;
+        this.cubeClient = cubeClient;
+        this.profiler = profiler;
+        this.cache = cache;
+        this.observability = observability;
+        this.langfuse = langfuse;
+    }
+    async runQuery(input, tenant, authToken) {
+        const dataset = this.metadataStore.getDataset(input.dataset);
+        const cubeQuery = this.guardrails.sanitizeAndBuildCubeQuery(input, dataset, this.metadataStore.getCatalog().datasets);
+        const cacheKey = this.getCacheKey(tenant.brandId, cubeQuery);
+        return await this.observability.span("query.run", {
+            "tenant.brand_id": tenant.brandId,
+            "query.dataset": dataset.name,
+            "query.limit": cubeQuery.limit ?? 0,
+            "cache.enabled": this.cache.isEnabled()
+        }, async () => {
+            const cached = await this.cache.get(cacheKey);
+            if (cached) {
+                await this.langfuse.capture({
+                    name: "query.cache.hit",
+                    input,
+                    output: {
+                        dataset: cached.dataset,
+                        rowCount: cached.rowCount
+                    },
+                    metadata: {
+                        tenant: tenant.brandId,
+                        cacheKey
+                    }
+                });
+                return { ...cached, cache: "hit" };
+            }
+            const cubeResult = await this.observability.span("cube.load", {
+                "tenant.brand_id": tenant.brandId,
+                "query.dataset": dataset.name
+            }, async () => this.cubeClient.load(cubeQuery, tenant.brandId, authToken));
+            const response = this.buildResponse(dataset.name, cubeResult.data ?? [], cubeResult.lastRefreshTime ?? null);
+            await this.cache.set(cacheKey, response);
+            await this.langfuse.capture({
+                name: "query.executed",
+                input,
+                output: {
+                    dataset: response.dataset,
+                    rowCount: response.rowCount,
+                    cache: "miss"
+                },
+                metadata: {
+                    tenant: tenant.brandId,
+                    cacheKey,
+                    maxRows: env.MAX_ROWS
+                }
+            });
+            return { ...response, cache: "miss" };
+        });
+    }
+    buildResponse(dataset, rows, lastRefreshTime) {
+        const profiled = this.profiler.profile(rows);
+        return {
+            dataset,
+            rowCount: profiled.rowCount,
+            previewRows: profiled.previewRows,
+            numericSummary: profiled.numericSummary,
+            lastRefreshTime
+        };
+    }
+    getCacheKey(brandId, cubeQuery) {
+        const hash = sha256(stableStringify({ brandId, cubeQuery }));
+        return `${env.CACHE_PREFIX}:${brandId}:${hash}`;
+    }
+}

package/dist/services/result-profiler.js

@@ -0,0 +1,53 @@
+import { env } from "../config/env.js";
+export class ResultProfiler {
+    stripPrefix(key) {
+        const dotIndex = key.indexOf(".");
+        return dotIndex >= 0 ? key.slice(dotIndex + 1) : key;
+    }
+    stripRowKeys(row) {
+        const result = {};
+        for (const [key, value] of Object.entries(row)) {
+            result[this.stripPrefix(key)] = value;
+        }
+        return result;
+    }
+    profile(rows) {
+        const previewRows = rows.slice(0, env.MAX_PREVIEW_ROWS).map((row) => this.stripRowKeys(row));
+        const numericSummary = {};
+        if (rows.length === 0) {
+            return {
+                rowCount: 0,
+                previewRows,
+                numericSummary
+            };
+        }
+        const firstRow = rows[0];
+        if (!firstRow) {
+            return {
+                rowCount: 0,
+                previewRows,
+                numericSummary
+            };
+        }
+        const keys = Object.keys(firstRow);
+        for (const key of keys) {
+            const values = rows
+                .map((row) => row[key])
+                .filter((value) => typeof value === "number" && Number.isFinite(value));
+            if (values.length === 0) {
+                continue;
+            }
+            const sum = values.reduce((acc, value) => acc + value, 0);
+            numericSummary[this.stripPrefix(key)] = {
+                min: Math.min(...values),
+                max: Math.max(...values),
+                avg: Number((sum / values.length).toFixed(4))
+            };
+        }
+        return {
+            rowCount: rows.length,
+            previewRows,
+            numericSummary
+        };
+    }
+}

package/dist/types/cube.js

@@ -0,0 +1 @@
+export {};

package/dist/types/metadata.js

@@ -0,0 +1 @@
+export {};

package/dist/types/planner.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export const queryFilterSchema = z.object({
+    member: z.string(),
+    operator: z.enum([
+        "equals",
+        "notEquals",
+        "contains",
+        "notContains",
+        "startsWith",
+        "endsWith",
+        "gt",
+        "gte",
+        "lt",
+        "lte",
+        "inDateRange"
+    ]),
+    values: z.array(z.string()).min(1)
+});
+export const queryOrderSchema = z.object({
+    member: z.string(),
+    direction: z.enum(["asc", "desc"])
+});
+export const queryTimeDimensionSchema = z.object({
+    member: z.string(),
+    dateRange: z.union([z.string(), z.tuple([z.string(), z.string()])]),
+    granularity: z.enum(["hour", "day", "week", "month", "quarter", "year"]).optional()
+});
+export const semanticQuerySchema = 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()
+});
+export const plannerOutputSchema = z.object({
+    semanticQuery: semanticQuerySchema,
+    rationale: z.string().min(1),
+    assumptions: z.array(z.string()).default([]),
+    confidence: z.number().min(0).max(1)
+});

package/dist/types/query.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/errors.js

@@ -0,0 +1,9 @@
+export class AppError extends Error {
+    code;
+    statusCode;
+    constructor(code, message, statusCode = 400) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}

package/dist/utils/hash.js

@@ -0,0 +1,4 @@
+import crypto from "node:crypto";
+export function sha256(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}

package/dist/utils/json.js

@@ -0,0 +1,27 @@
+export function stableStringify(value) {
+    return JSON.stringify(sortRecursively(value));
+}
+function sortRecursively(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortRecursively);
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, nested]) => [key, sortRecursively(nested)]);
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+export function tryParseJsonObject(input) {
+    try {
+        const parsed = JSON.parse(input);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/result.js

@@ -0,0 +1,6 @@
+export function textResult(message, structuredContent) {
+    return {
+        content: [{ type: "text", text: message }],
+        structuredContent
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dcluttr/dclare-mcp",
+  "version": "0.1.2",
+  "type": "module",
+  "description": "MCP server for secure talk-to-data on Cube + ClickHouse",
+  "bin": {
+    "dclare-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "context"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^1.30.1",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@opentelemetry/semantic-conventions": "^1.30.0",
+    "axios": "^1.13.6",
+    "ioredis": "^5.7.0",
+    "jsonwebtoken": "^9.0.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^24.5.2",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}