@rog0x/mcp-perf-tools 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# mcp-perf-tools
+
+Performance analysis tools for AI agents, exposed via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
+
+## Tools
+
+### benchmark
+
+Benchmark JavaScript code execution. Run a snippet N times and measure min/max/avg/median/p95/p99 latency and operations per second. Optionally compare two implementations side by side.
+
+**Parameters:**
+- `code` (string) — JavaScript code to benchmark
+- `iterations` (number, default 1000) — Number of iterations
+- `compareCode` (string, optional) — Second implementation to compare
+- `labelA` / `labelB` (string) — Labels for comparison output
+
+### memory_analyze
+
+Analyze Node.js memory usage: heap used/total, RSS, external memory, and array buffers. Takes snapshots over time and uses linear regression to detect trends and potential memory leaks.
+
+**Parameters:**
+- `action` — `"snapshot"` | `"analyze"` | `"clear"`
+
+### big_o_estimate
+
+Estimate Big O complexity from empirical timing data. Fits measurements against O(1), O(log n), O(n), O(n log n), O(n^2), O(n^3), and O(2^n) using R-squared scoring. Includes an ASCII growth curve visualization.
+
+**Parameters:**
+- `inputSizes` (number[]) — Array of input sizes
+- `executionTimesMs` (number[]) — Corresponding execution times in ms
+
+### bundle_analyze
+
+Analyze a JavaScript bundle file: raw size, gzip compressed estimate, detected module count, largest modules, and tree-shaking opportunities (side effects, duplicates).
+
+**Parameters:**
+- `filePath` (string) — Absolute path to the bundle file
+
+### load_test
+
+Simple HTTP load tester. Sends N requests at a given concurrency level and reports response time percentiles, error rate, throughput (req/sec), and status code distribution.
+
+**Parameters:**
+- `url` (string) — Target URL
+- `totalRequests` (number, default 100) — Total requests to send
+- `concurrency` (number, default 10) — Concurrent request count
+- `method` (string, default "GET") — HTTP method
+- `headers` (object, optional) — HTTP headers
+- `body` (string, optional) — Request body
+- `timeoutMs` (number, default 30000) — Request timeout
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "perf-tools": {
+      "command": "node",
+      "args": ["D:/products/mcp-servers/mcp-perf-tools/dist/index.js"]
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const benchmark_js_1 = require("./tools/benchmark.js");
+const memory_analyzer_js_1 = require("./tools/memory-analyzer.js");
+const big_o_estimator_js_1 = require("./tools/big-o-estimator.js");
+const bundle_analyzer_js_1 = require("./tools/bundle-analyzer.js");
+const load_tester_js_1 = require("./tools/load-tester.js");
+const server = new mcp_js_1.McpServer({
+    name: "mcp-perf-tools",
+    version: "1.0.0",
+});
+// -------------------------------------------------------------------
+// Tool 1: benchmark
+// -------------------------------------------------------------------
+server.tool("benchmark", "Benchmark JavaScript code execution. Run a snippet N times and measure min/max/avg/p95/p99 time and ops/sec. Optionally compare two implementations.", {
+    code: zod_1.z.string().describe("JavaScript code to benchmark"),
+    iterations: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .default(1000)
+        .describe("Number of iterations to run"),
+    compareCode: zod_1.z
+        .string()
+        .optional()
+        .describe("Optional second implementation to compare against"),
+    labelA: zod_1.z
+        .string()
+        .default("A")
+        .describe("Label for the first implementation"),
+    labelB: zod_1.z
+        .string()
+        .default("B")
+        .describe("Label for the second implementation"),
+}, async ({ code, iterations, compareCode, labelA, labelB }) => {
+    try {
+        if (compareCode) {
+            const result = (0, benchmark_js_1.compareBenchmarks)(code, labelA, compareCode, labelB, iterations);
+            return { content: [{ type: "text", text: result.summary }] };
+        }
+        const result = (0, benchmark_js_1.runBenchmark)(code, iterations);
+        return {
+            content: [{ type: "text", text: (0, benchmark_js_1.formatBenchmarkResult)(result) }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Benchmark error: ${msg}` }],
+            isError: true,
+        };
+    }
+});
+// -------------------------------------------------------------------
+// Tool 2: memory_analyze
+// -------------------------------------------------------------------
+server.tool("memory_analyze", "Analyze Node.js memory usage: heap used/total, RSS, external, array buffers. Tracks snapshots over time and detects potential memory leaks via growth trend analysis.", {
+    action: zod_1.z
+        .enum(["snapshot", "analyze", "clear"])
+        .default("analyze")
+        .describe("snapshot: take a single reading; analyze: full analysis with trend detection; clear: reset history"),
+}, async ({ action }) => {
+    try {
+        if (action === "clear") {
+            (0, memory_analyzer_js_1.clearSnapshotHistory)();
+            return {
+                content: [{ type: "text", text: "Memory snapshot history cleared." }],
+            };
+        }
+        if (action === "snapshot") {
+            const snap = (0, memory_analyzer_js_1.takeMemorySnapshot)();
+            return {
+                content: [{ type: "text", text: (0, memory_analyzer_js_1.formatSnapshot)(snap) }],
+            };
+        }
+        // analyze
+        const analysis = (0, memory_analyzer_js_1.analyzeMemory)();
+        return {
+            content: [{ type: "text", text: analysis.summary }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Memory analysis error: ${msg}` }],
+            isError: true,
+        };
+    }
+});
+// -------------------------------------------------------------------
+// Tool 3: big_o_estimate
+// -------------------------------------------------------------------
+server.tool("big_o_estimate", "Estimate Big O complexity from empirical data. Provide input sizes and corresponding execution times to get the best-fit complexity class (O(1), O(log n), O(n), O(n log n), O(n^2), O(n^3), O(2^n)) with confidence scores and growth curve.", {
+    inputSizes: zod_1.z
+        .array(zod_1.z.number().positive())
+        .min(3)
+        .describe("Array of input sizes (e.g., [100, 500, 1000, 5000])"),
+    executionTimesMs: zod_1.z
+        .array(zod_1.z.number().nonnegative())
+        .min(3)
+        .describe("Array of execution times in milliseconds, corresponding to each input size"),
+}, async ({ inputSizes, executionTimesMs }) => {
+    try {
+        const result = (0, big_o_estimator_js_1.estimateBigO)(inputSizes, executionTimesMs);
+        return {
+            content: [{ type: "text", text: result.summary }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Big O estimation error: ${msg}` }],
+            isError: true,
+        };
+    }
+});
+// -------------------------------------------------------------------
+// Tool 4: bundle_analyze
+// -------------------------------------------------------------------
+server.tool("bundle_analyze", "Analyze a JavaScript bundle file: raw size, gzip estimate, detected modules, largest modules, and tree-shaking opportunities.", {
+    filePath: zod_1.z
+        .string()
+        .describe("Absolute path to the JavaScript bundle file to analyze"),
+}, async ({ filePath }) => {
+    try {
+        const result = (0, bundle_analyzer_js_1.analyzeBundle)(filePath);
+        return {
+            content: [{ type: "text", text: result.summary }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Bundle analysis error: ${msg}` }],
+            isError: true,
+        };
+    }
+});
+// -------------------------------------------------------------------
+// Tool 5: load_test
+// -------------------------------------------------------------------
+server.tool("load_test", "Run a simple HTTP load test: send N concurrent requests to a URL, measure response times, error rate, throughput (req/sec), and percentile latencies.", {
+    url: zod_1.z.string().url().describe("Target URL to test"),
+    totalRequests: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .default(100)
+        .describe("Total number of requests to send"),
+    concurrency: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .default(10)
+        .describe("Number of concurrent requests"),
+    method: zod_1.z
+        .string()
+        .default("GET")
+        .describe("HTTP method (GET, POST, PUT, DELETE, etc.)"),
+    headers: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.string())
+        .optional()
+        .describe("Optional HTTP headers as key-value pairs"),
+    body: zod_1.z.string().optional().describe("Optional request body"),
+    timeoutMs: zod_1.z
+        .number()
+        .int()
+        .min(1000)
+        .default(30000)
+        .describe("Request timeout in milliseconds"),
+}, async ({ url, totalRequests, concurrency, method, headers, body, timeoutMs }) => {
+    try {
+        const result = await (0, load_tester_js_1.runLoadTest)({
+            url,
+            totalRequests,
+            concurrency,
+            method,
+            headers,
+            body,
+            timeoutMs,
+        });
+        return {
+            content: [{ type: "text", text: result.summary }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Load test error: ${msg}` }],
+            isError: true,
+        };
+    }
+});
+// -------------------------------------------------------------------
+// Start server
+// -------------------------------------------------------------------
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("mcp-perf-tools server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/tools/benchmark.d.ts

@@ -0,0 +1,27 @@
+export interface BenchmarkResult {
+    iterations: number;
+    minMs: number;
+    maxMs: number;
+    avgMs: number;
+    medianMs: number;
+    p95Ms: number;
+    p99Ms: number;
+    opsPerSecond: number;
+    totalMs: number;
+    timings: number[];
+}
+export interface ComparisonResult {
+    a: BenchmarkResult & {
+        label: string;
+    };
+    b: BenchmarkResult & {
+        label: string;
+    };
+    fasterLabel: string;
+    speedupFactor: number;
+    summary: string;
+}
+export declare function runBenchmark(code: string, iterations: number): BenchmarkResult;
+export declare function compareBenchmarks(codeA: string, labelA: string, codeB: string, labelB: string, iterations: number): ComparisonResult;
+export declare function formatBenchmarkResult(result: BenchmarkResult): string;
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/tools/benchmark.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBenchmark = runBenchmark;
+exports.compareBenchmarks = compareBenchmarks;
+exports.formatBenchmarkResult = formatBenchmarkResult;
+const node_perf_hooks_1 = require("node:perf_hooks");
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = (p / 100) * (sorted.length - 1);
+    const lower = Math.floor(idx);
+    const upper = Math.ceil(idx);
+    if (lower === upper)
+        return sorted[lower];
+    return sorted[lower] + (sorted[upper] - sorted[lower]) * (idx - lower);
+}
+function runBenchmark(code, iterations) {
+    const timings = [];
+    // Wrap the code in a function so it can be executed repeatedly
+    const fn = new Function(code);
+    // Warmup: 10% of iterations or at least 3
+    const warmupCount = Math.max(3, Math.floor(iterations * 0.1));
+    for (let i = 0; i < warmupCount; i++) {
+        fn();
+    }
+    for (let i = 0; i < iterations; i++) {
+        const start = node_perf_hooks_1.performance.now();
+        fn();
+        const end = node_perf_hooks_1.performance.now();
+        timings.push(end - start);
+    }
+    const sorted = [...timings].sort((a, b) => a - b);
+    const totalMs = timings.reduce((s, t) => s + t, 0);
+    const avgMs = totalMs / timings.length;
+    return {
+        iterations,
+        minMs: sorted[0],
+        maxMs: sorted[sorted.length - 1],
+        avgMs,
+        medianMs: percentile(sorted, 50),
+        p95Ms: percentile(sorted, 95),
+        p99Ms: percentile(sorted, 99),
+        opsPerSecond: totalMs > 0 ? (iterations / totalMs) * 1000 : Infinity,
+        totalMs,
+        timings: sorted,
+    };
+}
+function compareBenchmarks(codeA, labelA, codeB, labelB, iterations) {
+    const resultA = runBenchmark(codeA, iterations);
+    const resultB = runBenchmark(codeB, iterations);
+    const fasterIsA = resultA.avgMs < resultB.avgMs;
+    const fasterLabel = fasterIsA ? labelA : labelB;
+    const speedupFactor = fasterIsA
+        ? resultB.avgMs / resultA.avgMs
+        : resultA.avgMs / resultB.avgMs;
+    const summary = [
+        `"${fasterLabel}" is ${speedupFactor.toFixed(2)}x faster.`,
+        `  ${labelA}: avg ${resultA.avgMs.toFixed(4)}ms, p95 ${resultA.p95Ms.toFixed(4)}ms, ${resultA.opsPerSecond.toFixed(0)} ops/s`,
+        `  ${labelB}: avg ${resultB.avgMs.toFixed(4)}ms, p95 ${resultB.p95Ms.toFixed(4)}ms, ${resultB.opsPerSecond.toFixed(0)} ops/s`,
+    ].join("\n");
+    return {
+        a: { ...resultA, label: labelA },
+        b: { ...resultB, label: labelB },
+        fasterLabel,
+        speedupFactor,
+        summary,
+    };
+}
+function formatBenchmarkResult(result) {
+    return [
+        `Benchmark Results (${result.iterations} iterations):`,
+        `  Min:    ${result.minMs.toFixed(4)} ms`,
+        `  Max:    ${result.maxMs.toFixed(4)} ms`,
+        `  Avg:    ${result.avgMs.toFixed(4)} ms`,
+        `  Median: ${result.medianMs.toFixed(4)} ms`,
+        `  P95:    ${result.p95Ms.toFixed(4)} ms`,
+        `  P99:    ${result.p99Ms.toFixed(4)} ms`,
+        `  Ops/s:  ${result.opsPerSecond.toFixed(0)}`,
+        `  Total:  ${result.totalMs.toFixed(2)} ms`,
+    ].join("\n");
+}
+//# sourceMappingURL=benchmark.js.map

package/dist/tools/big-o-estimator.d.ts

@@ -0,0 +1,13 @@
+export type ComplexityClass = "O(1)" | "O(log n)" | "O(n)" | "O(n log n)" | "O(n^2)" | "O(n^3)" | "O(2^n)" | "unknown";
+export interface BigOEstimate {
+    bestFit: ComplexityClass;
+    confidence: number;
+    allFits: Array<{
+        complexity: ComplexityClass;
+        r2: number;
+    }>;
+    growthCurve: string;
+    summary: string;
+}
+export declare function estimateBigO(inputSizes: number[], executionTimesMs: number[]): BigOEstimate;
+//# sourceMappingURL=big-o-estimator.d.ts.map

package/dist/tools/big-o-estimator.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateBigO = estimateBigO;
+function linearRegression(xs, ys) {
+    const n = xs.length;
+    if (n < 2)
+        return { slope: 0, intercept: ys[0] ?? 0, r2: 0 };
+    const sumX = xs.reduce((a, b) => a + b, 0);
+    const sumY = ys.reduce((a, b) => a + b, 0);
+    const sumXY = xs.reduce((a, x, i) => a + x * ys[i], 0);
+    const sumX2 = xs.reduce((a, x) => a + x * x, 0);
+    const denom = n * sumX2 - sumX * sumX;
+    if (denom === 0)
+        return { slope: 0, intercept: sumY / n, r2: 0 };
+    const slope = (n * sumXY - sumX * sumY) / denom;
+    const intercept = (sumY - slope * sumX) / n;
+    const meanY = sumY / n;
+    const ssTot = ys.reduce((a, y) => a + (y - meanY) ** 2, 0);
+    const ssRes = ys.reduce((a, y, i) => a + (y - (slope * xs[i] + intercept)) ** 2, 0);
+    const r2 = ssTot === 0 ? 1 : 1 - ssRes / ssTot;
+    return { slope, intercept, r2 };
+}
+function tryFit(sizes, times, transform, label, description) {
+    const transformed = sizes.map(transform);
+    // Check for non-finite values
+    if (transformed.some((v) => !isFinite(v))) {
+        return { complexity: label, r2: -Infinity, description };
+    }
+    const { r2 } = linearRegression(transformed, times);
+    return { complexity: label, r2, description };
+}
+function estimateBigO(inputSizes, executionTimesMs) {
+    if (inputSizes.length !== executionTimesMs.length) {
+        throw new Error("inputSizes and executionTimesMs must have the same length");
+    }
+    if (inputSizes.length < 3) {
+        throw new Error("Need at least 3 data points for a meaningful estimate");
+    }
+    const fits = [
+        tryFit(inputSizes, executionTimesMs, (_n) => 1, "O(1)", "Constant time: performance does not change with input size."),
+        tryFit(inputSizes, executionTimesMs, (n) => Math.log2(n), "O(log n)", "Logarithmic: performance grows slowly, typical of binary search or balanced trees."),
+        tryFit(inputSizes, executionTimesMs, (n) => n, "O(n)", "Linear: performance scales proportionally with input size."),
+        tryFit(inputSizes, executionTimesMs, (n) => n * Math.log2(n), "O(n log n)", "Linearithmic: typical of efficient sorting algorithms (mergesort, heapsort)."),
+        tryFit(inputSizes, executionTimesMs, (n) => n * n, "O(n^2)", "Quadratic: nested iteration over input, common in naive sorting or pairwise comparisons."),
+        tryFit(inputSizes, executionTimesMs, (n) => n * n * n, "O(n^3)", "Cubic: triple-nested loops, e.g., naive matrix multiplication."),
+        tryFit(inputSizes, executionTimesMs, (n) => Math.pow(2, n), "O(2^n)", "Exponential: brute-force recursive algorithms, rapidly becomes infeasible."),
+    ];
+    // Sort by R^2 descending (best fit first)
+    fits.sort((a, b) => b.r2 - a.r2);
+    const best = fits[0];
+    const confidence = Math.max(0, Math.min(1, best.r2));
+    // Build a simple ASCII growth curve description
+    const growthCurve = buildGrowthCurve(inputSizes, executionTimesMs);
+    const allFits = fits.map((f) => ({ complexity: f.complexity, r2: f.r2 }));
+    const summary = [
+        `Big O Estimate: ${best.complexity} (confidence: ${(confidence * 100).toFixed(1)}%)`,
+        `${best.description}`,
+        "",
+        "All fits (by R² descending):",
+        ...allFits.map((f) => `  ${f.complexity.padEnd(10)} R² = ${f.r2.toFixed(4)}`),
+        "",
+        "Growth Curve:",
+        growthCurve,
+    ].join("\n");
+    return { bestFit: best.complexity, confidence, allFits, growthCurve, summary };
+}
+function buildGrowthCurve(sizes, times) {
+    const maxTime = Math.max(...times);
+    const maxBarWidth = 40;
+    const lines = [];
+    for (let i = 0; i < sizes.length; i++) {
+        const barLen = maxTime > 0 ? Math.round((times[i] / maxTime) * maxBarWidth) : 0;
+        const bar = "\u2588".repeat(barLen);
+        const sizeStr = String(sizes[i]).padStart(10);
+        const timeStr = times[i].toFixed(2).padStart(10);
+        lines.push(`  n=${sizeStr}  ${timeStr}ms  ${bar}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=big-o-estimator.js.map

package/dist/tools/bundle-analyzer.d.ts

@@ -0,0 +1,25 @@
+export interface ModuleInfo {
+    filePath: string;
+    sizeBytes: number;
+    sizeKB: number;
+    /** Percentage of total bundle size */
+    percentage: number;
+}
+export interface TreeShakingOpportunity {
+    filePath: string;
+    reason: string;
+}
+export interface BundleAnalysis {
+    filePath: string;
+    rawSizeBytes: number;
+    rawSizeKB: number;
+    gzipEstimateBytes: number;
+    gzipEstimateKB: number;
+    compressionRatio: number;
+    moduleCount: number;
+    largestModules: ModuleInfo[];
+    treeShakingOpportunities: TreeShakingOpportunity[];
+    summary: string;
+}
+export declare function analyzeBundle(filePath: string): BundleAnalysis;
+//# sourceMappingURL=bundle-analyzer.d.ts.map