quanticsoul4772/analytical-mcp

Analytical MCP Server

Model Context Protocol server providing statistical analysis, decision support, logical reasoning, and research verification tools for Claude.

Setup

Prerequisites

• Node.js >= 20.0.0
• EXA_API_KEY environment variable (for research features)

Installation

Option 1: Direct Installation

npm install
npm run build

Option 2: Docker

# Build the Docker image
docker build -t analytical-mcp .

# Run with environment variables
docker run -d \
  --name analytical-mcp \
  -e EXA_API_KEY=your_api_key_here \
  -v $(pwd)/cache:/app/cache \
  analytical-mcp

# Or use docker-compose
cp .env.example .env
# Edit .env with your API key
docker-compose up -d

Configuration

Direct Installation Configuration

1. Copy .env.example to .env
2. Add your EXA_API_KEY to .env
3. Add to Claude Desktop configuration:

{
  "mcpServers": {
    "analytical": {
      "command": "node",
      "args": ["/path/to/analytical-mcp/build/index.js"],
      "env": {
        "EXA_API_KEY": "your-exa-api-key-here"
      }
    }
  }
}

Docker Configuration

1. Copy .env.example to .env
2. Add your EXA_API_KEY to .env
3. Add to Claude Desktop configuration:

{
  "mcpServers": {
    "analytical": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", ".env",
        "-v", "$(pwd)/cache:/app/cache",
        "analytical-mcp"
      ]
    }
  }
}

Available Tools

Statistical Analysis

• analytical:analyze_dataset - Statistical analysis of datasets
• analytical:advanced_regression_analysis - Linear, polynomial, and logistic regression
• analytical:hypothesis_testing - Statistical hypothesis testing (t-tests, chi-square, ANOVA)
• analytical:data_visualization_generator - Generate data visualization specifications

Decision Analysis

• analytical:decision_analysis - Multi-criteria decision analysis with weighted scoring

Logical Reasoning

• analytical:logical_argument_analyzer - Analyze argument structure and validity
• analytical:logical_fallacy_detector - Detect logical fallacies in text
• analytical:perspective_shifter - Generate alternative perspectives on problems

Research Verification

• analytical:verify_research - Cross-verify research claims from multiple sources

Observability & Metrics

The Analytical MCP Server includes built-in observability features for monitoring circuit breakers and cache performance.

Metrics Endpoint

When enabled, the server exposes metrics via HTTP on port 9090 (configurable):

• http://localhost:9090/metrics - Prometheus-style metrics
• http://localhost:9090/metrics?format=json - JSON format metrics
• http://localhost:9090/health - Health check endpoint
• http://localhost:9090/ - Metrics server status page

Available Metrics

Circuit Breaker Metrics

• analytical_mcp_circuit_breaker_state - Current state (0=CLOSED, 1=HALF_OPEN, 2=OPEN)
• analytical_mcp_circuit_breaker_total_calls_total - Total calls through circuit breaker
• analytical_mcp_circuit_breaker_rejected_calls_total - Rejected calls by circuit breaker
• analytical_mcp_circuit_breaker_failure_count - Current failure count
• analytical_mcp_circuit_breaker_success_count - Current success count

Cache Metrics

• analytical_mcp_cache_hits_total - Cache hits by namespace
• analytical_mcp_cache_misses_total - Cache misses by namespace
• analytical_mcp_cache_puts_total - Cache puts by namespace
• analytical_mcp_cache_evictions_total - Cache evictions by namespace
• analytical_mcp_cache_size - Current cache size by namespace

System Metrics

• analytical_mcp_uptime_seconds - Server uptime in seconds
• analytical_mcp_memory_usage_bytes - Memory usage (RSS, heap, external)
• analytical_mcp_cpu_usage_microseconds - CPU time usage (user, system)

Configuration

Enable metrics by setting environment variables:

METRICS_ENABLED=true        # Enable metrics server (default: true)
METRICS_PORT=9090          # Metrics server port (default: 9090)
METRICS_HOST=127.0.0.1     # Metrics server host (default: 127.0.0.1, use 0.0.0.0 to bind to all interfaces)

Usage Examples

# Get Prometheus metrics
curl http://localhost:9090/metrics

# Get JSON metrics
curl http://localhost:9090/metrics?format=json

# Health check
curl http://localhost:9090/health

Usage Examples

Dataset Analysis

{
  "data": [23, 45, 67, 12, 89, 34, 56, 78],
  "analysisType": "stats"
}

Decision Analysis

{
  "options": ["Option A", "Option B", "Option C"],
  "criteria": ["Cost", "Quality", "Speed"],
  "weights": [0.4, 0.4, 0.2]
}

Logical Analysis

{
  "argument": "All birds can fly. Penguins are birds. Therefore, penguins can fly.",
  "analysisDepth": "comprehensive"
}

Development

Testing

# Run all tests
./tools/test-runner.sh

# Run specific test suite
./tools/test-runner.sh integration

# Available test suites: api-keys, server, integration, research, data-pipeline

Scripts

• npm run build - Build TypeScript to JavaScript
• npm run watch - Watch for changes and rebuild
• npm run test - Run Jest tests
• npm run inspector - Start MCP inspector for debugging

Project Structure

analytical-mcp/
├── src/
│   ├── tools/           # MCP tool implementations
│   ├── utils/           # Utility functions
│   └── index.ts         # Main server entry point
├── docs/                # Documentation
├── tools/               # Development and testing scripts
└── examples/            # Usage examples

Tool Categories

Statistical Analysis

• Descriptive statistics: mean, median, standard deviation, quartiles
• Correlation analysis
• Regression analysis: linear, polynomial, logistic
• Hypothesis testing: t-tests, chi-square, ANOVA

Decision Support

• Multi-criteria decision analysis
• Weighted scoring
• Trade-off analysis
• Risk assessment

Logical Reasoning

• Argument structure analysis
• Fallacy detection
• Perspective generation
• Critical analysis

Research Integration

• Multi-source verification
• Fact extraction
• Consistency checking
• Confidence scoring

Security and Privacy

• All processing occurs locally
• Research features use Exa API (optional, requires API key)
• No permanent data storage
• Optional file-based caching stored locally only
• API keys managed via environment variables

License

MIT License. See LICENSE file for details.

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/your-feature
3. Make changes and commit: git commit -m 'Add feature description'
4. Push to branch: git push origin feature/your-feature
5. Open pull request

See for detailed development guidelines, code standards, and testing requirements.

Troubleshooting

Common Issues

JSON parsing errors: All logging must go to stderr, not stdout. MCP protocol uses stdout for communication. Use the Logger class, not console.log.

Tools not appearing: Verify server configuration in Claude Desktop settings and restart Claude Desktop application.

Research features disabled: Set EXA_API_KEY in your environment or .env file.

Server not starting: Check Node.js version is 20 or higher and all dependencies are installed with npm install.

See for detailed troubleshooting guidance.

Debug Mode

Start the server with the MCP inspector:

npm run inspector

Links

• Model Context Protocol Documentation
• Exa API Documentation
• Claude Desktop