distil-ai-rms-reporting 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# Distil AI - RMS Reporting
+
+MCP server that connects Claude Desktop to your restaurant management analytics.
+
+## Setup Instructions
+
+### 1. Install Node.js
+
+Download and install Node.js (version 18 or later) from [nodejs.org](https://nodejs.org/).
+
+Choose the **LTS** version and follow the installer prompts.
+
+### 2. Configure Claude Desktop
+
+Open Claude Desktop, then open the MCP configuration file:
+
+- **Mac**: Claude Desktop menu > Settings > Developer > Edit Config
+- **Windows**: File > Settings > Developer > Edit Config
+
+This opens your `claude_desktop_config.json` file. Replace its contents with the following (or add the `distil-ai-rms-reporting` entry to your existing `mcpServers` block):
+
+```json
+{
+  "mcpServers": {
+    "distil-ai-rms-reporting": {
+      "command": "npx",
+      "args": ["-y", "distil-ai-rms-reporting"],
+      "env": {
+        "API_BASE_URL": "YOUR_API_URL",
+        "API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Replace `YOUR_API_URL` and `YOUR_API_KEY` with the values provided to you by your Distil contact.
+
+### 3. Restart Claude Desktop
+
+Quit Claude Desktop completely and reopen it. You should see a tools icon in the chat input area confirming the connection is active.
+
+### 4. Start asking questions
+
+Try prompts like:
+
+- "Show me reservation trends for the last 3 months"
+- "Which restaurant has the highest no-show rate?"
+- "What does demand look like for next week?"
+- "How are our review scores trending?"
+
+## Troubleshooting
+
+- **Tools icon not appearing**: Make sure Node.js is installed by opening a terminal and running `node --version`. You should see `v18` or higher.
+- **Connection errors**: Double-check your `API_URL` and `API_KEY` values in the config file.
+- **Still not working**: Quit and reopen Claude Desktop after any config changes.

package/dist/api.js

@@ -0,0 +1,201 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setMcpContext = setMcpContext;
+exports.testConnection = testConnection;
+exports.apiGetSchema = apiGetSchema;
+exports.apiQueryReservations = apiQueryReservations;
+exports.apiGetSummaryStats = apiGetSummaryStats;
+exports.apiGetLoyaltyBreakdown = apiGetLoyaltyBreakdown;
+exports.apiGetGuestBehaviour = apiGetGuestBehaviour;
+exports.apiGetRevenueStats = apiGetRevenueStats;
+exports.apiGetTimePatternStats = apiGetTimePatternStats;
+exports.apiGetDemandOutlook = apiGetDemandOutlook;
+exports.apiGetReviewStats = apiGetReviewStats;
+exports.apiGetForecastStats = apiGetForecastStats;
+exports.apiGetDateStats = apiGetDateStats;
+const dotenv_1 = __importDefault(require("dotenv"));
+const crypto_1 = __importDefault(require("crypto"));
+dotenv_1.default.config();
+const requiredEnvVars = ["API_BASE_URL", "API_KEY"];
+for (const key of requiredEnvVars) {
+    if (!process.env[key]) {
+        console.error(`Missing required environment variable: ${key}`);
+        process.exit(1);
+    }
+}
+const BASE_URL = process.env.API_BASE_URL.replace(/\/$/, "");
+const API_KEY = process.env.API_KEY;
+function authHeaders() {
+    return {
+        "Authorization": `Bearer ${API_KEY}`,
+        "Content-Type": "application/json",
+    };
+}
+// Context headers for query logging — set per-request by tool handlers
+let _mcpContext = {};
+function setMcpContext(toolName, userPrompt) {
+    _mcpContext = { toolName, userPrompt };
+}
+function mcpHeaders() {
+    const headers = {};
+    headers["X-Request-Id"] = crypto_1.default.randomUUID();
+    if (_mcpContext.toolName)
+        headers["X-MCP-Tool"] = _mcpContext.toolName;
+    if (_mcpContext.userPrompt) {
+        headers["X-User-Prompt"] = Buffer.from(_mcpContext.userPrompt).toString("base64");
+    }
+    return headers;
+}
+async function request(path, options) {
+    const url = `${BASE_URL}${path}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: { ...authHeaders(), ...mcpHeaders(), ...(options?.headers ?? {}) },
+    });
+    // Clear context after each request
+    _mcpContext = {};
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`API error ${res.status} on ${path}${body ? `: ${body}` : ""}`);
+    }
+    return res.json();
+}
+async function testConnection() {
+    try {
+        await request("/health");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`API connection failed: ${msg}`);
+        console.error(`Check that API_BASE_URL and API_KEY in .env are correct.`);
+        process.exit(1);
+    }
+}
+async function apiGetSchema() {
+    return request("/schema");
+}
+async function apiQueryReservations(whereClause, tenantCode) {
+    return request("/reservations/query", {
+        method: "POST",
+        body: JSON.stringify({ where_clause: whereClause, tenant_code: tenantCode }),
+    });
+}
+async function apiGetSummaryStats(groupByField, tenantCode) {
+    const params = new URLSearchParams({ group_by: groupByField });
+    if (tenantCode)
+        params.set("tenant_code", tenantCode);
+    return request(`/summary-stats?${params}`);
+}
+async function apiGetLoyaltyBreakdown(tenantCode) {
+    const params = tenantCode ? `?tenant_code=${encodeURIComponent(tenantCode)}` : "";
+    return request(`/loyalty-breakdown${params}`);
+}
+async function apiGetGuestBehaviour(dimension, dateFrom, dateTo, tenantCode) {
+    const params = new URLSearchParams({ dimension });
+    if (dateFrom)
+        params.set("date_from", dateFrom);
+    if (dateTo)
+        params.set("date_to", dateTo);
+    if (tenantCode)
+        params.set("tenant_code", tenantCode);
+    return request(`/guest-behaviour?${params}`);
+}
+async function apiGetRevenueStats(dimension, period, dateFrom, dateTo, tenantCode) {
+    const params = new URLSearchParams({ dimension });
+    if (period)
+        params.set("period", period);
+    if (dateFrom)
+        params.set("date_from", dateFrom);
+    if (dateTo)
+        params.set("date_to", dateTo);
+    if (tenantCode)
+        params.set("tenant_code", tenantCode);
+    return request(`/revenue-stats?${params}`);
+}
+async function apiGetTimePatternStats(dimension, dateFrom, dateTo, tenantCode) {
+    const params = new URLSearchParams({ dimension });
+    if (dateFrom)
+        params.set("date_from", dateFrom);
+    if (dateTo)
+        params.set("date_to", dateTo);
+    if (tenantCode)
+        params.set("tenant_code", tenantCode);
+    return request(`/time-pattern-stats?${params}`);
+}
+async function apiGetDemandOutlook(dimension, snapshotDate, restaurantName, dateFrom, dateTo, partySize, tenantCode) {
+    const params = new URLSearchParams({ dimension });
+    if (snapshotDate)
+        params.set("snapshot_date", snapshotDate);
+    if (restaurantName)
+        params.set("restaurant_name", restaurantName);
+    if (dateFrom)
+        params.set("date_from", dateFrom);
+    if (dateTo)
+        params.set("date_to", dateTo);
+    if (partySize)
+        params.set("party_size", partySize);
+    if (tenantCode)
+        params.set("tenant_code", tenantCode);
+    return request(`/demand-outlook?${params}`);
+}
+async function apiGetReviewStats(dimension, restaurantName, restaurantCategory, source, dateFrom, dateTo, period, minRating, maxRating, sortBy, weeks, tenantCode) {
+    const params = new URLSearchParams({ dimension });
+    if (restaurantName)
+        params.set("restaurant_name", restaurantName);
+    if (restaurantCategory)
+        params.set("restaurant_category", restaurantCategory);
+    if (source)
+        params.set("source", source);
+    if (dateFrom)
+        params.set("date_from", dateFrom);
+    if (dateTo)
+        params.set("date_to", dateTo);
+    if (period)
+        params.set("period", period);
+    if (minRating)
+        params.set("min_rating", minRating);
+    if (maxRating)
+        params.set("max_rating", maxRating);
+    if (sortBy)
+        params.set("sort_by", sortBy);
+    if (weeks)
+        params.set("weeks", weeks);
+    if (tenantCode)
+        params.set("tenant_code", tenantCode);
+    return request(`/review-stats?${params}`);
+}
+async function apiGetForecastStats(dimension, snapshotDate, restaurantName, serviceDateFrom, serviceDateTo, service, snapshotDate2, tenantCode) {
+    const params = new URLSearchParams({ dimension });
+    if (snapshotDate)
+        params.set("snapshot_date", snapshotDate);
+    if (restaurantName)
+        params.set("restaurant_name", restaurantName);
+    if (serviceDateFrom)
+        params.set("service_date_from", serviceDateFrom);
+    if (serviceDateTo)
+        params.set("service_date_to", serviceDateTo);
+    if (service)
+        params.set("service", service);
+    if (snapshotDate2)
+        params.set("snapshot_date_2", snapshotDate2);
+    if (tenantCode)
+        params.set("tenant_code", tenantCode);
+    return request(`/forecast-stats?${params}`);
+}
+async function apiGetDateStats(period, groupBy, dateFrom, dateTo, tenantCode, restaurantName) {
+    const params = new URLSearchParams({ period });
+    if (groupBy)
+        params.set("group_by", groupBy);
+    if (dateFrom)
+        params.set("date_from", dateFrom);
+    if (dateTo)
+        params.set("date_to", dateTo);
+    if (tenantCode)
+        params.set("tenant_code", tenantCode);
+    if (restaurantName)
+        params.set("restaurant_name", restaurantName);
+    return request(`/date-stats?${params}`);
+}

package/dist/index.js

@@ -0,0 +1,471 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const api_js_1 = require("./api.js");
+const tools_js_1 = require("./tools.js");
+const server = new index_js_1.Server({ name: "distil-ai-rms-reporting", version: "1.0.0" }, { capabilities: { tools: {} } });
+const TENANT_PARAM = {
+    tenant_code: {
+        type: "string",
+        description: "Optional. Restrict results to a specific tenant (brand). If omitted, all tenants your token has access to are included.",
+    },
+};
+const PROMPT_PARAM = {
+    _user_prompt: {
+        type: "string",
+        description: "Optional. Pass the user's original natural language question that triggered this tool call. Used for usage analytics and improving data quality.",
+    },
+};
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "get_schema",
+            description: "Returns the column structure of the data_reservation_master table. Call this first to understand available fields before writing queries.",
+            inputSchema: {
+                type: "object",
+                properties: { ...PROMPT_PARAM },
+                required: [],
+            },
+        },
+        {
+            name: "query_reservations",
+            description: "Query data_reservation_master by providing a SQL WHERE clause. Returns up to 200 matching rows. Do not include the full SELECT statement — only the filter condition. Outcome values: Done, NoShow, Cancelled (past reservations), Confirmed, NotConfirmed (future reservations). Example: \"outcome = 'NoShow' AND restaurant_name = 'Harbour'\"",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    where_clause: {
+                        type: "string",
+                        description: "A SQL WHERE clause fragment (no SELECT, no semicolons). Example: \"restaurant_name = 'Harbour' AND covers > 4\"",
+                    },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["where_clause"],
+            },
+        },
+        {
+            name: "get_summary_stats",
+            description: "Returns aggregate counts grouped by a specified column. Outcome values are: Done, NoShow, Cancelled (past reservations) and Confirmed, NotConfirmed (future reservations). Useful for quick breakdowns by outcome, restaurant_name, guest_loyalty_level_at_time, origin, etc.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    group_by_field: {
+                        type: "string",
+                        enum: [
+                            "outcome",
+                            "restaurant_name",
+                            "origin",
+                            "guest_loyalty_level_at_time",
+                            "covers",
+                            "currency_code",
+                            "tenant_code",
+                        ],
+                        description: "Column to group by. Must be one of the listed values.",
+                    },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["group_by_field"],
+            },
+        },
+        {
+            name: "get_revenue_stats",
+            description: "Revenue-focused analysis for CFO-level questions. Covers revenue per cover, no-show cost, channel performance, restaurant rankings, and forward-looking revenue at risk from upcoming bookings. Use this for any question involving money, revenue, financial performance, or cost of no-shows.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    dimension: {
+                        type: "string",
+                        enum: ["by_period", "by_channel", "by_restaurant", "no_show_cost", "revenue_at_risk"],
+                        description: "by_period: revenue trend over time (requires period param). by_channel: revenue and no-show rate by booking origin. by_restaurant: revenue per cover by venue. no_show_cost: estimated lost revenue per restaurant. revenue_at_risk: expected revenue from upcoming confirmed bookings.",
+                    },
+                    period: {
+                        type: "string",
+                        enum: ["day", "week", "month", "quarter", "year"],
+                        description: "Required when dimension=by_period.",
+                    },
+                    date_from: { type: "string", description: "Optional start date filter (ISO 8601)." },
+                    date_to: { type: "string", description: "Optional end date filter (ISO 8601)." },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["dimension"],
+            },
+        },
+        {
+            name: "get_time_pattern_stats",
+            description: "Analyses reservation patterns by time — day of week, hour of day, or a combined heatmap. Use this for questions about busy periods, peak times, when no-shows are highest, or operational planning.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    dimension: {
+                        type: "string",
+                        enum: ["day_of_week", "hour_of_day", "day_and_hour", "party_size_anomaly"],
+                        description: "day_of_week: covers, revenue, no-show rate per day. hour_of_day: same by hour. day_and_hour: full heatmap grid (day × hour). party_size_anomaly: weekly avg covers and % large party (7+) with z-scores — flags weeks that are statistical outliers, useful for detecting event-driven spikes.",
+                    },
+                    date_from: { type: "string", description: "Optional start date filter (ISO 8601)." },
+                    date_to: { type: "string", description: "Optional end date filter (ISO 8601)." },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["dimension"],
+            },
+        },
+        {
+            name: "get_guest_behaviour_stats",
+            description: "Analyses guest behaviour patterns. Use this for questions about cross-venue visits, visit frequency, return rates, and loyalty tier breakdowns for single vs multi-venue guests. All analysis is based on guest_global_id. Dimensions: venue_spread (how many distinct venues each guest visits), visit_frequency (distribution of how many times guests dine), return_rate (what share of guests come back), cross_venue_loyalty (loyalty tier split between single and multi-venue guests).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    dimension: {
+                        type: "string",
+                        enum: ["venue_spread", "visit_frequency", "return_rate", "cross_venue_loyalty", "loyalty_movement_by_venue", "ftd_conversion", "guest_lifetime_value", "churn_risk"],
+                        description: "venue_spread: distinct venues per guest. visit_frequency: visit count buckets. return_rate: overall return rate summary. cross_venue_loyalty: loyalty tier split by single/multi-venue. loyalty_movement_by_venue: which restaurants see the most tier progression. ftd_conversion: what % of first-timers came back and how fast. guest_lifetime_value: revenue buckets across guests. churn_risk: loyal guests who haven't returned in 60/90/180+ days.",
+                    },
+                    date_from: {
+                        type: "string",
+                        description: "Optional start date filter (ISO 8601, e.g. 2024-01-01).",
+                    },
+                    date_to: {
+                        type: "string",
+                        description: "Optional end date filter (ISO 8601, e.g. 2024-12-31).",
+                    },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["dimension"],
+            },
+        },
+        {
+            name: "get_date_stats",
+            description: "Returns reservation counts, covers, and revenue aggregated by a time period (day, week, month, quarter, year). Optionally broken down by a second dimension. Use this for any time-series or trend questions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    period: {
+                        type: "string",
+                        enum: ["day", "week", "month", "quarter", "year"],
+                        description: "Time bucket to group by.",
+                    },
+                    group_by: {
+                        type: "string",
+                        enum: ["outcome", "restaurant_name", "origin", "guest_loyalty_level_at_time", "covers", "currency_code", "service_period"],
+                        description: "Optional second dimension to break results down further. service_period groups by Breakfast/Lunch/Dinner inferred from reservation time — useful for cross-referencing against forecast by service.",
+                    },
+                    date_from: {
+                        type: "string",
+                        description: "Optional start date filter (ISO 8601, e.g. 2024-01-01).",
+                    },
+                    date_to: {
+                        type: "string",
+                        description: "Optional end date filter (ISO 8601, e.g. 2024-12-31).",
+                    },
+                    restaurant_name: {
+                        type: "string",
+                        description: "Optional. Filter results to a specific restaurant. Useful when cross-referencing reservation actuals against forecast for a single venue.",
+                    },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["period"],
+            },
+        },
+        {
+            name: "get_demand_outlook",
+            description: "Queries the data_restaurant_demand_master table to analyse forward-looking demand. Use this for questions about upcoming reservation demand, booking pace (how far in advance guests book), party size distribution in the outlook period, or which restaurants have the highest expected demand. Always uses the latest snapshot by default.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    dimension: {
+                        type: "string",
+                        enum: ["by_date", "by_restaurant", "by_party_size", "booking_pace", "pace_by_date", "by_date_restaurant", "pace_snapshot"],
+                        description: "pace_snapshot: USE THIS FIRST for any demand outlook or booking pace question. Returns one row per restaurant × future date with: days_out_today, cum_demand_today, baseline_median (same-DOW historical median at the same days_out), pct_vs_baseline, flag (Well ahead/Ahead/On track/Behind/Well behind), party mix % by band (mix_small_pct/mix_standard_pct/mix_medium_pct/mix_large_pct/mix_event_pct), and mix_shift_flag highlighting the biggest mix shift vs baseline if >10pp. One call replaces 36+ multi-call pace patterns. by_date: total demand per upcoming date (all restaurants combined). by_restaurant: demand ranked by restaurant for the outlook period. by_party_size: demand distribution across party sizes. booking_pace: booking curve aggregated across all dates. pace_by_date: booking curve per restaurant × date × days_out — all restaurants included unless restaurant_name filter applied. by_date_restaurant: per-date per-restaurant demand from the latest snapshot.",
+                    },
+                    snapshot_date: {
+                        type: "string",
+                        description: "Optional. ISO date (YYYY-MM-DD) of a specific snapshot to use. Defaults to the latest available snapshot. Not applicable for booking_pace (which uses all snapshots).",
+                    },
+                    restaurant_name: {
+                        type: "string",
+                        description: "Optional. Filter to a specific restaurant.",
+                    },
+                    date_from: {
+                        type: "string",
+                        description: "Optional. Filter on the demand date (the_date) — start of range (ISO 8601).",
+                    },
+                    date_to: {
+                        type: "string",
+                        description: "Optional. Filter on the demand date (the_date) — end of range (ISO 8601).",
+                    },
+                    party_size: {
+                        type: "string",
+                        description: "Optional. Filter to a specific party size (integer as string). Most useful with booking_pace.",
+                    },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["dimension"],
+            },
+        },
+        {
+            name: "get_loyalty_breakdown",
+            description: "Returns loyalty level distribution across all reservations. Shows total reservations, outcome breakdown (Done, NoShow, Cancelled for past; Confirmed, NotConfirmed for future), and revenue stats per loyalty level, plus a breakdown of booking origin by loyalty level.",
+            inputSchema: {
+                type: "object",
+                properties: { ...TENANT_PARAM },
+                required: [],
+            },
+        },
+        {
+            name: "get_review_stats",
+            description: "Queries the data_review_master table for guest review analytics. Use for questions about ratings, review trends, platform performance, sub-dimension scores (food/service/ambience/value), and recent negative feedback. Covers all review platforms (Google, TripAdvisor, OpenTable, etc.).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    dimension: {
+                        type: "string",
+                        enum: ["by_restaurant", "by_category", "by_source", "by_period", "rating_distribution", "sub_ratings", "recent_low", "recent_all", "trend"],
+                        description: "by_restaurant: avg overall + sub-ratings, review count, positive/negative split per restaurant. Use sort_by to rank by a specific dimension. " +
+                            "by_category: same metrics rolled up by restaurant_category — use to compare brand tiers without listing every venue. " +
+                            "by_source: metrics broken down by review platform (Google, TripAdvisor, OpenTable, etc.). " +
+                            "by_period: rating trend over time — requires period param. " +
+                            "rating_distribution: star band breakdown (1★–5★) per restaurant. " +
+                            "sub_ratings: food/service/ambience/value side-by-side per restaurant with weakest dimension flag. " +
+                            "recent_low: last 90 days of reviews rated below 3 (configurable via max_rating) with text excerpt — for operational alerts, up to 200 rows. " +
+                            "recent_all: last 90 days of all reviews with text excerpt — use for word clouds and broad sentiment analysis; filter with min_rating/max_rating, up to 500 rows. " +
+                            "trend: weekly (or monthly) ratings per restaurant across the last N periods — use to spot improving or declining sites in a single call. Control granularity with period (default week) and lookback with weeks param (default 4).",
+                    },
+                    period: {
+                        type: "string",
+                        enum: ["week", "month", "quarter", "year"],
+                        description: "Required for by_period. Controls granularity for trend (default: week).",
+                    },
+                    sort_by: {
+                        type: "string",
+                        enum: ["overall", "food", "service", "ambience", "value", "reviews"],
+                        description: "Optional. For by_restaurant: sort results by this dimension descending. Default: overall rating.",
+                    },
+                    weeks: {
+                        type: "string",
+                        description: "Optional. For trend: number of periods to look back (default 4, max 52). E.g. '6' returns the last 6 weeks.",
+                    },
+                    restaurant_name: {
+                        type: "string",
+                        description: "Optional. Filter to a specific restaurant.",
+                    },
+                    restaurant_category: {
+                        type: "string",
+                        description: "Optional. Filter to a restaurant category (e.g. 'Fine Dining', 'Casual'). Useful for querying all venues of the same brand tier in one call.",
+                    },
+                    source: {
+                        type: "string",
+                        description: "Optional. Filter to a specific review platform (e.g. 'Google', 'TripAdvisor', 'OpenTable').",
+                    },
+                    date_from: {
+                        type: "string",
+                        description: "Optional. Filter reviews on or after this date (ISO 8601).",
+                    },
+                    date_to: {
+                        type: "string",
+                        description: "Optional. Filter reviews on or before this date (ISO 8601).",
+                    },
+                    min_rating: {
+                        type: "string",
+                        description: "Optional. Only include reviews at or above this rating (e.g. '4' for positive reviews only). Most useful with recent_all.",
+                    },
+                    max_rating: {
+                        type: "string",
+                        description: "Optional. Only include reviews at or below this rating (e.g. '2' for very negative only). Overrides the default < 3 threshold in recent_low.",
+                    },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["dimension"],
+            },
+        },
+        {
+            name: "get_forecast_stats",
+            description: "Queries the data_forecast_master table to analyse cover forecasts. Use this for questions about forecasted covers, no-show forecasts, walk-in forecasts, cancellation forecasts, and comparing how forecasts change between snapshot dates. Each snapshot represents a daily forecast of future service dates.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    dimension: {
+                        type: "string",
+                        enum: ["by_date", "by_day_of_week", "by_restaurant", "by_restaurant_day_of_week", "by_service", "by_date_restaurant", "snapshot_comparison"],
+                        description: "by_date: aggregated forecast by service_date — total covers by category per date. Defaults to next 90 days; use service_date_from/service_date_to to change the window. " +
+                            "by_day_of_week: average covers per day of week (Mon–Sun) across ALL restaurants — use to identify which day is strongest/weakest portfolio-wide. Defaults to next 90 days. Results ordered by avg_total_completed_covers desc. " +
+                            "by_restaurant: forecast totals per restaurant across the full date range — always returns one row per restaurant, no date windowing needed. " +
+                            "by_restaurant_day_of_week: average covers per day of week broken down BY restaurant — USE THIS for staffing questions or comparing peak days across venues. Returns restaurant × weekday rows ordered by restaurant then avg covers desc. Defaults to next 90 days. " +
+                            "by_service: forecast breakdown by service period (Breakfast, Lunch, Dinner) — always aggregated across full range, no date windowing needed. " +
+                            "by_date_restaurant: detailed per-date, per-restaurant, per-service rows. REQUIRES at least one of: restaurant_name, service_date_from, service_date_to. Defaults to next 14 days for the date window. " +
+                            "snapshot_comparison: compare two snapshot dates to see how the forecast has changed — requires both snapshot_date and snapshot_date_2.",
+                    },
+                    snapshot_date: {
+                        type: "string",
+                        description: "Optional. ISO date (YYYY-MM-DD) of a specific snapshot to use. Defaults to the latest available snapshot. Required for snapshot_comparison.",
+                    },
+                    snapshot_date_2: {
+                        type: "string",
+                        description: "Optional. ISO date (YYYY-MM-DD) of the second snapshot for snapshot_comparison dimension only.",
+                    },
+                    restaurant_name: {
+                        type: "string",
+                        description: "Optional. Filter to a specific restaurant.",
+                    },
+                    service_date_from: {
+                        type: "string",
+                        description: "Optional. Filter on the service date — start of range (ISO 8601).",
+                    },
+                    service_date_to: {
+                        type: "string",
+                        description: "Optional. Filter on the service date — end of range (ISO 8601).",
+                    },
+                    service: {
+                        type: "string",
+                        description: "Optional. Filter to a specific service period (e.g. 'breakfast', 'lunch', 'dinner').",
+                    },
+                    ...TENANT_PARAM,
+                    ...PROMPT_PARAM,
+                },
+                required: ["dimension"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const a = (args ?? {});
+    // Pass tool name + optional user prompt to API for query logging
+    (0, api_js_1.setMcpContext)(name, a._user_prompt);
+    try {
+        switch (name) {
+            case "get_schema": {
+                const schema = await (0, tools_js_1.getSchema)();
+                return { content: [{ type: "text", text: schema }] };
+            }
+            case "query_reservations": {
+                if (!a.where_clause) {
+                    return {
+                        content: [{ type: "text", text: "Error: where_clause is required." }],
+                        isError: true,
+                    };
+                }
+                const rows = await (0, tools_js_1.queryReservations)(a.where_clause, a.tenant_code);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: rows.length === 0
+                                ? "No rows matched the given WHERE clause."
+                                : JSON.stringify(rows, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_summary_stats": {
+                if (!a.group_by_field) {
+                    return {
+                        content: [{ type: "text", text: "Error: group_by_field is required." }],
+                        isError: true,
+                    };
+                }
+                const stats = await (0, tools_js_1.getSummaryStats)(a.group_by_field, a.tenant_code);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(stats, null, 2) }],
+                };
+            }
+            case "get_guest_behaviour_stats": {
+                if (!a.dimension) {
+                    return {
+                        content: [{ type: "text", text: "Error: dimension is required." }],
+                        isError: true,
+                    };
+                }
+                const data = await (0, tools_js_1.getGuestBehaviour)(a.dimension, a.date_from, a.date_to, a.tenant_code);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            case "get_revenue_stats": {
+                if (!a.dimension) {
+                    return { content: [{ type: "text", text: "Error: dimension is required." }], isError: true };
+                }
+                const data = await (0, tools_js_1.getRevenueStats)(a.dimension, a.period, a.date_from, a.date_to, a.tenant_code);
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            case "get_time_pattern_stats": {
+                if (!a.dimension) {
+                    return { content: [{ type: "text", text: "Error: dimension is required." }], isError: true };
+                }
+                const data = await (0, tools_js_1.getTimePatternStats)(a.dimension, a.date_from, a.date_to, a.tenant_code);
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            case "get_date_stats": {
+                if (!a.period) {
+                    return {
+                        content: [{ type: "text", text: "Error: period is required." }],
+                        isError: true,
+                    };
+                }
+                const stats = await (0, tools_js_1.getDateStats)(a.period, a.group_by, a.date_from, a.date_to, a.tenant_code, a.restaurant_name);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(stats, null, 2) }],
+                };
+            }
+            case "get_demand_outlook": {
+                if (!a.dimension) {
+                    return { content: [{ type: "text", text: "Error: dimension is required." }], isError: true };
+                }
+                const data = await (0, tools_js_1.getDemandOutlook)(a.dimension, a.snapshot_date, a.restaurant_name, a.date_from, a.date_to, a.party_size, a.tenant_code);
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            case "get_loyalty_breakdown": {
+                const breakdown = await (0, tools_js_1.getLoyaltyBreakdown)(a.tenant_code);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(breakdown, null, 2) }],
+                };
+            }
+            case "get_review_stats": {
+                if (!a.dimension) {
+                    return { content: [{ type: "text", text: "Error: dimension is required." }], isError: true };
+                }
+                const data = await (0, tools_js_1.getReviewStats)(a.dimension, a.restaurant_name, a.restaurant_category, a.source, a.date_from, a.date_to, a.period, a.min_rating, a.max_rating, a.sort_by, a.weeks, a.tenant_code);
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            case "get_forecast_stats": {
+                if (!a.dimension) {
+                    return { content: [{ type: "text", text: "Error: dimension is required." }], isError: true };
+                }
+                const data = await (0, tools_js_1.getForecastStats)(a.dimension, a.snapshot_date, a.restaurant_name, a.service_date_from, a.service_date_to, a.service, a.snapshot_date_2, a.tenant_code);
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            default:
+                return {
+                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                    isError: true,
+                };
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    await (0, api_js_1.testConnection)();
+    console.error("API connection established.");
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio.");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+process.on("SIGINT", () => process.exit(0));

package/dist/safety.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateWhereClause = validateWhereClause;
+exports.validateGroupByField = validateGroupByField;
+const BLOCKED_KEYWORDS = /\b(INSERT|UPDATE|DELETE|DROP|TRUNCATE|ALTER|CREATE|GRANT|REVOKE|EXEC|EXECUTE|CALL)\b/i;
+const BLOCKED_CHARS = /;/;
+function validateWhereClause(clause) {
+    if (BLOCKED_KEYWORDS.test(clause)) {
+        return { ok: false, reason: "WHERE clause contains a disallowed keyword (only read operations are permitted)." };
+    }
+    if (BLOCKED_CHARS.test(clause)) {
+        return { ok: false, reason: "WHERE clause must not contain semicolons." };
+    }
+    return { ok: true };
+}
+function validateGroupByField(field) {
+    // Only allow simple column name identifiers (letters, numbers, underscores)
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
+        return { ok: false, reason: `Invalid field name: "${field}". Only alphanumeric characters and underscores are allowed.` };
+    }
+    return { ok: true };
+}

package/dist/tools.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSchema = getSchema;
+exports.queryReservations = queryReservations;
+exports.getSummaryStats = getSummaryStats;
+exports.getLoyaltyBreakdown = getLoyaltyBreakdown;
+exports.getGuestBehaviour = getGuestBehaviour;
+exports.getRevenueStats = getRevenueStats;
+exports.getTimePatternStats = getTimePatternStats;
+exports.getDemandOutlook = getDemandOutlook;
+exports.getReviewStats = getReviewStats;
+exports.getForecastStats = getForecastStats;
+exports.getDateStats = getDateStats;
+const safety_js_1 = require("./safety.js");
+const api_js_1 = require("./api.js");
+async function getSchema() {
+    const { schema } = await (0, api_js_1.apiGetSchema)();
+    return schema;
+}
+async function queryReservations(whereClause, tenantCode) {
+    const check = (0, safety_js_1.validateWhereClause)(whereClause);
+    if (!check.ok) {
+        throw new Error(`Query blocked: ${check.reason}`);
+    }
+    const { rows } = await (0, api_js_1.apiQueryReservations)(whereClause, tenantCode);
+    return rows;
+}
+async function getSummaryStats(groupByField, tenantCode) {
+    const check = (0, safety_js_1.validateGroupByField)(groupByField);
+    if (!check.ok) {
+        throw new Error(`Invalid group-by field: ${check.reason}`);
+    }
+    const { stats } = await (0, api_js_1.apiGetSummaryStats)(groupByField, tenantCode);
+    return stats;
+}
+async function getLoyaltyBreakdown(tenantCode) {
+    return (0, api_js_1.apiGetLoyaltyBreakdown)(tenantCode);
+}
+async function getGuestBehaviour(dimension, dateFrom, dateTo, tenantCode) {
+    const { data } = await (0, api_js_1.apiGetGuestBehaviour)(dimension, dateFrom, dateTo, tenantCode);
+    return data;
+}
+async function getRevenueStats(dimension, period, dateFrom, dateTo, tenantCode) {
+    const { data } = await (0, api_js_1.apiGetRevenueStats)(dimension, period, dateFrom, dateTo, tenantCode);
+    return data;
+}
+async function getTimePatternStats(dimension, dateFrom, dateTo, tenantCode) {
+    const { data } = await (0, api_js_1.apiGetTimePatternStats)(dimension, dateFrom, dateTo, tenantCode);
+    return data;
+}
+async function getDemandOutlook(dimension, snapshotDate, restaurantName, dateFrom, dateTo, partySize, tenantCode) {
+    const { data } = await (0, api_js_1.apiGetDemandOutlook)(dimension, snapshotDate, restaurantName, dateFrom, dateTo, partySize, tenantCode);
+    return data;
+}
+async function getReviewStats(dimension, restaurantName, restaurantCategory, source, dateFrom, dateTo, period, minRating, maxRating, sortBy, weeks, tenantCode) {
+    const { data } = await (0, api_js_1.apiGetReviewStats)(dimension, restaurantName, restaurantCategory, source, dateFrom, dateTo, period, minRating, maxRating, sortBy, weeks, tenantCode);
+    return data;
+}
+async function getForecastStats(dimension, snapshotDate, restaurantName, serviceDateFrom, serviceDateTo, service, snapshotDate2, tenantCode) {
+    const { data } = await (0, api_js_1.apiGetForecastStats)(dimension, snapshotDate, restaurantName, serviceDateFrom, serviceDateTo, service, snapshotDate2, tenantCode);
+    return data;
+}
+async function getDateStats(period, groupBy, dateFrom, dateTo, tenantCode, restaurantName) {
+    const { stats } = await (0, api_js_1.apiGetDateStats)(period, groupBy, dateFrom, dateTo, tenantCode, restaurantName);
+    return stats;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "distil-ai-rms-reporting",
+  "version": "1.0.0",
+  "description": "MCP server for restaurant management system reporting and analytics",
+  "main": "dist/index.js",
+  "bin": {
+    "distil-ai-rms-reporting": "dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "restaurant",
+    "analytics",
+    "reporting",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.3"
+  }
+}