@anyshift/mcp-proxy 0.3.5 → 0.4.0

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),
+            },
+        ],
+    };
+}

package/dist/timeseries/index.d.ts

@@ -0,0 +1,68 @@
+import type { TimeseriesConfig } from './types.js';
+/**
+ * Create a timeseries anomaly detection tool instance with the given configuration
+ * @param config - Timeseries configuration
+ * @returns Object with handler and toolDefinition
+ */
+export declare function createTimeseriesTool(config: TimeseriesConfig): {
+    /**
+     * Tool definition for MCP server registration
+     */
+    toolDefinition: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                file_path: {
+                    type: string;
+                    description: string;
+                };
+                jq_query: {
+                    type: string;
+                    description: string;
+                };
+                timestamp_field: {
+                    type: string;
+                    description: string;
+                };
+                value_field: {
+                    type: string;
+                    description: string;
+                };
+                detection_type: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                detection_params: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    /**
+     * Handler for timeseries anomaly detection requests
+     * @param request - MCP request containing parameters
+     * @returns Promise with the detection result
+     */
+    handler: (request: {
+        params: {
+            arguments: Record<string, unknown>;
+        };
+    }) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+    }>;
+};
+export type { TimeseriesConfig, DataPoint, Anomaly, AnomalyDetectionResult, DetectionType, DetectionParams, NamedThreshold, ThresholdDirection, } from './types.js';
+export { TimeseriesAnomalySchema, TIMESERIES_ANOMALY_TOOL_DEFINITION } from './tool.js';
+export { detectTimeseriesAnomalies } from './handler.js';

package/dist/timeseries/index.js

@@ -0,0 +1,26 @@
+import { detectTimeseriesAnomalies } from './handler.js';
+import { TimeseriesAnomalySchema, TIMESERIES_ANOMALY_TOOL_DEFINITION } from './tool.js';
+/**
+ * Create a timeseries anomaly detection tool instance with the given configuration
+ * @param config - Timeseries configuration
+ * @returns Object with handler and toolDefinition
+ */
+export function createTimeseriesTool(config) {
+    return {
+        /**
+         * Tool definition for MCP server registration
+         */
+        toolDefinition: TIMESERIES_ANOMALY_TOOL_DEFINITION,
+        /**
+         * Handler for timeseries anomaly detection requests
+         * @param request - MCP request containing parameters
+         * @returns Promise with the detection result
+         */
+        handler: async (request) => {
+            const parsed = TimeseriesAnomalySchema.parse(request.params.arguments);
+            return detectTimeseriesAnomalies(config, parsed.file_path, parsed.jq_query, parsed.value_field, parsed.detection_type, parsed.detection_params, parsed.timestamp_field);
+        },
+    };
+}
+export { TimeseriesAnomalySchema, TIMESERIES_ANOMALY_TOOL_DEFINITION } from './tool.js';
+export { detectTimeseriesAnomalies } from './handler.js';

package/dist/timeseries/tool.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+/**
+ * Zod schema for time series anomaly detection
+ */
+export declare const TimeseriesAnomalySchema: z.ZodObject<{
+    file_path: z.ZodString;
+    jq_query: z.ZodString;
+    timestamp_field: z.ZodOptional<z.ZodString>;
+    value_field: z.ZodString;
+    detection_type: z.ZodEnum<["rolling_quantile", "mad", "moving_average", "threshold"]>;
+    detection_params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    jq_query: string;
+    file_path: string;
+    value_field: string;
+    detection_type: "rolling_quantile" | "mad" | "moving_average" | "threshold";
+    timestamp_field?: string | undefined;
+    detection_params?: Record<string, unknown> | undefined;
+    description?: string | undefined;
+}, {
+    jq_query: string;
+    file_path: string;
+    value_field: string;
+    detection_type: "rolling_quantile" | "mad" | "moving_average" | "threshold";
+    timestamp_field?: string | undefined;
+    detection_params?: Record<string, unknown> | undefined;
+    description?: string | undefined;
+}>;
+/**
+ * Tool definition for time series anomaly detection with comprehensive documentation
+ */
+export declare const TIMESERIES_ANOMALY_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            file_path: {
+                type: string;
+                description: string;
+            };
+            jq_query: {
+                type: string;
+                description: string;
+            };
+            timestamp_field: {
+                type: string;
+                description: string;
+            };
+            value_field: {
+                type: string;
+                description: string;
+            };
+            detection_type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            detection_params: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/timeseries/tool.js

@@ -0,0 +1,170 @@
+import { z } from 'zod';
+/**
+ * Schema for a named threshold
+ */
+const NamedThresholdSchema = z.object({
+    name: z.string().describe('Name/label for this threshold (e.g., "critical", "warning", "min_healthy")'),
+    value: z.number().describe('The threshold value'),
+    direction: z.enum(['upper', 'lower']).describe('Whether values should be below (upper bound) or above (lower bound) this threshold'),
+});
+/**
+ * Zod schema for time series anomaly detection
+ */
+export const TimeseriesAnomalySchema = z.object({
+    file_path: z
+        .string()
+        .describe('Absolute path starting with "/" pointing to the JSON file to process. Must be a valid, existing file with .json extension.'),
+    jq_query: z
+        .string()
+        .describe('JQ query to extract tabular data from the JSON file. The query must return an array of objects with consistent fields. Use PLAIN quotes like .["field"] - DO NOT escape them.'),
+    timestamp_field: z
+        .string()
+        .optional()
+        .describe('Optional field name in the extracted data to use as timestamp. If provided, timestamps will be included in anomaly results.'),
+    value_field: z
+        .string()
+        .describe('Field name in the extracted data containing the numeric values to analyze for anomalies.'),
+    detection_type: z
+        .enum(['rolling_quantile', 'mad', 'moving_average', 'threshold'])
+        .describe('The anomaly detection algorithm to use. See algorithm descriptions below.'),
+    detection_params: z
+        .record(z.unknown())
+        .optional()
+        .describe('Algorithm-specific parameters. See parameter descriptions for each detection_type.'),
+    description: z
+        .string()
+        .optional()
+        .describe('Brief explanation of why you are calling this tool and what you expect to learn/achieve.'),
+});
+/**
+ * Tool definition for time series anomaly detection with comprehensive documentation
+ */
+export const TIMESERIES_ANOMALY_TOOL_DEFINITION = {
+    name: 'detect_timeseries_anomalies',
+    description: 'Detect anomalies in time series data extracted from JSON files using jq queries. ' +
+        'This tool combines jq-based data extraction with statistical anomaly detection algorithms.' +
+        '\n\n## IMPORTANT: This tool has jq built-in. Do NOT prepare or transform data separately.' +
+        '\n- NO separate "transform data" step needed' +
+        '\n- NO calling execute_jq_query first' +
+        '\n- The jq_query parameter handles ALL data extraction and transformation in ONE call' +
+        '\n\n## WHAT THIS TOOL DOES (automatically, in a single call):' +
+        '\n1. Reads the JSON file' +
+        '\n2. Applies the jq query to extract tabular data (array of objects)' +
+        '\n3. Extracts numeric values from the specified value_field' +
+        '\n4. Runs the selected anomaly detection algorithm' +
+        '\n5. Returns detected anomalies with indices, values, and reasons' +
+        '\n\n## DATA REQUIREMENTS:' +
+        '\n- The jq_query MUST return an array of objects: [{...}, {...}, ...]' +
+        '\n- Each object MUST have the field specified in value_field' +
+        '\n- The value_field MUST contain numeric values' +
+        '\n- If timestamp_field is provided, it will be included in results' +
+        '\n\n## DETECTION ALGORITHMS:' +
+        '\n\n### rolling_quantile (RECOMMENDED - similar to Datadog Basic)' +
+        '\nUses a sliding window to compute rolling percentiles, flags points outside the expected range.' +
+        '\n- Best for: General purpose, works with any data distribution' +
+        '\n- Parameters: { "window_size": 10, "lower_quantile": 0.05, "upper_quantile": 0.95 }' +
+        '\n- REQUIRED: window_size (number of points in rolling window)' +
+        '\n- lower_quantile: percentile for lower bound (default: 0.05 = 5th percentile)' +
+        '\n- upper_quantile: percentile for upper bound (default: 0.95 = 95th percentile)' +
+        '\n- Non-parametric: does not assume normal distribution' +
+        '\n\n### mad (Median Absolute Deviation)' +
+        '\nUses modified Z-scores based on median instead of mean.' +
+        '\n- Best for: Global outlier detection across all data, robust to existing outliers' +
+        '\n- Parameters: { "threshold": 3 } (default: 3)' +
+        '\n- Uses median-based statistics for maximum robustness' +
+        '\n- Good when you want to find outliers relative to the entire dataset' +
+        '\n\n### moving_average' +
+        '\nDetects points that deviate from a rolling average.' +
+        '\n- Best for: Time series with trends, detecting sudden changes' +
+        '\n- Parameters: { "window_size": 10, "threshold": 2 }' +
+        '\n- REQUIRED: window_size (number of points in rolling window)' +
+        '\n- threshold: std devs from moving average (default: 2)' +
+        '\n- Assumes roughly normal distribution within each window' +
+        '\n\n### threshold' +
+        '\nDetects points crossing named upper/lower thresholds.' +
+        '\n- Best for: SLA monitoring, known limits' +
+        '\n- Parameters: { "thresholds": [...] }' +
+        '\n- REQUIRED: thresholds array with named thresholds' +
+        '\n- Each threshold: { "name": "critical", "value": 100, "direction": "upper" }' +
+        '\n- direction: "upper" = value must be below, "lower" = value must be above' +
+        '\n\n## JQ QUERY TIPS:' +
+        '\n- Use PLAIN quotes: .["field"] NOT .[\"field\"]' +
+        '\n- Array of metrics: .metrics' +
+        '\n- Nested data: .data.timeseries' +
+        '\n- Filter: .items[] | select(.type == "cpu") | {ts: .timestamp, val: .value}' +
+        '\n- Transform: [.[] | {timestamp: .ts, value: .cpu_usage}]' +
+        '\n\n## EXAMPLE CALLS:' +
+        '\n\n**Rolling Quantile detection (RECOMMENDED):**' +
+        '\n```json' +
+        '\n{' +
+        '\n  "file_path": "/tmp/metrics.json",' +
+        '\n  "jq_query": ".cpu_metrics",' +
+        '\n  "value_field": "usage",' +
+        '\n  "timestamp_field": "timestamp",' +
+        '\n  "detection_type": "rolling_quantile",' +
+        '\n  "detection_params": { "window_size": 10, "lower_quantile": 0.05, "upper_quantile": 0.95 }' +
+        '\n}' +
+        '\n```' +
+        '\n\n**Threshold detection with SLA limits:**' +
+        '\n```json' +
+        '\n{' +
+        '\n  "file_path": "/tmp/response_times.json",' +
+        '\n  "jq_query": ".api_latencies",' +
+        '\n  "value_field": "latency_ms",' +
+        '\n  "detection_type": "threshold",' +
+        '\n  "detection_params": {' +
+        '\n    "thresholds": [' +
+        '\n      { "name": "warning", "value": 200, "direction": "upper" },' +
+        '\n      { "name": "critical", "value": 500, "direction": "upper" },' +
+        '\n      { "name": "too_fast", "value": 1, "direction": "lower" }' +
+        '\n    ]' +
+        '\n  }' +
+        '\n}' +
+        '\n```' +
+        '\n\n**MAD for global outlier detection:**' +
+        '\n```json' +
+        '\n{' +
+        '\n  "file_path": "/tmp/sales.json",' +
+        '\n  "jq_query": "[.daily_sales[] | {date: .date, amount: .total}]",' +
+        '\n  "value_field": "amount",' +
+        '\n  "timestamp_field": "date",' +
+        '\n  "detection_type": "mad",' +
+        '\n  "detection_params": { "threshold": 3 }' +
+        '\n}' +
+        '\n```',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file_path: {
+                type: 'string',
+                description: 'Absolute path starting with "/" pointing to the JSON file to process. Must be a valid, existing file with .json extension.',
+            },
+            jq_query: {
+                type: 'string',
+                description: 'JQ query to extract tabular data from the JSON file. The query must return an array of objects with consistent fields. Use PLAIN quotes like .["field"] - DO NOT escape them.',
+            },
+            timestamp_field: {
+                type: 'string',
+                description: 'Optional field name in the extracted data to use as timestamp. If provided, timestamps will be included in anomaly results.',
+            },
+            value_field: {
+                type: 'string',
+                description: 'Field name in the extracted data containing the numeric values to analyze for anomalies.',
+            },
+            detection_type: {
+                type: 'string',
+                enum: ['rolling_quantile', 'mad', 'moving_average', 'threshold'],
+                description: 'The anomaly detection algorithm to use: rolling_quantile (recommended), mad, moving_average, or threshold.',
+            },
+            detection_params: {
+                type: 'object',
+                description: 'Algorithm-specific parameters. For rolling_quantile: {window_size: number, lower_quantile?: number, upper_quantile?: number}. For mad: {threshold: number}. For moving_average: {window_size: number, threshold?: number}. For threshold: {thresholds: [{name, value, direction}]}.',
+            },
+            description: {
+                type: 'string',
+                description: 'Brief explanation of why you are calling this tool and what you expect to learn/achieve.',
+            },
+        },
+        required: ['file_path', 'jq_query', 'value_field', 'detection_type'],
+    },
+};