Math MCP Server

A high-performance, production-ready MCP (Model Context Protocol) server providing secure mathematical computation capabilities powered by mathjs, with Multi-Tier Acceleration through WebWorkers, WebAssembly (WASM), and comprehensive security features.

🚀 Performance

This server features intelligent multi-tier acceleration providing up to 1920x speedup compared to pure JavaScript:

• 🎯 Intelligent Routing: Automatically selects optimal acceleration tier (mathjs → WASM → Workers → GPU)

• ⚡ WebWorkers: 3-4x faster than WASM for large operations (multi-threaded)

• 🔥 WASM: 14x faster than mathjs for medium operations (single-threaded)

• 🚄 WebGPU: 50-100x faster than Workers for massive operations (GPU, future)

• 🔄 Graceful Fallback: GPU → Workers → WASM → mathjs (never fails)

• ✅ Zero Breaking Changes: 100% backward compatible API

Performance Results

Current (Node.js): Up to 143x speedup with WebWorkers Future (Browser): Up to 10000x speedup with WebGPU

For detailed benchmarks and architecture, see docs/ACCELERATION_ARCHITECTURE.md.

✨ Features

⚡ Multi-Tier Acceleration

• Intelligent Routing: Automatically routes operations through optimal acceleration tier

• WebWorker Pool: Dynamic 2-8 worker threads for parallel processing

• WASM Acceleration: AssemblyScript-compiled modules for medium operations

• WebGPU Ready: GPU compute shaders (browser/Deno support planned)

• Performance Tracking: Monitor acceleration tier usage and statistics

• Zero Configuration: Works out-of-the-box with automatic optimization

🔐 Security Features

• Rate Limiting: Token bucket algorithm prevents DoS attacks

  • Configurable request limits per time window

  • Concurrent request limits (max in-flight operations)

  • Queue size limits for pending requests

• WASM Integrity Verification: Cryptographic SHA-256 verification of WASM binaries

  • Prevents execution of tampered modules

  • Automatic verification at runtime

• Expression Sandboxing: AST validation prevents code injection

  • Whitelist-based approach for safe operations

  • Blocks dangerous functions and assignments

• Input Validation: Comprehensive validation for all inputs

  • Length limits and format validation

  • Size limits prevent resource exhaustion

• Timeout Protection: Configurable timeout for all operations

• Type Safety: Strict TypeScript with enforced type checking

⚡ Performance Optimizations

• Expression Caching: LRU cache for parsed/compiled expressions

  • Reduces repeated parsing overhead

  • Configurable cache size (default: 1000 entries)

• Early Size Checks: Prevents event loop blocking from oversized inputs

• Efficient Logging: Proper stream separation (stdout/stderr)

📊 Observability & Production Readiness ⚡ NEW in v3.2.0

• Prometheus Metrics Export: Production-grade monitoring

  • Operation duration histograms with configurable buckets

  • Operation counters by type, tier, and status

  • Real-time queue size and worker count gauges

  • Rate limit hits and backpressure event tracking

  • Cache hit/miss rates and effectiveness metrics

  • HTTP endpoint on port 9090 for Prometheus scraping

• Health Check System: Kubernetes-compatible probes

  • GET /health - Overall system health (healthy/degraded/unhealthy)

  • GET /health/live - Liveness probe (always returns true)

  • GET /health/ready - Readiness probe (based on health status)

  • Component-level checks: WASM, rate limiter, memory usage

  • Detailed diagnostics with timestamps

• Telemetry HTTP Server: Standalone observability server

  • Runs on port 9090 (configurable)

  • Metrics in Prometheus text format

  • JSON metrics export via /metrics/json

  • Health status in JSON format

  • No impact on main server performance

• Backpressure Management: Intelligent queue overflow handling

  • REJECT Strategy: Fast fail when at capacity (low latency)

  • WAIT Strategy: Queue with timeout (max throughput)

  • SHED Strategy: Drop oldest tasks (favor fresh requests)

  • Event-driven monitoring with backpressure events

  • Automatic queue size and wait time tracking

• Dependency Injection Architecture: Clean, testable design

  • Constructor injection for worker pools and rate limiters

  • Interface-based abstractions for easy mocking

  • Improved test coverage (721 total tests, 92% security coverage)

  • Reduced coupling between components

🛡️ Comprehensive Security Testing ⚡ NEW in v3.2.0

• 119 Security Tests: Multi-layered security validation

  • Injection Prevention: 36 tests for code/command injection

  • DoS Protection: 28 tests for rate limiting and resource exhaustion

  • Fuzzing: 24 tests with random/malformed inputs

  • Bounds Testing: 31 tests for size limits and edge cases

  • 92% Pass Rate: 110/119 tests passing, actively maintained

• WASM Security: Integrity verification and sandboxing

  • SHA-256 cryptographic verification of all WASM binaries

  • Memory isolation between workers and main thread

  • Automatic fallback on integrity failures

⚡ Lazy Loading & Faster Startup ⚡ NEW in v3.4.0

• Lazy WASM Initialization: WASM modules load on-demand at first use

  • No startup overhead until acceleration is needed

  • Thread-safe concurrent initialization (Promise-based)

  • Reduces cold start time for simple operations

• Dynamic GPU Import: GPU module only loads when GPU is actually used

  • No browser/GPU detection overhead at startup

  • Cleaner module dependency graph

• Worker Pool On-Demand: Workers created lazily when needed

🔧 Codebase Refactoring ⚡ NEW in v3.5.0

• 44% Code Reduction: Complete refactoring across 7 sprints

  • Sprint 1-3: WASM wrapper, acceleration router, tool handlers optimization

  • Sprint 4: Lazy loading implementation

  • Sprint 5-7: Documentation, dead code removal, worker infrastructure

• Generic Parallel Executor Framework: Type-safe parallel operation pattern

  • Unified chunking utilities for arrays and matrices

  • Configurable merge strategies (sum, min, max, concat)

  • Foundation for future parallel operation extensions

• Improved Type Safety: Better generic constraints and DI patterns

7 Mathematical Tools

1. evaluate - Evaluate mathematical expressions with variables

2. simplify - Simplify algebraic expressions

3. derivative - Calculate derivatives

4. solve - Solve equations

5. matrix_operations ⚡ - Matrix operations (WASM-accelerated)

6. statistics ⚡ - Statistical calculations (WASM-accelerated)

7. unit_conversion - Convert between units

⚡ = WASM-accelerated for large inputs

Example Usage

📦 Installation

Requirements

Before installing, ensure you have:

• Node.js: ≥18.0.0 (required for worker_threads and ESM support)

• npm: ≥8.0.0

• Platform: Windows, macOS, or Linux

• Memory: Minimum 2GB RAM (4GB+ recommended for large operations)

Quick Start

Verify Installation

After installation, verify everything is working correctly:

Expected output from tests:

Integration with Claude Desktop

Add to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop and start using math tools!

Integration with Claude CLI

🧮 Tools Documentation

1. evaluate

Evaluate mathematical expressions with optional variables.

Parameters:

• expression (string): Mathematical expression to evaluate

• scope (object, optional): Variables to use in the expression

Examples:

2. simplify

Simplify mathematical expressions.

Parameters:

• expression (string): Expression to simplify

Examples:

3. derivative

Calculate derivatives of expressions.

Parameters:

• expression (string): Expression to differentiate

• variable (string): Variable to differentiate with respect to

Examples:

4. solve

Solve equations.

Parameters:

• equation (string): Equation to solve

• variable (string): Variable to solve for

Examples:

5. matrix_operations (Multi-Tier Accelerated ⚡⚡⚡)

Perform matrix operations with intelligent multi-tier acceleration.

Parameters:

• operation (string): Operation to perform

  • multiply, inverse, determinant, transpose, eigenvalues, add, subtract

• matrix_a (string): First matrix in JSON format

• matrix_b (string, optional): Second matrix (for binary operations)

Acceleration Tiers:

• mathjs (< 10×10): Pure JavaScript, no overhead

• WASM (10-100): Single-threaded, 8-17x faster

• WebWorkers (100-500): Multi-threaded, 32x faster ⚡ NEW

• WebGPU (500+): GPU-accelerated, 1920x faster (future) ⚡⚡⚡

Examples:

6. statistics (Multi-Tier Accelerated ⚡⚡⚡)

Calculate statistical values with intelligent multi-tier acceleration.

Parameters:

• operation (string): Statistical operation

  • mean, median, mode, std, variance, min, max, sum, product

• data (string): Data array in JSON format

Acceleration Tiers:

• mathjs (< 100): Pure JavaScript, no overhead

• WASM (100-100K): Single-threaded, 15-42x faster

• WebWorkers (100K-1M): Multi-threaded, 125x faster ⚡ NEW

• WebGPU (1M+): GPU-accelerated, 10000x faster (future) ⚡⚡⚡

Examples:

7. unit_conversion

Convert between units.

Parameters:

• value (string): Value with unit (e.g., "5 inches")

• target_unit (string): Target unit (e.g., "cm")

Examples:

🔧 How Multi-Tier Acceleration Works

The server intelligently routes operations through optimal acceleration tiers:

Graceful Fallback Chain:

If any tier fails, automatically falls back to the next tier. Never fails!

📊 Architecture

Architecture Benefits:

• Intelligent routing based on operation size

• Parallel processing for large operations

• GPU acceleration for massive operations (future)

• Graceful fallback at every tier

• Zero configuration required

• Automatic performance optimization

📁 Project Structure

🧪 Development

📚 Documentation

Core Documentation

• docs/README.md - ⚡ NEW v3.2.0: Complete documentation index

• ACCELERATION_ARCHITECTURE.md - Multi-tier acceleration architecture guide

• BUILD_GUIDE.md - Build and compilation guide

• DEPLOYMENT_PLAN.md - Production deployment instructions

• IMPLEMENTATION_PLAN.md - Implementation strategy and architecture

• SPRINT_9_PLAN.md - ⚡ NEW v3.2.0: Sprint 9 observability & security features

• PRODUCT_SPECIFICATION.md - Complete product specification

Code Quality & Review

• docs/code-review/CODE_REVIEW.md - ⚡ NEW v3.2.0: Initial code review

• docs/code-review/CODE_REVIEW_ANALYSIS.md - ⚡ NEW v3.2.0: Detailed analysis

• docs/code-review/CODE_QUALITY_IMPROVEMENTS.md - ⚡ NEW v3.2.0: Quality tracking

Development Guides

• STYLE_GUIDE.md - Coding standards and conventions

• TEST_GUIDE.md - Testing procedures and guidelines

• TEST_VERIFICATION_PLAN.md - Test verification strategy

• BENCHMARKS.md - Performance benchmarks and results

Project Management

• docs/planning/IMPLEMENTATION_PLAN_VERIFICATION.md - ⚡ NEW v3.2.0: Verification report

• docs/planning/REFACTORING_PLAN.md - ⚡ COMPLETE v3.5.0: All 7 sprints done (44% code reduction)

• docs/planning/PROJECT_HISTORY.md - ⚡ NEW v3.2.0: Project evolution timeline

• CHANGELOG.md - Version history and changes

• CONTRIBUTING.md - Contribution guidelines

• SECURITY.md - Security policy

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Make your changes

4. Run tests (npm test)

5. Commit your changes (git commit -m 'feat: add amazing feature')

6. Push to the branch (git push origin feature/amazing-feature)

7. Open a Pull Request

🔒 Security

See SECURITY.md for security policy and vulnerability reporting.

🐛 Troubleshooting

Worker Pool Issues

Workers Fail to Initialize

Symptoms:

Solutions:

1. Verify Node.js version:

   node --version # Must be v18.0.0 or higher

2. Check worker_threads support:

   // test-workers.js try { const { Worker } = require('worker_threads'); console.log('✓ worker_threads available'); } catch (err) { console.error('✗ worker_threads not available:', err.message); }

3. Rebuild native modules (if needed):

   npm rebuild npm install

4. Platform-specific issues:

   • Docker: Ensure Node.js base image is v18+

   • WSL/Windows: May need --experimental-worker flag (Node <16)

   • Alpine Linux: Use node package, not nodejs-current

Worker Crashes Repeatedly

Symptoms:

Solutions:

1. Enable debug logging:

   LOG_LEVEL=debug npm start

2. Increase Node.js memory limit:

   node --max-old-space-size=4096 dist/index-wasm.js

3. Reduce worker count:

   MAX_WORKERS=2 npm start

4. Check for WASM corruption:

   # Rebuild WASM modules cd wasm npm install npx gulp cd .. npm run generate:hashes

5. Monitor worker health:

   ENABLE_PERF_LOGGING=true npm start # Watch for patterns in worker exits

Operations Timeout

Symptoms:

Solutions:

1. Increase operation timeout:

   OPERATION_TIMEOUT=60000 npm start

2. Increase task timeout:

   TASK_TIMEOUT=60000 npm start

3. Check input size (may be too large):

   • Maximum matrix size: 1000×1000 (configurable via MAX_MATRIX_SIZE)

   • Maximum array length: 100,000 (configurable via MAX_ARRAY_LENGTH)

4. Monitor worker pool status:

   ENABLE_PERF_LOGGING=true npm start # Check for: "Worker pool at capacity"

5. Scale up workers:

   MIN_WORKERS=4 MAX_WORKERS=8 npm start

Worker Pool Not Scaling

Symptoms:

Solutions:

1. Verify MIN_WORKERS configuration:

   # Set MIN_WORKERS=0 for auto-scaling MIN_WORKERS=0 npm start # Or keep workers warm MIN_WORKERS=2 npm start

2. Adjust idle timeout:

   # Workers terminate after 60s idle by default WORKER_IDLE_TIMEOUT=120000 npm start # 2 minutes

3. Monitor scaling behavior:

   LOG_LEVEL=debug npm start # Look for: "Pool empty, creating worker on-demand" # Look for: "Terminating idle worker"

WASM Issues

WASM Integrity Verification Fails

Symptoms:

Solutions:

1. Rebuild WASM modules:

   cd wasm npm install npx gulp cd ..

2. Regenerate hash manifest:

   npm run generate:hashes

3. Disable integrity checks (development only):

   DISABLE_WASM_INTEGRITY=true npm start

4. Verify file permissions:

   ls -l wasm/build/*.wasm # Should be readable by current user

WASM Module Not Loading

Symptoms:

Solutions:

1. Check WASM files exist:

   ls wasm/build/ # Should contain: release.wasm, debug.wasm

2. Rebuild from scratch:

   cd wasm rm -rf node_modules build npm install npx gulp cd ..

3. Verify AssemblyScript toolchain:

   cd wasm npx asc --version # Should show AssemblyScript compiler version

4. Check Node.js WASM support:

   // test-wasm.js try { new WebAssembly.Module(new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0])); console.log('✓ WASM supported'); } catch (err) { console.error('✗ WASM not supported:', err.message); }

Acceleration Not Working

Check server startup logs:

Common Issues:

1. Input sizes too small - Acceleration only activates above thresholds:

   • WASM: 10×10+ matrices, 100+ elements

   • Workers: 100×100+ matrices, 100k+ elements

2. WASM not initialized - Check startup logs:

   [INFO] WASM modules initialized successfully [INFO] WorkerPool initialized successfully { activeWorkers: 2 }

3. Using wrong entry point:

   # ✓ Correct (with acceleration) node dist/index-wasm.js # ✗ Wrong (mathjs only) node dist/index.js

Performance Not Improving

1. Verify using index-wasm.js not index.js

2. Check input sizes exceed acceleration thresholds (see docs/BENCHMARKS.md)

3. Monitor routing statistics in logs:

   ENABLE_PERF_LOGGING=true npm start # Look for: "WASM calls: 70%, mathjs calls: 30%"

4. Ensure worker threads are available (node --version >= 18)

5. Check system resources:

   # Monitor CPU/memory during operations top -p $(pgrep -f "node.*index-wasm")

Integration Tests Failing

Expected output:

Common failures:

1. WASM modules not built:

   npm run build:wasm npm run generate:hashes

2. TypeScript compilation errors:

   npm run type-check # Fix any errors before running tests

3. Node.js version too old:

   node --version # Must be >=18.0.0 nvm install 18 # If using nvm

Memory Issues

High Memory Usage

Symptoms:

Solutions:

1. Scale down workers:

   MIN_WORKERS=0 MAX_WORKERS=2 npm start

2. Enable auto-scaling to zero:

   MIN_WORKERS=0 WORKER_IDLE_TIMEOUT=30000 npm start

3. Increase Node.js heap:

   node --max-old-space-size=2048 dist/index-wasm.js

4. Disable performance tracking:

   DISABLE_PERF_TRACKING=true npm start

Memory Leaks

Symptoms:

Solutions:

1. Monitor worker lifecycle:

   LOG_LEVEL=debug npm start # Look for: "Terminating idle worker" # Check: workers.size in logs

2. Force garbage collection (debugging):

   node --expose-gc dist/index-wasm.js

3. Reduce worker idle timeout:

   WORKER_IDLE_TIMEOUT=30000 npm start # 30 seconds

Getting Help

If you're still experiencing issues:

1. Enable debug logging:

   LOG_LEVEL=debug npm start 2>&1 | tee debug.log

2. Collect system information:

   node --version npm --version uname -a # Linux/macOS systeminfo # Windows

3. Run diagnostic:

   npm run type-check npm test npm run lint

4. Create an issue:

   • URL: https://github.com/danielsimonjr/math-mcp/issues

   • Include: Debug logs, system info, steps to reproduce

   • Attach: Relevant error messages

Performance Tuning

For optimal performance, see:

• Benchmark documentation: docs/BENCHMARKS.md

• Threshold configuration: src/wasm-wrapper.ts:39-74

• Worker pool tuning: Environment variables section above

Expected: 11/11 tests passing

🔧 Configuration

The server supports several environment variables for customization:

🛠️ Development

Code Quality Tools

Quality Features

• ESLint: TypeScript + JSDoc validation

• Prettier: Consistent code formatting

• Husky: Git hooks for pre-commit quality checks

• Vitest: Modern, fast testing framework

• 100% JSDoc Coverage: All public APIs documented

📄 License

ISC License - see LICENSE file for details.

🙏 Acknowledgments

• mathjs - Excellent JavaScript math library

• AssemblyScript - TypeScript-to-WASM compiler

• MCP SDK - Model Context Protocol implementation

Made with ❤️ by the math-mcp contributors