@anyshift/mcp-proxy 0.3.6 → 0.4.0

package/dist/timeseries/algorithms/rolling-quantile.js

@@ -0,0 +1,78 @@
+/**
+ * Rolling Quantile based anomaly detection (similar to Datadog's Basic algorithm)
+ *
+ * Uses a sliding window to compute rolling percentiles, then flags points
+ * outside the expected range. This is non-parametric and works well for
+ * any distribution without assuming normality.
+ */
+import { rollingQuantiles } from './stats.js';
+const DEFAULT_LOWER_QUANTILE = 0.05;
+const DEFAULT_UPPER_QUANTILE = 0.95;
+/**
+ * Detect anomalies using Rolling Quantile method
+ *
+ * @param data - Array of data points (should be in time order)
+ * @param params - Rolling Quantile parameters
+ * @returns Array of detected anomalies
+ */
+export function detectRollingQuantileAnomalies(data, params) {
+    const { window_size: windowSize, lower_quantile: lowerQuantile = DEFAULT_LOWER_QUANTILE, upper_quantile: upperQuantile = DEFAULT_UPPER_QUANTILE, } = params;
+    if (windowSize <= 0) {
+        throw new Error('window_size must be greater than 0');
+    }
+    if (windowSize > data.length) {
+        throw new Error(`window_size (${windowSize}) cannot be larger than data length (${data.length})`);
+    }
+    if (lowerQuantile < 0 || lowerQuantile > 1) {
+        throw new Error('lower_quantile must be between 0 and 1');
+    }
+    if (upperQuantile < 0 || upperQuantile > 1) {
+        throw new Error('upper_quantile must be between 0 and 1');
+    }
+    if (lowerQuantile >= upperQuantile) {
+        throw new Error('lower_quantile must be less than upper_quantile');
+    }
+    const values = data.map((d) => d.value);
+    const { lower, upper } = rollingQuantiles(values, windowSize, lowerQuantile, upperQuantile);
+    const anomalies = [];
+    for (let i = 0; i < data.length; i++) {
+        // Skip points where we don't have enough data for the window
+        if (isNaN(lower[i]) || isNaN(upper[i])) {
+            continue;
+        }
+        const point = data[i];
+        const lowerBound = lower[i];
+        const upperBound = upper[i];
+        if (point.value < lowerBound) {
+            anomalies.push({
+                index: point.index,
+                timestamp: point.timestamp,
+                value: point.value,
+                reason: `Value ${point.value.toFixed(2)} below rolling ${(lowerQuantile * 100).toFixed(0)}th percentile ${lowerBound.toFixed(2)}`,
+                metadata: {
+                    lower_bound: lowerBound,
+                    upper_bound: upperBound,
+                    lower_quantile: lowerQuantile,
+                    upper_quantile: upperQuantile,
+                    window_size: windowSize,
+                },
+            });
+        }
+        else if (point.value > upperBound) {
+            anomalies.push({
+                index: point.index,
+                timestamp: point.timestamp,
+                value: point.value,
+                reason: `Value ${point.value.toFixed(2)} above rolling ${(upperQuantile * 100).toFixed(0)}th percentile ${upperBound.toFixed(2)}`,
+                metadata: {
+                    lower_bound: lowerBound,
+                    upper_bound: upperBound,
+                    lower_quantile: lowerQuantile,
+                    upper_quantile: upperQuantile,
+                    window_size: windowSize,
+                },
+            });
+        }
+    }
+    return anomalies;
+}

package/dist/timeseries/algorithms/stats.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Statistical utility functions for anomaly detection
+ * Implemented in pure TypeScript for zero dependencies and fast execution
+ */
+/**
+ * Calculate the mean (average) of an array of numbers
+ */
+export declare function mean(values: number[]): number;
+/**
+ * Calculate the median of an array of numbers
+ */
+export declare function median(values: number[]): number;
+/**
+ * Calculate the standard deviation of an array of numbers
+ */
+export declare function standardDeviation(values: number[]): number;
+/**
+ * Calculate the Median Absolute Deviation (MAD)
+ * MAD = median(|Xi - median(X)|)
+ */
+export declare function medianAbsoluteDeviation(values: number[]): number;
+/**
+ * Calculate modified Z-score using MAD
+ * Modified Z-score = 0.6745 * (Xi - median) / MAD
+ * The constant 0.6745 makes it comparable to standard Z-scores for normal distributions
+ */
+export declare function modifiedZScore(value: number, med: number, mad: number): number;
+/**
+ * Calculate a simple moving average for an array at each position
+ * Returns an array of the same length, with NaN for positions where window is incomplete
+ */
+export declare function movingAverage(values: number[], windowSize: number): number[];
+/**
+ * Calculate the standard deviation of a moving window at each position
+ */
+export declare function movingStandardDeviation(values: number[], windowSize: number): number[];
+/**
+ * Calculate a specific quantile (percentile) of an array
+ * Uses linear interpolation between closest ranks
+ */
+export declare function quantile(values: number[], q: number): number;
+/**
+ * Calculate rolling quantiles (lower and upper bounds) at each position
+ * Returns arrays of the same length as input, with NaN for positions where window is incomplete
+ */
+export declare function rollingQuantiles(values: number[], windowSize: number, lowerQuantile: number, upperQuantile: number): {
+    lower: number[];
+    upper: number[];
+};

package/dist/timeseries/algorithms/stats.js

@@ -0,0 +1,139 @@
+/**
+ * Statistical utility functions for anomaly detection
+ * Implemented in pure TypeScript for zero dependencies and fast execution
+ */
+/**
+ * Calculate the mean (average) of an array of numbers
+ */
+export function mean(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+/**
+ * Calculate the median of an array of numbers
+ */
+export function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 !== 0
+        ? sorted[mid]
+        : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/**
+ * Calculate the standard deviation of an array of numbers
+ */
+export function standardDeviation(values) {
+    if (values.length < 2)
+        return 0;
+    const avg = mean(values);
+    const squaredDiffs = values.map((v) => Math.pow(v - avg, 2));
+    return Math.sqrt(mean(squaredDiffs));
+}
+/**
+ * Calculate the Median Absolute Deviation (MAD)
+ * MAD = median(|Xi - median(X)|)
+ */
+export function medianAbsoluteDeviation(values) {
+    if (values.length === 0)
+        return 0;
+    const med = median(values);
+    const absoluteDeviations = values.map((v) => Math.abs(v - med));
+    return median(absoluteDeviations);
+}
+/**
+ * Calculate modified Z-score using MAD
+ * Modified Z-score = 0.6745 * (Xi - median) / MAD
+ * The constant 0.6745 makes it comparable to standard Z-scores for normal distributions
+ */
+export function modifiedZScore(value, med, mad) {
+    if (mad === 0)
+        return 0;
+    return (0.6745 * (value - med)) / mad;
+}
+/**
+ * Calculate a simple moving average for an array at each position
+ * Returns an array of the same length, with NaN for positions where window is incomplete
+ */
+export function movingAverage(values, windowSize) {
+    if (windowSize <= 0 || values.length === 0)
+        return [];
+    const result = [];
+    for (let i = 0; i < values.length; i++) {
+        if (i < windowSize - 1) {
+            // Not enough data points yet
+            result.push(NaN);
+        }
+        else {
+            // Calculate average of the window
+            const window = values.slice(i - windowSize + 1, i + 1);
+            result.push(mean(window));
+        }
+    }
+    return result;
+}
+/**
+ * Calculate the standard deviation of a moving window at each position
+ */
+export function movingStandardDeviation(values, windowSize) {
+    if (windowSize <= 0 || values.length === 0)
+        return [];
+    const result = [];
+    for (let i = 0; i < values.length; i++) {
+        if (i < windowSize - 1) {
+            result.push(NaN);
+        }
+        else {
+            const window = values.slice(i - windowSize + 1, i + 1);
+            result.push(standardDeviation(window));
+        }
+    }
+    return result;
+}
+/**
+ * Calculate a specific quantile (percentile) of an array
+ * Uses linear interpolation between closest ranks
+ */
+export function quantile(values, q) {
+    if (values.length === 0)
+        return 0;
+    if (q <= 0)
+        return Math.min(...values);
+    if (q >= 1)
+        return Math.max(...values);
+    const sorted = [...values].sort((a, b) => a - b);
+    const pos = (sorted.length - 1) * q;
+    const lower = Math.floor(pos);
+    const upper = Math.ceil(pos);
+    const weight = pos - lower;
+    if (upper >= sorted.length)
+        return sorted[sorted.length - 1];
+    return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+}
+/**
+ * Calculate rolling quantiles (lower and upper bounds) at each position
+ * Returns arrays of the same length as input, with NaN for positions where window is incomplete
+ */
+export function rollingQuantiles(values, windowSize, lowerQuantile, upperQuantile) {
+    if (windowSize <= 0 || values.length === 0) {
+        return { lower: [], upper: [] };
+    }
+    const lower = [];
+    const upper = [];
+    for (let i = 0; i < values.length; i++) {
+        if (i < windowSize - 1) {
+            // Not enough data points yet
+            lower.push(NaN);
+            upper.push(NaN);
+        }
+        else {
+            // Calculate quantiles of the window
+            const window = values.slice(i - windowSize + 1, i + 1);
+            lower.push(quantile(window, lowerQuantile));
+            upper.push(quantile(window, upperQuantile));
+        }
+    }
+    return { lower, upper };
+}

package/dist/timeseries/algorithms/threshold.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Threshold-based anomaly detection
+ *
+ * Detects points that cross one or more named thresholds.
+ * Supports multiple thresholds with names and directions (upper/lower).
+ */
+import type { DataPoint, Anomaly, ThresholdParams } from '../types.js';
+/**
+ * Detect anomalies using threshold method
+ *
+ * @param data - Array of data points
+ * @param params - Threshold parameters with named thresholds
+ * @returns Array of detected anomalies
+ */
+export declare function detectThresholdAnomalies(data: DataPoint[], params: ThresholdParams): Anomaly[];

package/dist/timeseries/algorithms/threshold.js

@@ -0,0 +1,49 @@
+/**
+ * Threshold-based anomaly detection
+ *
+ * Detects points that cross one or more named thresholds.
+ * Supports multiple thresholds with names and directions (upper/lower).
+ */
+/**
+ * Detect anomalies using threshold method
+ *
+ * @param data - Array of data points
+ * @param params - Threshold parameters with named thresholds
+ * @returns Array of detected anomalies
+ */
+export function detectThresholdAnomalies(data, params) {
+    const { thresholds } = params;
+    if (!thresholds || thresholds.length === 0) {
+        throw new Error('At least one threshold must be specified');
+    }
+    const anomalies = [];
+    for (const point of data) {
+        const crossedThresholds = [];
+        for (const threshold of thresholds) {
+            if (threshold.direction === 'upper' && point.value > threshold.value) {
+                crossedThresholds.push(threshold);
+            }
+            else if (threshold.direction === 'lower' && point.value < threshold.value) {
+                crossedThresholds.push(threshold);
+            }
+        }
+        if (crossedThresholds.length > 0) {
+            const thresholdNames = crossedThresholds.map((t) => t.name);
+            const thresholdDetails = crossedThresholds
+                .map((t) => `${t.name} (${t.direction}: ${t.value})`)
+                .join(', ');
+            anomalies.push({
+                index: point.index,
+                timestamp: point.timestamp,
+                value: point.value,
+                reason: `Value ${point.value} crossed threshold(s): ${thresholdDetails}`,
+                crossed_thresholds: thresholdNames,
+                metadata: crossedThresholds.reduce((acc, t) => {
+                    acc[`threshold_${t.name}`] = t.value;
+                    return acc;
+                }, {}),
+            });
+        }
+    }
+    return anomalies;
+}

package/dist/timeseries/handler.d.ts

@@ -0,0 +1,10 @@
+import type { TimeseriesConfig, DetectionType, DetectionParams } from './types.js';
+/**
+ * Main handler for time series anomaly detection
+ */
+export declare function detectTimeseriesAnomalies(config: TimeseriesConfig, filePath: string, jqQuery: string, valueField: string, detectionType: DetectionType, detectionParams?: DetectionParams, timestampField?: string): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;

package/dist/timeseries/handler.js

@@ -0,0 +1,292 @@
+import { existsSync } from 'fs';
+import path from 'path';
+import { validatePathWithinAllowedDirs } from '../utils/pathValidation.js';
+import { validateJqQuery, runJqParsed } from '../utils/jq.js';
+import { detectMadAnomalies, detectMovingAverageAnomalies, detectThresholdAnomalies, detectRollingQuantileAnomalies, } from './algorithms/index.js';
+// Default timeout for jq execution
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Convert a timestamp to UTC time string
+ * Handles Unix timestamps (seconds or milliseconds) and ISO strings
+ */
+function toUtcTime(timestamp) {
+    if (timestamp === undefined || timestamp === null) {
+        return undefined;
+    }
+    let date;
+    if (typeof timestamp === 'number') {
+        // Detect if timestamp is in seconds or milliseconds
+        // Unix timestamps in seconds are typically 10 digits (until 2286)
+        // Milliseconds are 13 digits
+        if (timestamp > 1e12) {
+            // Likely milliseconds
+            date = new Date(timestamp);
+        }
+        else {
+            // Likely seconds
+            date = new Date(timestamp * 1000);
+        }
+    }
+    else if (typeof timestamp === 'string') {
+        // Try parsing as number first (string representation of Unix timestamp)
+        const numericTimestamp = Number(timestamp);
+        if (!isNaN(numericTimestamp)) {
+            if (numericTimestamp > 1e12) {
+                date = new Date(numericTimestamp);
+            }
+            else {
+                date = new Date(numericTimestamp * 1000);
+            }
+        }
+        else {
+            // Try parsing as ISO string or other date format
+            date = new Date(timestamp);
+        }
+    }
+    else {
+        return undefined;
+    }
+    // Check if date is valid
+    if (isNaN(date.getTime())) {
+        return undefined;
+    }
+    return date.toISOString();
+}
+/**
+ * Pool consecutive anomalies together to reduce output size
+ * Anomalies are considered consecutive if their indices differ by 1
+ */
+function poolAnomalies(anomalies) {
+    if (anomalies.length === 0) {
+        return [];
+    }
+    // Sort anomalies by index to ensure proper grouping
+    const sorted = [...anomalies].sort((a, b) => a.index - b.index);
+    const pools = [];
+    let currentPool = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        const current = sorted[i];
+        const previous = sorted[i - 1];
+        // Check if consecutive (index differs by 1)
+        if (current.index === previous.index + 1) {
+            currentPool.push(current);
+        }
+        else {
+            // Finalize current pool and start new one
+            pools.push(createPooledAnomaly(currentPool));
+            currentPool = [current];
+        }
+    }
+    // Don't forget the last pool
+    pools.push(createPooledAnomaly(currentPool));
+    return pools;
+}
+/**
+ * Create a PooledAnomaly from a group of consecutive Anomaly objects
+ */
+function createPooledAnomaly(anomalies) {
+    const first = anomalies[0];
+    const last = anomalies[anomalies.length - 1];
+    const values = anomalies.map((a) => a.value);
+    const minValue = Math.min(...values);
+    const maxValue = Math.max(...values);
+    const avgValue = values.reduce((sum, v) => sum + v, 0) / values.length;
+    // Collect all crossed thresholds (union)
+    const allThresholds = new Set();
+    for (const a of anomalies) {
+        if (a.crossed_thresholds) {
+            for (const t of a.crossed_thresholds) {
+                allThresholds.add(t);
+            }
+        }
+    }
+    // Generate summary reason
+    let reason;
+    if (anomalies.length === 1) {
+        reason = first.reason;
+    }
+    else {
+        // Extract the core reason pattern from the first anomaly
+        const baseReason = first.reason;
+        if (allThresholds.size > 0) {
+            reason = `${anomalies.length} consecutive points crossing threshold(s): ${Array.from(allThresholds).join(', ')}`;
+        }
+        else if (baseReason.includes('percentile')) {
+            reason = `${anomalies.length} consecutive points outside rolling quantile bounds`;
+        }
+        else if (baseReason.includes('Modified Z-score')) {
+            reason = `${anomalies.length} consecutive points with high MAD deviation`;
+        }
+        else if (baseReason.includes('moving average')) {
+            reason = `${anomalies.length} consecutive points deviating from moving average`;
+        }
+        else {
+            reason = `${anomalies.length} consecutive anomalous points`;
+        }
+    }
+    const pooled = {
+        start_index: first.index,
+        end_index: last.index,
+        count: anomalies.length,
+        min_value: minValue,
+        max_value: maxValue,
+        avg_value: Math.round(avgValue * 100) / 100, // Round to 2 decimal places
+        reason,
+    };
+    // Add timestamps if available
+    if (first.timestamp !== undefined) {
+        pooled.start_timestamp = first.timestamp;
+        const startUtc = toUtcTime(first.timestamp);
+        if (startUtc) {
+            pooled.start_utc = startUtc;
+        }
+    }
+    if (last.timestamp !== undefined) {
+        pooled.end_timestamp = last.timestamp;
+        const endUtc = toUtcTime(last.timestamp);
+        if (endUtc) {
+            pooled.end_utc = endUtc;
+        }
+    }
+    // Add crossed thresholds if any
+    if (allThresholds.size > 0) {
+        pooled.crossed_thresholds = Array.from(allThresholds);
+    }
+    return pooled;
+}
+/**
+ * Validate that the jq output is tabular (array of objects)
+ */
+function validateTabularData(data) {
+    if (!Array.isArray(data)) {
+        throw new Error(`jq query must return an array, but got ${typeof data}. ` +
+            'Wrap your query in brackets if needed: [.[] | ...]');
+    }
+    if (data.length === 0) {
+        throw new Error('jq query returned an empty array. No data to analyze.');
+    }
+    // Check first few items are objects
+    const sampleSize = Math.min(5, data.length);
+    for (let i = 0; i < sampleSize; i++) {
+        if (typeof data[i] !== 'object' || data[i] === null || Array.isArray(data[i])) {
+            throw new Error(`jq query must return an array of objects, but item ${i} is ${typeof data[i]}. ` +
+                'Each item should be an object with fields.');
+        }
+    }
+}
+/**
+ * Extract data points from tabular data
+ */
+function extractDataPoints(data, valueField, timestampField) {
+    const points = [];
+    for (let i = 0; i < data.length; i++) {
+        const item = data[i];
+        const rawValue = item[valueField];
+        // Skip items without the value field or with null values
+        if (rawValue === undefined || rawValue === null) {
+            continue;
+        }
+        // Convert to number
+        const value = Number(rawValue);
+        if (isNaN(value)) {
+            throw new Error(`Value at index ${i} is not a valid number: ${JSON.stringify(rawValue)}. ` +
+                `Field "${valueField}" must contain numeric values.`);
+        }
+        const point = {
+            index: i,
+            value,
+        };
+        if (timestampField && item[timestampField] !== undefined) {
+            const ts = item[timestampField];
+            point.timestamp = typeof ts === 'string' || typeof ts === 'number' ? ts : String(ts);
+        }
+        points.push(point);
+    }
+    if (points.length === 0) {
+        throw new Error(`No valid numeric values found in field "${valueField}". ` +
+            'Check that the field exists and contains numbers.');
+    }
+    return points;
+}
+/**
+ * Run the appropriate detection algorithm
+ */
+function runDetection(data, detectionType, params) {
+    let rawAnomalies;
+    switch (detectionType) {
+        case 'rolling_quantile':
+            if (!params || !('window_size' in params)) {
+                throw new Error('rolling_quantile detection requires window_size parameter');
+            }
+            rawAnomalies = detectRollingQuantileAnomalies(data, params);
+            break;
+        case 'mad':
+            rawAnomalies = detectMadAnomalies(data, params);
+            break;
+        case 'moving_average':
+            if (!params || !('window_size' in params)) {
+                throw new Error('moving_average detection requires window_size parameter');
+            }
+            rawAnomalies = detectMovingAverageAnomalies(data, params);
+            break;
+        case 'threshold':
+            if (!params || !('thresholds' in params)) {
+                throw new Error('threshold detection requires thresholds parameter');
+            }
+            rawAnomalies = detectThresholdAnomalies(data, params);
+            break;
+        default:
+            throw new Error(`Unknown detection type: ${detectionType}`);
+    }
+    // Pool consecutive anomalies together
+    const pooledAnomalies = poolAnomalies(rawAnomalies);
+    return {
+        total_points: data.length,
+        anomaly_count: rawAnomalies.length,
+        anomaly_percentage: Math.round((rawAnomalies.length / data.length) * 10000) / 100, // Round to 2 decimal places
+        pool_count: pooledAnomalies.length,
+        anomalies: pooledAnomalies,
+        detection_type: detectionType,
+        parameters: params || {},
+    };
+}
+/**
+ * Main handler for time series anomaly detection
+ */
+export async function detectTimeseriesAnomalies(config, filePath, jqQuery, valueField, detectionType, detectionParams, timestampField) {
+    // Input validation
+    if (!filePath || !jqQuery || !valueField || !detectionType) {
+        throw new Error('file_path, jq_query, value_field, and detection_type are required');
+    }
+    // Sanitize jq query
+    validateJqQuery(jqQuery);
+    // Validate file path
+    if (!path.isAbsolute(filePath)) {
+        throw new Error(`File path must be an absolute path starting with "/": ${filePath}`);
+    }
+    if (!existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    if (!filePath.toLowerCase().endsWith('.json')) {
+        throw new Error(`Only JSON files (.json) are supported: ${filePath}`);
+    }
+    // Validate path is within allowed directories
+    validatePathWithinAllowedDirs(filePath, config.allowedPaths);
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // Execute jq query
+    const rawData = await runJqParsed(jqQuery, filePath, timeoutMs);
+    // Validate tabular structure
+    validateTabularData(rawData);
+    // Extract data points
+    const dataPoints = extractDataPoints(rawData, valueField, timestampField);
+    // Run detection
+    const result = runDetection(dataPoints, detectionType, detectionParams);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}