@rog0x/mcp-perf-tools 1.0.0

package/src/index.ts

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import {
+  runBenchmark,
+  compareBenchmarks,
+  formatBenchmarkResult,
+} from "./tools/benchmark.js";
+import {
+  analyzeMemory,
+  takeMemorySnapshot,
+  clearSnapshotHistory,
+  formatSnapshot,
+} from "./tools/memory-analyzer.js";
+import { estimateBigO } from "./tools/big-o-estimator.js";
+import { analyzeBundle } from "./tools/bundle-analyzer.js";
+import { runLoadTest } from "./tools/load-tester.js";
+
+const server = new 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: z.string().describe("JavaScript code to benchmark"),
+    iterations: z
+      .number()
+      .int()
+      .min(1)
+      .default(1000)
+      .describe("Number of iterations to run"),
+    compareCode: z
+      .string()
+      .optional()
+      .describe("Optional second implementation to compare against"),
+    labelA: z
+      .string()
+      .default("A")
+      .describe("Label for the first implementation"),
+    labelB: z
+      .string()
+      .default("B")
+      .describe("Label for the second implementation"),
+  },
+  async ({ code, iterations, compareCode, labelA, labelB }) => {
+    try {
+      if (compareCode) {
+        const result = compareBenchmarks(
+          code,
+          labelA,
+          compareCode,
+          labelB,
+          iterations
+        );
+        return { content: [{ type: "text", text: result.summary }] };
+      }
+
+      const result = runBenchmark(code, iterations);
+      return {
+        content: [{ type: "text", text: formatBenchmarkResult(result) }],
+      };
+    } catch (err: unknown) {
+      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: 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") {
+        clearSnapshotHistory();
+        return {
+          content: [{ type: "text", text: "Memory snapshot history cleared." }],
+        };
+      }
+      if (action === "snapshot") {
+        const snap = takeMemorySnapshot();
+        return {
+          content: [{ type: "text", text: formatSnapshot(snap) }],
+        };
+      }
+      // analyze
+      const analysis = analyzeMemory();
+      return {
+        content: [{ type: "text", text: analysis.summary }],
+      };
+    } catch (err: unknown) {
+      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: z
+      .array(z.number().positive())
+      .min(3)
+      .describe("Array of input sizes (e.g., [100, 500, 1000, 5000])"),
+    executionTimesMs: z
+      .array(z.number().nonnegative())
+      .min(3)
+      .describe(
+        "Array of execution times in milliseconds, corresponding to each input size"
+      ),
+  },
+  async ({ inputSizes, executionTimesMs }) => {
+    try {
+      const result = estimateBigO(inputSizes, executionTimesMs);
+      return {
+        content: [{ type: "text", text: result.summary }],
+      };
+    } catch (err: unknown) {
+      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: z
+      .string()
+      .describe("Absolute path to the JavaScript bundle file to analyze"),
+  },
+  async ({ filePath }) => {
+    try {
+      const result = analyzeBundle(filePath);
+      return {
+        content: [{ type: "text", text: result.summary }],
+      };
+    } catch (err: unknown) {
+      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: z.string().url().describe("Target URL to test"),
+    totalRequests: z
+      .number()
+      .int()
+      .min(1)
+      .default(100)
+      .describe("Total number of requests to send"),
+    concurrency: z
+      .number()
+      .int()
+      .min(1)
+      .default(10)
+      .describe("Number of concurrent requests"),
+    method: z
+      .string()
+      .default("GET")
+      .describe("HTTP method (GET, POST, PUT, DELETE, etc.)"),
+    headers: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe("Optional HTTP headers as key-value pairs"),
+    body: z.string().optional().describe("Optional request body"),
+    timeoutMs: z
+      .number()
+      .int()
+      .min(1000)
+      .default(30000)
+      .describe("Request timeout in milliseconds"),
+  },
+  async ({ url, totalRequests, concurrency, method, headers, body, timeoutMs }) => {
+    try {
+      const result = await runLoadTest({
+        url,
+        totalRequests,
+        concurrency,
+        method,
+        headers,
+        body,
+        timeoutMs,
+      });
+      return {
+        content: [{ type: "text", text: result.summary }],
+      };
+    } catch (err: unknown) {
+      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(): Promise<void> {
+  const transport = new 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);
+});

package/src/tools/benchmark.ts

@@ -0,0 +1,113 @@
+import { performance } from "node:perf_hooks";
+
+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;
+}
+
+function percentile(sorted: number[], p: number): number {
+  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);
+}
+
+export function runBenchmark(code: string, iterations: number): BenchmarkResult {
+  const timings: number[] = [];
+
+  // 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 = performance.now();
+    fn();
+    const end = 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,
+  };
+}
+
+export function compareBenchmarks(
+  codeA: string,
+  labelA: string,
+  codeB: string,
+  labelB: string,
+  iterations: number
+): ComparisonResult {
+  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,
+  };
+}
+
+export function formatBenchmarkResult(result: BenchmarkResult): string {
+  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");
+}

package/src/tools/big-o-estimator.ts

@@ -0,0 +1,175 @@
+export type ComplexityClass =
+  | "O(1)"
+  | "O(log n)"
+  | "O(n)"
+  | "O(n log n)"
+  | "O(n^2)"
+  | "O(n^3)"
+  | "O(2^n)"
+  | "unknown";
+
+interface FitResult {
+  complexity: ComplexityClass;
+  r2: number;
+  description: string;
+}
+
+function linearRegression(
+  xs: number[],
+  ys: number[]
+): { slope: number; intercept: number; r2: number } {
+  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: number[],
+  times: number[],
+  transform: (n: number) => number,
+  label: ComplexityClass,
+  description: string
+): FitResult {
+  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 };
+}
+
+export interface BigOEstimate {
+  bestFit: ComplexityClass;
+  confidence: number;
+  allFits: Array<{ complexity: ComplexityClass; r2: number }>;
+  growthCurve: string;
+  summary: string;
+}
+
+export function estimateBigO(
+  inputSizes: number[],
+  executionTimesMs: number[]
+): BigOEstimate {
+  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: FitResult[] = [
+    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: number[], times: number[]): string {
+  const maxTime = Math.max(...times);
+  const maxBarWidth = 40;
+  const lines: string[] = [];
+
+  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");
+}