# Math MCP Server
[](https://github.com/danielsimonjr/math-mcp/actions)
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org/)
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
| Operation | Size | mathjs | WASM | Workers | GPU (future) | Best Speedup |
|-----------|------|--------|------|---------|--------------|--------------|
| Matrix Multiply | 10×10 | 0.5ms | 0.06ms | - | - | **8x** |
| Matrix Multiply | 100×100 | 95ms | 12ms | 3ms | - | **32x** |
| Matrix Multiply | 1000×1000 | 96s | 12s | 3s | 0.05s | **1920x** |
| Statistics (Mean) | 1K elements | 0.1ms | 0.003ms | - | - | **33x** |
| Statistics (Mean) | 100K elements | 10ms | 0.3ms | 0.08ms | - | **125x** |
| Statistics (Mean) | 10M elements | 1000ms | 25ms | 7ms | 0.1ms | **10000x** |
**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](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
```javascript
// Matrix operations (WASM-accelerated for 10x10+)
matrix_operations("determinant", "[[1,2],[3,4]]") // -2
// Statistics (WASM-accelerated for 100+ elements)
// Note: mode returns an array
statistics("mean", "[1,2,3,4,5]") // 3
statistics("mode", "[1,2,2,3,4]") // [2]
// Symbolic math
derivative("x^2", "x") // "2 * x"
simplify("2 * x + x") // "3 * x"
// Unit conversion
unit_conversion("5 inches", "cm") // "12.7 cm"
```
## 📦 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
```bash
# Clone the repository
git clone https://github.com/danielsimonjr/math-mcp.git
cd math-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Build WASM modules (platform-specific)
# Linux/macOS:
cd wasm && npm install && npx gulp && cd ..
# Windows (PowerShell):
# cd wasm; npm install; npx gulp; cd ..
# Run tests
npm test
```
### Verify Installation
After installation, verify everything is working correctly:
```bash
# 1. Check Node.js version
node --version # Should show v18.0.0 or higher
# 2. Verify TypeScript compilation
npm run type-check # Should complete without errors
# 3. Run integration tests
npm test # Should show "11/11 tests passing"
# 4. Check WASM modules are built
ls -l wasm/build/*.wasm # Should see release.wasm and debug.wasm
# Windows: dir wasm\build\*.wasm
```
**Expected output from tests:**
```
✓ All integration tests passed!
✓ WASM integration working correctly
✓ Threshold-based routing working
Success rate: 100.0%
```
### Integration with Claude Desktop
Add to your Claude Desktop config file:
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"math-mcp": {
"command": "node",
"args": ["C:/path/to/math-mcp/dist/index-wasm.js"]
}
}
}
```
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"math-mcp": {
"command": "node",
"args": ["/path/to/math-mcp/dist/index-wasm.js"]
}
}
}
```
Restart Claude Desktop and start using math tools!
### Integration with Claude CLI
```bash
claude mcp add --transport stdio math-mcp node /path/to/math-mcp/dist/index-wasm.js
```
## 🧮 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:**
```javascript
evaluate("2 + 2") // 4
evaluate("sqrt(16)") // 4
evaluate("x^2 + 2*x", {x: 5}) // 35
evaluate("derivative(x^2, x)") // "2 * x"
```
### 2. simplify
Simplify mathematical expressions.
**Parameters:**
- `expression` (string): Expression to simplify
**Examples:**
```javascript
simplify("2 * x + x") // "3 * x"
simplify("(x + 2)^2") // "x^2 + 4*x + 4"
```
### 3. derivative
Calculate derivatives of expressions.
**Parameters:**
- `expression` (string): Expression to differentiate
- `variable` (string): Variable to differentiate with respect to
**Examples:**
```javascript
derivative("x^2", "x") // "2 * x"
derivative("sin(x)", "x") // "cos(x)"
```
### 4. solve
Solve equations.
**Parameters:**
- `equation` (string): Equation to solve
- `variable` (string): Variable to solve for
**Examples:**
```javascript
solve("x^2 - 4 = 0", "x") // Solutions for x
solve("2*x + 3 = 7", "x") // x = 2
```
### 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:**
```javascript
matrix_operations("determinant", "[[1,2],[3,4]]") // -2
matrix_operations("multiply", "[[1,2],[3,4]]", "[[5,6],[7,8]]") // [[19,22],[43,50]]
matrix_operations("transpose", "[[1,2,3],[4,5,6]]") // [[1,4],[2,5],[3,6]]
matrix_operations("add", "[[1,2],[3,4]]", "[[5,6],[7,8]]") // [[6,8],[10,12]]
matrix_operations("subtract", "[[5,6],[7,8]]", "[[1,2],[3,4]]") // [[4,4],[4,4]]
```
### 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:**
```javascript
statistics("mean", "[1,2,3,4,5]") // 3
statistics("std", "[2,4,4,4,5,5,7,9]") // 2
statistics("median", "[1,2,3,4,5]") // 3
statistics("mode", "[1,2,2,3,4,4,4,5]") // 4
statistics("product", "[2,3,4]") // 24
```
### 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:**
```javascript
unit_conversion("5 inches", "cm") // "12.7 cm"
unit_conversion("100 fahrenheit", "celsius") // "37.78 celsius"
unit_conversion("50 mph", "km/h") // "80.47 km/h"
```
## 🔧 How Multi-Tier Acceleration Works
The server intelligently routes operations through optimal acceleration tiers:
```
Small Data (< 10×10)
↓
mathjs ────────────────→ Result
Fast for small ops, no overhead
Medium Data (10-100)
↓
WASM ──────────────────→ Result
14x faster, single-threaded
Large Data (100-500)
↓
WebWorkers ────────────→ Result
56x faster, multi-threaded (3-4x × WASM)
Massive Data (500+)
↓
WebGPU ────────────────→ Result
5600x faster, GPU-accelerated (future)
```
**Graceful Fallback Chain:**
```
GPU → Workers → WASM → mathjs
```
If any tier fails, automatically falls back to the next tier. Never fails!
## 📊 Architecture
```
MCP Server (index-wasm.ts)
↓
Acceleration Router (acceleration-router.ts)
↓
Size Analysis & Tier Selection
↓
┌───────┬──────────┬──────────────┬──────────┐
│ │ │ │ │
▼ ▼ ▼ ▼ │
mathjs WASM WebWorkers WebGPU │
(small) (medium) (large) (massive) │
│ │ │ │ │
│ │ ┌────┴─────┐ │ │
│ │ │ Worker 1 │ │ │
│ │ │ Worker 2 │ │ │
│ │ │ Worker N │ │ │
│ │ │ (WASM) │ │ │
│ │ └──────────┘ │ │
└───────┴──────────┴──────────────┴────────┘
↓
Result
```
**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
```
math-mcp/
├── src/
│ ├── index.ts # Original mathjs-only server
│ ├── index-wasm.ts # Multi-tier accelerated server (production)
│ ├── acceleration-router.ts # ⚡ Intelligent routing logic (v3.0.0)
│ ├── acceleration-adapter.ts # ⚡ Clean adapter interface (v3.0.0)
│ ├── wasm-wrapper.ts # WASM integration layer
│ ├── tool-handlers.ts # Business logic for all tools
│ ├── validation.ts # Input validation & security
│ ├── errors.ts # Custom error types
│ ├── utils.ts # Utilities and logging
│ ├── rate-limiter.ts # Token bucket rate limiting
│ ├── health.ts # ⚡ Health check system (v3.2.0)
│ ├── telemetry/ # ⚡ Observability system (v3.2.0)
│ │ ├── metrics.ts # Prometheus metrics collection
│ │ └── server.ts # HTTP telemetry server (port 9090)
│ ├── workers/ # ⚡ WebWorker infrastructure (v3.0.0)
│ │ ├── worker-pool.ts # Dynamic worker pool with DI (v3.2.0)
│ │ ├── parallel-executor.ts # ⚡ Generic parallel framework (v3.5.0)
│ │ ├── backpressure-queue.ts # ⚡ Backpressure strategies (v3.2.0)
│ │ ├── task-queue.ts # Priority-based task scheduling
│ │ ├── math-worker.ts # Worker thread implementation
│ │ ├── parallel-matrix.ts # Parallel matrix operations
│ │ ├── parallel-stats.ts # Parallel statistics
│ │ ├── chunk-utils.ts # Data chunking utilities
│ │ └── worker-types.ts # Type definitions
│ └── gpu/ # ⚡ WebGPU acceleration (future)
│ └── webgpu-wrapper.ts # GPU compute shaders
├── wasm/
│ ├── assembly/ # AssemblyScript source
│ │ ├── matrix/
│ │ └── statistics/
│ ├── bindings/ # JavaScript bindings
│ ├── build/ # Compiled WASM
│ ├── tests/ # WASM tests
│ └── benchmarks/ # Performance benchmarks
├── test/
│ ├── integration-test.js # Integration tests (11/11 passing)
│ ├── unit/ # ⚡ Unit tests (v3.2.0)
│ │ ├── telemetry/
│ │ │ └── metrics.test.ts # Prometheus metrics tests (36 tests)
│ │ ├── health.test.ts # Health check tests (30 tests)
│ │ └── backpressure.test.ts # Backpressure tests (33 tests)
│ └── security/ # ⚡ Security test suite (v3.2.0)
│ ├── injection.test.ts # Injection prevention (36 tests)
│ ├── dos.test.ts # DoS protection (28 tests)
│ ├── fuzzing.test.ts # Fuzzing tests (24 tests)
│ └── bounds.test.ts # Bounds testing (31 tests)
├── dist/ # Compiled JavaScript
├── docs/ # Documentation
│ ├── README.md # ⚡ Documentation index (v3.2.0)
│ ├── ACCELERATION_ARCHITECTURE.md # Multi-tier architecture guide
│ ├── BUILD_GUIDE.md
│ ├── DEPLOYMENT_PLAN.md
│ ├── IMPLEMENTATION_PLAN.md
│ ├── PRODUCT_SPECIFICATION.md
│ ├── SPRINT_9_PLAN.md # ⚡ Sprint 9 planning (v3.2.0)
│ ├── STYLE_GUIDE.md
│ ├── TEST_GUIDE.md
│ ├── TEST_VERIFICATION_PLAN.md
│ ├── BENCHMARKS.md
│ ├── code-review/ # ⚡ Code review reports (v3.2.0)
│ │ ├── CODE_REVIEW.md
│ │ ├── CODE_REVIEW_ANALYSIS.md
│ │ └── CODE_QUALITY_IMPROVEMENTS.md
│ ├── planning/ # ⚡ Planning documents (v3.2.0)
│ │ ├── IMPLEMENTATION_PLAN_VERIFICATION.md
│ │ ├── REFACTORING_PLAN.md
│ │ └── PROJECT_HISTORY.md
│ └── pull-requests/ # ⚡ PR documentation (v3.2.0)
│ ├── PR_DESCRIPTION.md
│ └── PR_TASK_19.md
├── .github/
│ ├── workflows/ci.yml
│ └── ISSUE_TEMPLATE/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE
└── package.json
```
## 🧪 Development
```bash
# Build TypeScript
npm run build
# Build WASM modules
npm run build:wasm
# Build everything
npm run build:all
# Run tests
npm test
# Run server
npm start
# Development mode
npm run dev
```
## 📚 Documentation
### Core Documentation
- **[docs/README.md](docs/README.md)** - ⚡ NEW v3.2.0: Complete documentation index
- **[ACCELERATION_ARCHITECTURE.md](docs/ACCELERATION_ARCHITECTURE.md)** - Multi-tier acceleration architecture guide
- **[BUILD_GUIDE.md](docs/BUILD_GUIDE.md)** - Build and compilation guide
- **[DEPLOYMENT_PLAN.md](docs/DEPLOYMENT_PLAN.md)** - Production deployment instructions
- **[IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md)** - Implementation strategy and architecture
- **[SPRINT_9_PLAN.md](docs/SPRINT_9_PLAN.md)** - ⚡ NEW v3.2.0: Sprint 9 observability & security features
- **[PRODUCT_SPECIFICATION.md](docs/PRODUCT_SPECIFICATION.md)** - Complete product specification
### Code Quality & Review
- **[docs/code-review/CODE_REVIEW.md](docs/code-review/CODE_REVIEW.md)** - ⚡ NEW v3.2.0: Initial code review
- **[docs/code-review/CODE_REVIEW_ANALYSIS.md](docs/code-review/CODE_REVIEW_ANALYSIS.md)** - ⚡ NEW v3.2.0: Detailed analysis
- **[docs/code-review/CODE_QUALITY_IMPROVEMENTS.md](docs/code-review/CODE_QUALITY_IMPROVEMENTS.md)** - ⚡ NEW v3.2.0: Quality tracking
### Development Guides
- **[STYLE_GUIDE.md](docs/STYLE_GUIDE.md)** - Coding standards and conventions
- **[TEST_GUIDE.md](docs/TEST_GUIDE.md)** - Testing procedures and guidelines
- **[TEST_VERIFICATION_PLAN.md](docs/TEST_VERIFICATION_PLAN.md)** - Test verification strategy
- **[BENCHMARKS.md](docs/BENCHMARKS.md)** - Performance benchmarks and results
### Project Management
- **[docs/planning/IMPLEMENTATION_PLAN_VERIFICATION.md](docs/planning/IMPLEMENTATION_PLAN_VERIFICATION.md)** - ⚡ NEW v3.2.0: Verification report
- **[docs/planning/REFACTORING_PLAN.md](docs/planning/REFACTORING_PLAN.md)** - ⚡ COMPLETE v3.5.0: All 7 sprints done (44% code reduction)
- **[docs/planning/PROJECT_HISTORY.md](docs/planning/PROJECT_HISTORY.md)** - ⚡ NEW v3.2.0: Project evolution timeline
- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines
- **[SECURITY.md](SECURITY.md)** - Security policy
## 🤝 Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](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](SECURITY.md) for security policy and vulnerability reporting.
## 🐛 Troubleshooting
### Worker Pool Issues
#### Workers Fail to Initialize
**Symptoms:**
```
[ERROR] Failed to create worker: Error: worker_threads not available
[ERROR] WorkerPool not initialized
```
**Solutions:**
1. **Verify Node.js version:**
```bash
node --version # Must be v18.0.0 or higher
```
2. **Check worker_threads support:**
```javascript
// 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):**
```bash
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:**
```
[WARN] Worker exited unexpectedly { workerId: 'worker-0', exitCode: 1 }
[ERROR] Worker terminated due to reaching memory limit
```
**Solutions:**
1. **Enable debug logging:**
```bash
LOG_LEVEL=debug npm start
```
2. **Increase Node.js memory limit:**
```bash
node --max-old-space-size=4096 dist/index-wasm.js
```
3. **Reduce worker count:**
```bash
MAX_WORKERS=2 npm start
```
4. **Check for WASM corruption:**
```bash
# Rebuild WASM modules
cd wasm
npm install
npx gulp
cd ..
npm run generate:hashes
```
5. **Monitor worker health:**
```bash
ENABLE_PERF_LOGGING=true npm start
# Watch for patterns in worker exits
```
#### Operations Timeout
**Symptoms:**
```
[ERROR] Operation timed out after 30000ms
[ERROR] Task queue full, operation rejected
```
**Solutions:**
1. **Increase operation timeout:**
```bash
OPERATION_TIMEOUT=60000 npm start
```
2. **Increase task timeout:**
```bash
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:**
```bash
ENABLE_PERF_LOGGING=true npm start
# Check for: "Worker pool at capacity"
```
5. **Scale up workers:**
```bash
MIN_WORKERS=4 MAX_WORKERS=8 npm start
```
#### Worker Pool Not Scaling
**Symptoms:**
```
[DEBUG] Pool empty, creating worker on-demand
[INFO] WorkerPool initialized successfully { activeWorkers: 0 }
```
**Solutions:**
1. **Verify MIN_WORKERS configuration:**
```bash
# 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:**
```bash
# Workers terminate after 60s idle by default
WORKER_IDLE_TIMEOUT=120000 npm start # 2 minutes
```
3. **Monitor scaling behavior:**
```bash
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:**
```
[ERROR] WASM integrity verification failed
[ERROR] Hash mismatch for wasm/build/release.wasm
```
**Solutions:**
1. **Rebuild WASM modules:**
```bash
cd wasm
npm install
npx gulp
cd ..
```
2. **Regenerate hash manifest:**
```bash
npm run generate:hashes
```
3. **Disable integrity checks (development only):**
```bash
DISABLE_WASM_INTEGRITY=true npm start
```
4. **Verify file permissions:**
```bash
ls -l wasm/build/*.wasm
# Should be readable by current user
```
#### WASM Module Not Loading
**Symptoms:**
```
[ERROR] Failed to load WASM module
[WARN] WASM not initialized, falling back to mathjs
```
**Solutions:**
1. **Check WASM files exist:**
```bash
ls wasm/build/
# Should contain: release.wasm, debug.wasm
```
2. **Rebuild from scratch:**
```bash
cd wasm
rm -rf node_modules build
npm install
npx gulp
cd ..
```
3. **Verify AssemblyScript toolchain:**
```bash
cd wasm
npx asc --version
# Should show AssemblyScript compiler version
```
4. **Check Node.js WASM support:**
```javascript
// 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:
```
MathJS MCP Server (Multi-tier Accelerated) running on stdio
Acceleration Status: 0% ops use acceleration ← Should increase with usage
```
**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:**
```bash
# ✓ 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:
```bash
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:
```bash
# Monitor CPU/memory during operations
top -p $(pgrep -f "node.*index-wasm")
```
### Integration Tests Failing
```bash
npm install
npm run build:all
npm test
```
**Expected output:**
```
✓ All integration tests passed!
✓ WASM integration working correctly
Success rate: 100.0%
```
**Common failures:**
1. **WASM modules not built:**
```bash
npm run build:wasm
npm run generate:hashes
```
2. **TypeScript compilation errors:**
```bash
npm run type-check
# Fix any errors before running tests
```
3. **Node.js version too old:**
```bash
node --version # Must be >=18.0.0
nvm install 18 # If using nvm
```
### Memory Issues
#### High Memory Usage
**Symptoms:**
```
[WARN] Memory usage high: 1.2GB
[ERROR] JavaScript heap out of memory
```
**Solutions:**
1. **Scale down workers:**
```bash
MIN_WORKERS=0 MAX_WORKERS=2 npm start
```
2. **Enable auto-scaling to zero:**
```bash
MIN_WORKERS=0 WORKER_IDLE_TIMEOUT=30000 npm start
```
3. **Increase Node.js heap:**
```bash
node --max-old-space-size=2048 dist/index-wasm.js
```
4. **Disable performance tracking:**
```bash
DISABLE_PERF_TRACKING=true npm start
```
#### Memory Leaks
**Symptoms:**
```
Memory usage increases over time
Workers not being garbage collected
```
**Solutions:**
1. **Monitor worker lifecycle:**
```bash
LOG_LEVEL=debug npm start
# Look for: "Terminating idle worker"
# Check: workers.size in logs
```
2. **Force garbage collection (debugging):**
```bash
node --expose-gc dist/index-wasm.js
```
3. **Reduce worker idle timeout:**
```bash
WORKER_IDLE_TIMEOUT=30000 npm start # 30 seconds
```
### Getting Help
If you're still experiencing issues:
1. **Enable debug logging:**
```bash
LOG_LEVEL=debug npm start 2>&1 | tee debug.log
```
2. **Collect system information:**
```bash
node --version
npm --version
uname -a # Linux/macOS
systeminfo # Windows
```
3. **Run diagnostic:**
```bash
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:
```bash
# Logging configuration
LOG_LEVEL=debug|info|warn|error # Control log verbosity (default: info)
# Acceleration tier configuration
ENABLE_GPU=false # Enable WebGPU acceleration tier (default: false, not yet implemented)
ENABLE_WORKERS=true # Enable WebWorkers acceleration tier (default: true)
ENABLE_WASM=true # Enable WASM acceleration tier (default: true)
NOTIFY_DEGRADATION=true # Log when acceleration tier degradation occurs (default: true)
# Performance tuning
DISABLE_PERF_TRACKING=true # Disable performance tracking for minimal overhead
ENABLE_PERF_LOGGING=true # Enable periodic performance statistics logging
# Worker pool configuration
MIN_WORKERS=0 # Minimum workers to keep alive (default: 2, set to 0 for auto-scaling)
MAX_WORKERS=8 # Maximum concurrent workers (default: CPU cores - 1)
WORKER_IDLE_TIMEOUT=60000 # Idle timeout in ms before worker termination (default: 60000)
TASK_TIMEOUT=30000 # Task timeout in milliseconds (default: 30000)
# Security limits
MAX_MATRIX_SIZE=1000 # Maximum matrix dimension (1000×1000)
MAX_ARRAY_LENGTH=100000 # Maximum array length for statistics
MAX_EXPRESSION_LENGTH=10000 # Maximum expression length (characters)
MAX_NESTING_DEPTH=50 # Maximum parentheses/bracket nesting
OPERATION_TIMEOUT=30000 # Operation timeout in milliseconds
```
## 🛠️ Development
### Code Quality Tools
```bash
# Linting and formatting
npm run lint # Run ESLint on TypeScript files
npm run lint:fix # Auto-fix linting issues
npm run format # Format code with Prettier
npm run format:check # Check code formatting
npm run type-check # Run TypeScript type checking
# Testing
npm run test # Run integration tests
npm run test:unit # Run unit tests (Vitest)
npm run test:coverage # Generate test coverage report
```
### 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](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
