qualmcp 0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "qualmcp",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "qualmcp": "src/cli.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "start:env": "node src/launch-env.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.4.5",
+    "pg": "^8.11.3",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.24.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import process from 'node:process';
+
+const dbUrl = String(process.env.DATABASE_URL || '').trim();
+if (!dbUrl) {
+  process.stderr.write('DATABASE_URL is required\n');
+  process.exit(1);
+}
+
+await import('./index.js');

package/src/db.js

@@ -0,0 +1,27 @@
+import pg from 'pg';
+
+const { Pool } = pg;
+
+function getDatabaseUrl() {
+  const url = process.env.DATABASE_URL;
+  if (!url) {
+    throw new Error('DATABASE_URL is required');
+  }
+  return url;
+}
+
+function buildSslConfig() {
+  const mode = String(process.env.PGSSLMODE || '').toLowerCase();
+  if (!mode || mode === 'disable' || mode === 'false' || mode === '0') return false;
+  if (mode === 'require' || mode === 'true' || mode === '1') return { rejectUnauthorized: false };
+  return { rejectUnauthorized: false };
+}
+
+export const pool = new Pool({
+  connectionString: getDatabaseUrl(),
+  ssl: buildSslConfig()
+});
+
+export async function query(sql, params = []) {
+  return await pool.query(sql, params);
+}

package/src/index.js

@@ -0,0 +1,58 @@
+import 'dotenv/config';
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+import { tools } from './tools.js';
+
+const server = new Server(
+  {
+    name: 'qualmcp',
+    version: '0.1.0'
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: Object.values(tools).map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: zodToJsonSchema(t.schema, { name: t.name })
+    }))
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const name = req?.params?.name;
+  const args = req?.params?.arguments || {};
+
+  const entry = Object.values(tools).find((t) => t.name === name);
+  if (!entry) {
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ success: false, error: `Unknown tool: ${name}` }) }]
+    };
+  }
+
+  try {
+    const parsed = entry.schema.parse(args);
+    const result = await entry.handler(parsed);
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ success: true, result }, null, 2) }]
+    };
+  } catch (e) {
+    const msg = e?.message || String(e);
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ success: false, error: msg }, null, 2) }]
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/launch-env.js

@@ -0,0 +1,14 @@
+import path from 'node:path';
+import process from 'node:process';
+
+function main() {
+  const dbUrl = String(process.env.DATABASE_URL || '').trim();
+  if (!dbUrl) {
+    throw new Error('DATABASE_URL is required');
+  }
+
+  const entry = path.resolve('src/index.js');
+  import(entry);
+}
+
+main();

package/src/sql.js

@@ -0,0 +1,58 @@
+export function buildOrderScopeWhere({ mode, statusIds, statusKeys, excludeSpam } = {}, startIndex = 1) {
+  const clauses = [];
+  const params = [];
+
+  const safeMode = mode || 'all';
+  let nextIndex = Number.isFinite(Number(startIndex)) ? Number(startIndex) : 1;
+
+  const pushParam = (value) => {
+    params.push(value);
+    const idx = nextIndex;
+    nextIndex += 1;
+    return idx;
+  };
+
+  if (safeMode === 'orderedFlag') {
+    clauses.push('os.is_ordered = TRUE');
+  }
+
+  if (safeMode === 'statusIds') {
+    const ids = Array.isArray(statusIds)
+      ? Array.from(new Set(statusIds.map((x) => Number(x)).filter((n) => Number.isFinite(n))))
+      : [];
+    if (ids.length > 0) {
+      const idx = pushParam(ids);
+      clauses.push(`o.status_id = ANY($${idx})`);
+    } else {
+      clauses.push('1=0');
+    }
+  }
+
+  if (safeMode === 'statusKeys') {
+    const keys = Array.isArray(statusKeys)
+      ? Array.from(new Set(statusKeys.map((x) => String(x || '').trim()).filter(Boolean)))
+      : [];
+    if (keys.length > 0) {
+      const idx = pushParam(keys);
+      clauses.push(`os.key = ANY($${idx})`);
+    } else {
+      clauses.push('1=0');
+    }
+  }
+
+  if (excludeSpam === true) {
+    clauses.push('COALESCE(os.is_spam, FALSE) = FALSE');
+  }
+
+  return {
+    whereSql: clauses.length > 0 ? clauses.join(' AND ') : '1=1',
+    params,
+    nextIndex
+  };
+}
+
+export function normalizeDateField(dateField) {
+  const allowed = new Set(['created_at', 'ordered_at', 'updated_at']);
+  const f = String(dateField || '').trim();
+  return allowed.has(f) ? f : 'created_at';
+}

package/src/tools.js

@@ -0,0 +1,379 @@
+import { z } from 'zod';
+import { query } from './db.js';
+import { buildOrderScopeWhere, normalizeDateField } from './sql.js';
+
+const OrderScopeSchema = z.object({
+  mode: z.enum(['all', 'statusIds', 'statusKeys', 'orderedFlag']).default('all'),
+  statusIds: z.array(z.number()).optional(),
+  statusKeys: z.array(z.string()).optional(),
+  excludeSpam: z.boolean().optional()
+}).optional();
+
+const DateFieldSchema = z.enum(['created_at', 'ordered_at', 'updated_at']).optional();
+
+function parseSkuTag(productSku) {
+  const raw = String(productSku || '').trim();
+  if (!raw) return { sku: null, tag: null, compound: null };
+  if (raw.includes('/')) {
+    const [sku, tag] = raw.split('/', 2);
+    const base = String(sku || '').trim();
+    const t = String(tag || '').trim();
+    return { sku: base || null, tag: t || null, compound: `${base}/${t}` };
+  }
+  return { sku: raw, tag: null, compound: raw };
+}
+
+function safeLimit(v, max = 200) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return 50;
+  return Math.min(max, Math.max(1, Math.floor(n)));
+}
+
+export const tools = {
+  analytics_salesRank: {
+    name: 'analytics.salesRank',
+    description: 'Ranking of products by sales quantity/revenue across orders with flexible filters and grouping. Always returns product names when possible.',
+    schema: z.object({
+      dateFrom: z.string().datetime().optional(),
+      dateTo: z.string().datetime().optional(),
+      dateField: DateFieldSchema,
+      managerId: z.number().optional(),
+      orderScope: OrderScopeSchema,
+      groupBy: z.enum(['sku', 'sku_tag']).default('sku_tag'),
+      metric: z.enum(['qty', 'revenueApprox', 'ordersCount']).default('qty'),
+      limit: z.number().optional(),
+      offset: z.number().optional()
+    }),
+    handler: async (input) => {
+      const {
+        dateFrom,
+        dateTo,
+        dateField,
+        managerId,
+        orderScope,
+        groupBy,
+        metric,
+        limit,
+        offset
+      } = input;
+
+      const field = normalizeDateField(dateField);
+      const scope = buildOrderScopeWhere(orderScope);
+
+      const params = [...scope.params];
+      const clauses = [scope.whereSql];
+
+      if (dateFrom) {
+        params.push(dateFrom);
+        clauses.push(`o.${field} >= $${params.length}`);
+      }
+      if (dateTo) {
+        params.push(dateTo);
+        clauses.push(`o.${field} <= $${params.length}`);
+      }
+      if (managerId != null) {
+        params.push(Number(managerId));
+        clauses.push(`o.manager_id = $${params.length}`);
+      }
+
+      const where = clauses.length > 0 ? clauses.join(' AND ') : '1=1';
+      const lim = safeLimit(limit, 500);
+      const off = Math.max(0, Math.floor(Number(offset || 0)));
+
+      const groupExpr = groupBy === 'sku'
+        ? `base_sku`
+        : `compound_sku`;
+
+      const orderExpr = metric === 'ordersCount'
+        ? 'orders_count'
+        : metric === 'revenueApprox'
+          ? 'revenue_approx'
+          : 'qty';
+
+      const sql = `
+        WITH expanded AS (
+          SELECT
+            o.id AS order_id,
+            o.manager_id,
+            o.${field} AS order_date,
+            x.sku AS raw_sku,
+            COALESCE(x.quantity, 1) AS qty,
+            CASE WHEN POSITION('/' IN x.sku) > 0 THEN SUBSTRING(x.sku FROM 1 FOR POSITION('/' IN x.sku) - 1) ELSE x.sku END AS base_sku,
+            CASE WHEN POSITION('/' IN x.sku) > 0 THEN SUBSTRING(x.sku FROM POSITION('/' IN x.sku) + 1) ELSE NULL END AS tag,
+            x.sku AS compound_sku
+          FROM orders o
+          LEFT JOIN order_statuses os ON os.id = o.status_id
+          JOIN LATERAL jsonb_to_recordset(o.products) AS x(sku text, quantity int) ON TRUE
+          WHERE ${where}
+            AND x.sku IS NOT NULL AND x.sku != ''
+        ),
+        agg AS (
+          SELECT
+            ${groupExpr} AS group_key,
+            base_sku,
+            tag,
+            SUM(qty)::bigint AS qty,
+            COUNT(DISTINCT order_id)::bigint AS orders_count
+          FROM expanded
+          GROUP BY ${groupExpr}, base_sku, tag
+        ),
+        product_pick AS (
+          SELECT
+            a.group_key,
+            a.base_sku,
+            a.tag,
+            a.qty,
+            a.orders_count,
+            p.id AS product_id,
+            p.name AS product_name,
+            p.price,
+            p.discount,
+            ROUND((COALESCE(p.price::numeric, 0) * (1 - COALESCE(p.discount::numeric, 0) / 100))::numeric, 2) AS final_price
+          FROM agg a
+          LEFT JOIN LATERAL (
+            SELECT id, name, price, discount
+            FROM products
+            WHERE sku = a.base_sku
+              AND ( (a.tag IS NOT NULL AND tag = a.tag) OR (a.tag IS NULL) )
+            ORDER BY
+              CASE WHEN a.tag IS NOT NULL AND tag = a.tag THEN 0 ELSE 1 END,
+              created_at ASC
+            LIMIT 1
+          ) p ON TRUE
+        )
+        SELECT
+          group_key,
+          base_sku AS sku,
+          tag,
+          product_name,
+          qty,
+          orders_count,
+          (qty * COALESCE(final_price, 0))::numeric AS revenue_approx
+        FROM product_pick
+        ORDER BY ${orderExpr} DESC NULLS LAST, qty DESC
+        LIMIT ${lim} OFFSET ${off}
+      `;
+
+      const res = await query(sql, params);
+      return {
+        rows: res.rows || [],
+        meta: {
+          metric,
+          groupBy,
+          dateField: field,
+          limit: lim,
+          offset: off
+        }
+      };
+    }
+  },
+
+  analytics_stockHealth: {
+    name: 'analytics.stockHealth',
+    description: 'Stock + sales velocity and days-cover metrics per product (optionally per store). Returns product names and signals; interpretation is left to the agent.',
+    schema: z.object({
+      storeId: z.number().optional(),
+      salesWindowDays: z.number().default(30),
+      dateTo: z.string().datetime().optional(),
+      dateField: DateFieldSchema,
+      orderScope: OrderScopeSchema,
+      includeZeroSales: z.boolean().default(true),
+      minSalesQty: z.number().default(0),
+      limit: z.number().optional(),
+      offset: z.number().optional()
+    }),
+    handler: async (input) => {
+      const {
+        storeId,
+        salesWindowDays,
+        dateTo,
+        dateField,
+        orderScope,
+        includeZeroSales,
+        minSalesQty,
+        limit,
+        offset
+      } = input;
+
+      const field = normalizeDateField(dateField);
+      const to = dateTo ? new Date(dateTo) : new Date();
+      const windowDays = Math.max(1, Math.min(3650, Math.floor(Number(salesWindowDays || 30))));
+      const from = new Date(to.getTime() - windowDays * 24 * 60 * 60 * 1000);
+
+      const hasStore = storeId != null;
+      const storeParams = hasStore ? [Number(storeId)] : [];
+      const scope = buildOrderScopeWhere(orderScope, hasStore ? 2 : 1);
+
+      const params = [...storeParams, ...scope.params];
+      const clauses = [scope.whereSql];
+
+      params.push(from.toISOString());
+      clauses.push(`o.${field} >= $${params.length}`);
+      params.push(to.toISOString());
+      clauses.push(`o.${field} <= $${params.length}`);
+
+      const where = clauses.length > 0 ? clauses.join(' AND ') : '1=1';
+      const lim = safeLimit(limit, 500);
+      const off = Math.max(0, Math.floor(Number(offset || 0)));
+
+      const sql = `
+        WITH stock AS (
+          SELECT
+            ${storeId != null ? 'si.store_id' : 'NULL::bigint'} AS store_id,
+            si.product_sku AS compound_sku,
+            SUM(COALESCE(si.quantity, 0))::bigint AS stock_qty
+          FROM store_inventory si
+          ${storeId != null ? 'WHERE si.store_id = $1' : ''}
+          GROUP BY ${storeId != null ? 'si.store_id, si.product_sku' : 'si.product_sku'}
+        ),
+        sales_expanded AS (
+          SELECT
+            x.sku AS compound_sku,
+            COALESCE(x.quantity, 1) AS qty
+          FROM orders o
+          LEFT JOIN order_statuses os ON os.id = o.status_id
+          JOIN LATERAL jsonb_to_recordset(o.products) AS x(sku text, quantity int) ON TRUE
+          WHERE ${where}
+            AND x.sku IS NOT NULL AND x.sku != ''
+        ),
+        sales AS (
+          SELECT
+            compound_sku,
+            SUM(qty)::bigint AS sales_qty_window
+          FROM sales_expanded
+          GROUP BY compound_sku
+        ),
+        merged AS (
+          SELECT
+            s.store_id,
+            s.compound_sku,
+            s.stock_qty,
+            COALESCE(sa.sales_qty_window, 0)::bigint AS sales_qty_window
+          FROM stock s
+          LEFT JOIN sales sa ON sa.compound_sku = s.compound_sku
+        ),
+        parsed AS (
+          SELECT
+            m.*,
+            CASE WHEN POSITION('/' IN m.compound_sku) > 0 THEN SUBSTRING(m.compound_sku FROM 1 FOR POSITION('/' IN m.compound_sku) - 1) ELSE m.compound_sku END AS base_sku,
+            CASE WHEN POSITION('/' IN m.compound_sku) > 0 THEN SUBSTRING(m.compound_sku FROM POSITION('/' IN m.compound_sku) + 1) ELSE NULL END AS tag
+          FROM merged m
+        ),
+        with_product AS (
+          SELECT
+            p2.store_id,
+            p2.compound_sku,
+            p2.base_sku AS sku,
+            p2.tag,
+            p2.stock_qty,
+            p2.sales_qty_window,
+            (p2.sales_qty_window::numeric / ${windowDays}::numeric) AS avg_daily_sales,
+            CASE WHEN (p2.sales_qty_window::numeric / ${windowDays}::numeric) > 0
+              THEN (p2.stock_qty::numeric / (p2.sales_qty_window::numeric / ${windowDays}::numeric))
+              ELSE NULL
+            END AS days_cover,
+            pr.name AS product_name,
+            pr.price,
+            pr.discount,
+            pr.category_id
+          FROM parsed p2
+          LEFT JOIN LATERAL (
+            SELECT name, price, discount, category_id
+            FROM products
+            WHERE sku = p2.base_sku
+              AND ( (p2.tag IS NOT NULL AND tag = p2.tag) OR (p2.tag IS NULL) )
+            ORDER BY
+              CASE WHEN p2.tag IS NOT NULL AND tag = p2.tag THEN 0 ELSE 1 END,
+              created_at ASC
+            LIMIT 1
+          ) pr ON TRUE
+        )
+        SELECT *
+        FROM with_product
+        WHERE (sales_qty_window >= $${params.length + 1})
+          ${includeZeroSales ? '' : 'AND sales_qty_window > 0'}
+        ORDER BY
+          CASE WHEN days_cover IS NULL THEN 1 ELSE 0 END,
+          days_cover ASC NULLS LAST,
+          stock_qty ASC
+        LIMIT ${lim} OFFSET ${off}
+      `;
+
+      const res = await query(sql, [...params, Number(minSalesQty || 0)]);
+
+      return {
+        window: {
+          from: from.toISOString(),
+          to: to.toISOString(),
+          days: windowDays,
+          dateField: field
+        },
+        rows: res.rows || []
+      };
+    }
+  },
+
+  analytics_salesTimeSeries: {
+    name: 'analytics.salesTimeSeries',
+    description: 'Time series aggregation of orders and items sold over time buckets (day/week/month) with flexible orderScope.',
+    schema: z.object({
+      dateFrom: z.string().datetime().optional(),
+      dateTo: z.string().datetime().optional(),
+      dateField: DateFieldSchema,
+      bucket: z.enum(['day', 'week', 'month']).default('day'),
+      managerId: z.number().optional(),
+      orderScope: OrderScopeSchema
+    }),
+    handler: async (input) => {
+      const { dateFrom, dateTo, dateField, bucket, managerId, orderScope } = input;
+
+      const field = normalizeDateField(dateField);
+      const scope = buildOrderScopeWhere(orderScope);
+      const params = [...scope.params];
+      const clauses = [scope.whereSql];
+
+      if (dateFrom) {
+        params.push(dateFrom);
+        clauses.push(`o.${field} >= $${params.length}`);
+      }
+      if (dateTo) {
+        params.push(dateTo);
+        clauses.push(`o.${field} <= $${params.length}`);
+      }
+      if (managerId != null) {
+        params.push(Number(managerId));
+        clauses.push(`o.manager_id = $${params.length}`);
+      }
+
+      const where = clauses.join(' AND ');
+      const trunc = bucket === 'week' ? 'week' : bucket === 'month' ? 'month' : 'day';
+
+      const sql = `
+        WITH expanded AS (
+          SELECT
+            o.id AS order_id,
+            date_trunc('${trunc}', o.${field}) AS period_start,
+            COALESCE(x.quantity, 1) AS qty
+          FROM orders o
+          LEFT JOIN order_statuses os ON os.id = o.status_id
+          JOIN LATERAL jsonb_to_recordset(o.products) AS x(sku text, quantity int) ON TRUE
+          WHERE ${where}
+        )
+        SELECT
+          period_start,
+          COUNT(DISTINCT order_id)::bigint AS orders_count,
+          SUM(qty)::bigint AS items_qty
+        FROM expanded
+        GROUP BY period_start
+        ORDER BY period_start ASC
+      `;
+
+      const res = await query(sql, params);
+      return {
+        bucket: trunc,
+        dateField: field,
+        rows: res.rows || []
+      };
+    }
+  }
+};