Algorate MCP Server 📊

A Model Context Protocol (MCP) server for comprehensive algorithm benchmarking, performance analysis, and optimization. Compare multiple implementations, detect performance bottlenecks, and get AI-driven optimization insights across JavaScript, TypeScript, and Python code.

🚀 Quick Start

Installation

Install globally via npm:

npm install -g @cmiretf/algorate-mcp

Or add to your project:

npm install @cmiretf/algorate-mcp

Usage

With MCP Inspector

Test the server interactively:

npm install -g @cmiretf/algorate-mcp
npx @modelcontextprotocol/inspector algorate

Or if installed locally:

npx @modelcontextprotocol/inspector node node_modules/algorate/dist/index.js

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "algorate": {
      "command": "npx",
      "args": ["-y", "@cmiretf/algorate-mcp"]
    }
  }
}

Or with a local installation:

{
  "mcpServers": {
    "algorate": {
      "command": "node",
      "args": ["/path/to/node_modules/algorate/dist/index.js"]
    }
  }
}

With Visual Studio Code / Cursor

Add to your mcp.json:

{
  "servers": {
    "algorate": {
      "command": "npx",
      "args": ["-y", "@cmiretf/algorate-mcp"]
    }
  }
}

Or with a local installation:

{
  "mcpServers": {
    "algorate": {
      "command": "node",
      "args": ["/path/to/node_modules/algorate/dist/index.js"]
    }
  }
}

🎯 Features

Algorithm Registration & Management

• Register Algorithms: Define custom algorithms with unique identifiers
• Multiple Implementations: Compare 2+ implementations of the same algorithm
• Language Support: JavaScript, TypeScript, and Python
• Automatic Detection: AI-powered algorithm detection from code

Performance Benchmarking

• Execution Metrics: Precise timing with warmup and measurement runs
• Memory Profiling: Track peak memory usage and memory trends
• Statistical Analysis: Mean, median, std deviation, P95, P99 percentiles
• Consistency Tracking: Identify variability and outliers

Advanced Features

• Workload Generation: Automatic test data generation for different input sizes
• Output Validation: Ensure correctness across all implementations
• Isolated Execution: Worker-based isolation for accurate measurements
• Result Storage: Persistent storage of benchmarks with versioning
• Performance Insights: Automatic detection of performance patterns

AI-Powered Analysis

• Code Optimization: Receive specific optimization recommendations
• Performance Comparison: Automated ranking and insights
• Bottleneck Detection: Identify slow operations and memory issues
• Query Engine: Natural language queries on benchmark results

📖 Available MCP Tools

Core Benchmarking Tools

register_algorithm

Register a new algorithm for benchmarking.

Parameters:

• name (string): Algorithm name (e.g., "Sorting", "Searching")
• description (string, optional): Detailed description

Example:

{
  "name": "QuickSort",
  "description": "Fast sorting algorithm using divide and conquer"
}

register_implementation

Add an implementation of an algorithm.

Parameters:

• algorithmId (string): ID of the algorithm
• name (string): Implementation name
• language (string): "javascript", "typescript", or "python"
• code (string): Function code
• functionName (string): Name of the exported function

register_test_case

Create a test case for benchmarking.

Parameters:

• name (string): Test case name
• inputSize (number): Size of input
• inputType (string): "array", "number", "string", "object"
• inputData (any): The actual input
• expectedOutput (any): Expected result for validation

run_benchmark

Execute a complete benchmark comparing implementations.

Parameters:

• algorithmId (string): Algorithm to benchmark
• testCaseId (string): Test case to use
• warmupRuns (number, optional): Warmup executions (default: 3)
• measurementRuns (number, optional): Measurement runs (default: 10)
• timeoutMs (number, optional): Timeout per execution in ms (default: 30000)
• validateOutput (boolean, optional): Enable validation (default: true)

Example:

{
  "algorithmId": "algo-123",
  "testCaseId": "test-456",
  "warmupRuns": 3,
  "measurementRuns": 10,
  "validateOutput": true
}

list_algorithms

List all registered algorithms.

Parameters:

None

list_implementations

List implementations, optionally filtered by algorithm.

Parameters:

• algorithmId (string, optional): Filter by algorithm ID

list_test_cases

List all registered test cases.

Parameters:

None

get_results

Get benchmark results for a specific implementation and test case.

Parameters:

• implementationId (string): Implementation ID
• testCaseId (string): Test case ID

Analysis & Insights Tools

get_algorithm_insights

Get AI-powered insights about algorithm performance.

Parameters:

• algorithmId (string): Algorithm to analyze

optimize_code

Receive specific optimization recommendations.

Parameters:

• code (string): Code to optimize
• language (string): "javascript", "typescript", or "python"
• benchmarkResults (object, optional): Previous benchmark results

query_results

Query benchmark results with natural language.

Parameters:

• query (string): Natural language question about results
• algorithmId (string, optional): Specific algorithm to query

generate_summary

Generate a comprehensive benchmark summary report.

Parameters:

• algorithmId (string): Algorithm to summarize
• includeCharts (boolean): Include visualization data

Workload & Detection Tools

generate_workload

Generate test data for different input sizes.

Parameters:

• type (string): "random", "sorted", "reverse", "nearly_sorted"
• size (number): Input size
• complexity (string): "low", "medium", "high"

detect_algorithm

AI-powered algorithm detection from code.

Parameters:

• code (string): Code to analyze
• language (string): "javascript", "typescript", or "python"

auto_detect_algorithms

Automatically detect algorithms in project files.

Parameters:

• directories (array of strings, optional): Directories to scan (default: src, examples)

auto_benchmark

Automatically run benchmarks for detected or registered algorithms.

Parameters:

• algorithmIds (array of strings, optional): Algorithm IDs to benchmark (empty = all)
• forceRefresh (boolean, optional): Force refresh even if cached results exist

Visualization & Query Tools

generate_chart

Generate performance chart for benchmark results.

Parameters:

• algorithmId (string): Algorithm ID
• testCaseId (string, optional): Test case ID

query_performance

Query performance analysis with automatic benchmark and summary.

Parameters:

• query (string): Query about algorithm performance (e.g., "sorting algorithms", "all algorithms")
• forceRefresh (boolean, optional): Force refresh even if cached results exist
• directories (array of strings, optional): Directories to scan for algorithms

benchmark_all

Automatically detect all algorithms, run benchmarks, and return formatted results (ONE-CLICK BENCHMARK).

Parameters:

• directories (array of strings, optional): Directories to scan (default: src, examples)
• filePath (string, optional): Specific file path to analyze (if provided, only analyzes this file)
• forceRefresh (boolean, optional): Force refresh even if cached results exist

📊 Metrics Explained

Key Metrics

• Execution Time (ms): Average time to run the algorithm
• Memory Peak (MB): Maximum memory used during execution
• Success Rate (%): Percentage of successful executions
• Std Deviation (ms): Consistency of results (lower = better)
• P95/P99: Latency in worst-case scenarios

Interpreting Results

• Lower Score = Better overall performance
• Mean < Median = Some slower outliers detected
• High StdDev = Inconsistent results (increase warmup runs)
• High Success Rate = Stable implementation

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone the repository

git clone <your-repo-url>
cd algorate

# Install dependencies

npm install

# Build the project

npm run build

Development Commands

# Development with auto-reload

npm run dev

# Build TypeScript

npm run build

# Run built version

npm start

# Test with MCP Inspector (built version)

npm run inspect

# Test with MCP Inspector (dev version)

npm run inspect:dev

# Run examples

npm run example:simple
npm run example:sorting

# Run tests

npm test

🧪 Testing

Test the server interactively with the MCP Inspector:

npm run inspect

Or run the examples:

# Quick validation

npm run example:simple

# Complete benchmark with multiple implementations

npm run example:sorting

See TESTING_GUIDE.md for comprehensive testing instructions.

🔗 Integration Examples

Git Hooks

Add to .git/hooks/pre-commit:

#!/bin/bash

# Run quick benchmark validation

npm run example:simple

CI/CD

# GitHub Actions example

- name: Run Algorithm Benchmarks
  run: |
  npm install
  npm run build
  npm test
  npm run example:sorting

📚 Documentation

• Testing Guide - Comprehensive testing and validation guide
• Inspector Guide - MCP Inspector usage and tips
• API Reference - Detailed tool documentation
• Examples - Code examples and usage patterns

💡 Use Cases

• Algorithm Comparison: Compare 2+ implementations objectively
• Performance Regression: Detect performance degradation in CI/CD
• Code Optimization: Get specific recommendations for improvement
• Learning: Understand algorithm performance characteristics
• Benchmark Storage: Track performance over time and versions
• Team Standards: Enforce performance baselines across teams

🌟 Supported Languages

• JavaScript (ES6+)
• TypeScript
• Python (3.7+)

🎨 Example Workflow

import { Orchestrator } from "@cmiretf/algorate";

const orchestrator = new Orchestrator();

// 1. Register algorithm
const algo = orchestrator.registerAlgorithm("BubbleSort");

// 2. Register implementations
const impl1 = orchestrator.registerImplementation(
  algo.id,
  "Basic Implementation",
  "javascript",
  "function bubbleSort(arr) { /_ code _/ }",
  "bubbleSort"
);

const impl2 = orchestrator.registerImplementation(
  algo.id,
  "Optimized Implementation",
  "javascript",
  "function bubbleSortOptimized(arr) { /_ code _/ }",
  "bubbleSortOptimized"
);

// 3. Create test cases
const test = orchestrator.registerTestCase(
  "Random array 1000 elements",
  1000,
  "array",
  Array.from({ length: 1000 }, () => Math.random()),
  "sorted array"
);

// 4. Run benchmark
const result = await orchestrator.runBenchmark(algo.id, test.id, {
  warmupRuns: 3,
  measurementRuns: 10,
  validateOutput: true,
});

// 5. Get insights
const insights = await orchestrator.getAlgorithmInsights(algo.id);
console.log(insights); // Performance analysis and recommendations

🔍 Severity Levels

• error: Critical execution failures or validation errors
• warning: Performance anomalies or high variability
• info: Optimization suggestions and observations

📈 Performance Benchmarking Best Practices

1. Warmup Runs: Use 2-3 warmup runs to stabilize the JIT
2. Measurement Runs: 5-10 runs for reliable statistics
3. Consistent Environment: Close unnecessary applications
4. Large Inputs: Test with representative data sizes
5. Validation: Always validate correctness before measuring

See TESTING_GUIDE.md for detailed best practices.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - an open source license that allows you to use, modify, and distribute this software freely.

What this means:

• ✅ Free to use: You can use this software in any project, commercial or personal
• ✅ Open source: The source code is publicly available and can be inspected, modified, and improved
• ✅ Modify freely: You can adapt the code to fit your specific needs
• ✅ Distribute: You can share the original or modified versions
• ✅ Private use: You can use it in proprietary projects without disclosing your source code

License Text

Copyright (c) 2026 Carlos Miret Fiuza

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🌐 Supported Platforms

• Node.js 18+
• Deno (with appropriate configuration)
• Browser environments (with bundling)

🔐 Security

⚠️ Remote Code Execution Risk: This server compiles and runs JavaScript supplied by the MCP caller inside the Node.js process. Worker threads provide fault isolation, not a security sandbox — injected code still has full access to the filesystem, network, environment variables, and child processes of the user running the server. Treat this tool as you would a local REPL.

Enabling code execution

For safety, the tools that accept or execute caller-supplied code are disabled by default. Enable them only when the MCP client is fully trusted by setting the environment variable:

ALGORATE_ALLOW_CODE_EXECUTION=1

Affected tools: register_implementation, run_benchmark, auto_benchmark, benchmark_all.

Example claude_desktop_config.json entry:

{
  "mcpServers": {
    "algorate": {
      "command": "npx",
      "args": ["-y", "@cmiretf/algorate-mcp"],
      "env": {
        "ALGORATE_ALLOW_CODE_EXECUTION": "1"
      }
    }
  }
}

Without this variable the execution tools respond with a safety error. Read-only tools (list_algorithms, get_results, query_performance, generate_chart, etc.) keep working.

Other defenses

• Isolated Execution: Uses Worker threads to reduce fault blast radius (not a security boundary).
• Timeout Protection: Prevents infinite loops and hanging processes.
• Memory Monitoring: Tracks memory consumption during runs.
• UUID-validated paths: generate_chart rejects non-UUID algorithmId / testCaseId to prevent path traversal into chart file writes.
• Input Validation: All tool arguments are parsed with zod before use.

📞 Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check TESTING_GUIDE.md for troubleshooting
• Review INSPECTOR_GUIDE.md for MCP usage

---

👤 Author

This project is developed and maintained by Carlos Miret Fiuza.
Feel free to connect on LinkedIn for collaborations, suggestions, or any questions related to Algorate MCP Server!