@anyshift/mcp-proxy 0.3.6 → 0.4.0

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

package/dist/timeseries/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Time Series Anomaly Detection Types
+ */
+/**
+ * A single data point in the time series
+ */
+export interface DataPoint {
+    /** Index in the original array */
+    index: number;
+    /** Timestamp value (if available) */
+    timestamp?: string | number;
+    /** The numeric value */
+    value: number;
+}
+/**
+ * Threshold direction for threshold-based detection
+ */
+export type ThresholdDirection = 'upper' | 'lower';
+/**
+ * A named threshold with direction
+ */
+export interface NamedThreshold {
+    /** Name/label for this threshold */
+    name: string;
+    /** The threshold value */
+    value: number;
+    /** Whether this is an upper or lower bound */
+    direction: ThresholdDirection;
+}
+/**
+ * Detection types supported by the tool
+ */
+export type DetectionType = 'rolling_quantile' | 'mad' | 'moving_average' | 'threshold';
+/**
+ * Parameters for Rolling Quantile detection (similar to Datadog Basic)
+ */
+export interface RollingQuantileParams {
+    /** Window size for the rolling quantile calculation */
+    window_size: number;
+    /** Lower quantile for the expected range (default: 0.05 = 5th percentile) */
+    lower_quantile?: number;
+    /** Upper quantile for the expected range (default: 0.95 = 95th percentile) */
+    upper_quantile?: number;
+}
+/**
+ * Parameters for MAD (Median Absolute Deviation) detection
+ */
+export interface MadParams {
+    /** Multiplier for MAD threshold (default: 3) */
+    threshold?: number;
+}
+/**
+ * Parameters for Moving Average detection
+ */
+export interface MovingAverageParams {
+    /** Window size for the moving average */
+    window_size: number;
+    /** Number of standard deviations from moving average (default: 2) */
+    threshold?: number;
+}
+/**
+ * Parameters for Threshold detection
+ */
+export interface ThresholdParams {
+    /** Named thresholds with direction */
+    thresholds: NamedThreshold[];
+}
+/**
+ * Union type for all detection parameters
+ */
+export type DetectionParams = RollingQuantileParams | MadParams | MovingAverageParams | ThresholdParams;
+/**
+ * A detected anomaly (individual point)
+ */
+export interface Anomaly {
+    /** Index in the original data */
+    index: number;
+    /** Timestamp if available (raw value from data) */
+    timestamp?: string | number;
+    /** UTC time string if timestamp was a Unix timestamp */
+    utc_time?: string;
+    /** The anomalous value */
+    value: number;
+    /** Reason/description of why this is an anomaly */
+    reason: string;
+    /** For threshold detection: which thresholds were crossed */
+    crossed_thresholds?: string[];
+    /** Additional metadata (e.g., z-score value, percent change) */
+    metadata?: Record<string, number>;
+}
+/**
+ * A pooled anomaly (consecutive anomalies grouped together)
+ */
+export interface PooledAnomaly {
+    /** Start index in the original data */
+    start_index: number;
+    /** End index in the original data (inclusive) */
+    end_index: number;
+    /** Number of anomalous points in this pool */
+    count: number;
+    /** Start timestamp if available */
+    start_timestamp?: string | number;
+    /** End timestamp if available */
+    end_timestamp?: string | number;
+    /** Start UTC time string */
+    start_utc?: string;
+    /** End UTC time string */
+    end_utc?: string;
+    /** Minimum value in the pool */
+    min_value: number;
+    /** Maximum value in the pool */
+    max_value: number;
+    /** Average value in the pool */
+    avg_value: number;
+    /** Summary reason for the pool */
+    reason: string;
+    /** For threshold detection: union of all crossed thresholds */
+    crossed_thresholds?: string[];
+}
+/**
+ * Result of anomaly detection
+ */
+export interface AnomalyDetectionResult {
+    /** Total number of data points analyzed */
+    total_points: number;
+    /** Number of anomalous points detected */
+    anomaly_count: number;
+    /** Percentage of points that are anomalies */
+    anomaly_percentage: number;
+    /** Number of anomaly pools (consecutive anomalies grouped) */
+    pool_count: number;
+    /** List of pooled anomalies (consecutive anomalies grouped together) */
+    anomalies: PooledAnomaly[];
+    /** Detection method used */
+    detection_type: DetectionType;
+    /** Parameters used for detection */
+    parameters: DetectionParams;
+}
+/**
+ * Configuration for the timeseries anomaly detection tool
+ */
+export interface TimeseriesConfig {
+    /** Paths where the tool is allowed to read files */
+    allowedPaths: string[];
+    /** Timeout for jq query execution in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}

package/dist/timeseries/types.js

@@ -0,0 +1,4 @@
+/**
+ * Time Series Anomaly Detection Types
+ */
+export {};

package/dist/utils/jq.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Dangerous patterns that could access environment variables or system info in jq queries
+ */
+export declare const DANGEROUS_JQ_PATTERNS: RegExp[];
+/**
+ * Validate a jq query for dangerous patterns
+ * @throws Error if the query contains dangerous patterns
+ */
+export declare function validateJqQuery(jqQuery: string): void;
+/**
+ * Execute a jq query and return the raw stdout string
+ * @param jqQuery - The jq query to execute
+ * @param filePath - Path to the JSON file
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Raw stdout string from jq
+ */
+export declare function runJq(jqQuery: string, filePath: string, timeoutMs: number): Promise<string>;
+/**
+ * Execute a jq query and return the parsed JSON result
+ * @param jqQuery - The jq query to execute
+ * @param filePath - Path to the JSON file
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Parsed JSON result
+ */
+export declare function runJqParsed(jqQuery: string, filePath: string, timeoutMs: number): Promise<unknown>;

package/dist/utils/jq.js

@@ -0,0 +1,90 @@
+import { spawn } from 'child_process';
+/**
+ * Dangerous patterns that could access environment variables or system info in jq queries
+ */
+export const DANGEROUS_JQ_PATTERNS = [
+    /\$ENV/i, // $ENV variable access
+    /env\./i, // env.VARIABLE access
+    /@env/i, // @env function
+    /\.env\[/i, // .env["VARIABLE"] access
+    /getenv/i, // getenv function
+    /\$__loc__/i, // location info that might leak paths
+    /input_filename/i, // input filename access
+];
+/**
+ * Validate a jq query for dangerous patterns
+ * @throws Error if the query contains dangerous patterns
+ */
+export function validateJqQuery(jqQuery) {
+    const isDangerous = DANGEROUS_JQ_PATTERNS.some((pattern) => pattern.test(jqQuery));
+    if (isDangerous) {
+        throw new Error('The jq query contains patterns that could access environment variables or system information. Please use a different query.');
+    }
+}
+/**
+ * Execute a jq query and return the raw stdout string
+ * @param jqQuery - The jq query to execute
+ * @param filePath - Path to the JSON file
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Raw stdout string from jq
+ */
+export async function runJq(jqQuery, filePath, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const jqProcess = spawn('jq', [jqQuery, filePath], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: timeoutMs,
+        });
+        let stdout = '';
+        let stderr = '';
+        jqProcess.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        jqProcess.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        // Handle timeout
+        const timeoutId = setTimeout(() => {
+            if (!settled && !jqProcess.killed) {
+                settled = true;
+                jqProcess.kill('SIGTERM');
+                reject(new Error(`jq command timed out after ${timeoutMs}ms`));
+            }
+        }, timeoutMs);
+        jqProcess.on('close', (code) => {
+            clearTimeout(timeoutId);
+            if (settled)
+                return;
+            settled = true;
+            if (code === 0) {
+                resolve(stdout.trim());
+            }
+            else {
+                reject(new Error(`jq command failed with exit code ${code}: ${stderr.trim()}`));
+            }
+        });
+        jqProcess.on('error', (error) => {
+            clearTimeout(timeoutId);
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`Failed to execute jq command: ${error.message}`));
+        });
+    });
+}
+/**
+ * Execute a jq query and return the parsed JSON result
+ * @param jqQuery - The jq query to execute
+ * @param filePath - Path to the JSON file
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Parsed JSON result
+ */
+export async function runJqParsed(jqQuery, filePath, timeoutMs) {
+    const stdout = await runJq(jqQuery, filePath, timeoutMs);
+    try {
+        return JSON.parse(stdout);
+    }
+    catch (parseError) {
+        throw new Error(`Failed to parse jq output as JSON: ${stdout.slice(0, 200)}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anyshift/mcp-proxy",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Generic MCP proxy that adds truncation, file writing, and JQ capabilities to any MCP server",
   "type": "module",
   "main": "dist/index.js",