Analytical MCP Server

Analytical MCP Server

Model Context Protocol server exposing 12 analytical tools for Claude: descriptive statistics, regression (linear/polynomial/logistic/multivariate), hypothesis testing, data preprocessing, data visualization specs, multi-criteria decision analysis, ML model evaluation, logical argument/fallacy analysis, and Exa-backed research verification. Runs over stdio; the analytical core needs no API key (research features require EXA_API_KEY).

Setup

Prerequisites

• Node.js >= 20.0.0
• EXA_API_KEY environment variable (required for verify_research and perspective_shifter, both of which call the Exa search API on every invocation)

Installation

Option 1: Direct Installation

npm install
npm run build

Option 2: Docker

Build the image. The server speaks the MCP protocol over stdio — it is launched (and its stdin/stdout piped) by the MCP client, not run as a detached daemon; see the Docker entry under Configuration for how Claude Desktop invokes it.

docker build -t analytical-mcp .

# Smoke-test the image interactively (Ctrl-C to exit):
docker run --rm -i -e EXA_API_KEY=your_api_key_here analytical-mcp

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

The server registers 12 tools on startup, unconditionally (registration does not depend on EXA_API_KEY; the two research-backed tools below will error at call time if the key is missing). See src/tools/index.ts for the authoritative list.

Statistical Analysis

• analyze_dataset — Descriptive statistics for a numeric or record-array dataset (summary/stats).
• advanced_statistical_analysis — Descriptive statistics plus cross-variable Pearson correlation on tabular data (arrays of objects). Use analyze_dataset for a single numeric series.
• advanced_regression_analysis — Linear, polynomial, logistic, and multivariate regression, backed by dedicated provider modules with real OLS/logistic math (not mocked).
• hypothesis_testing — Real statistical hypothesis tests: Welch's independent t-test, paired t-test, correlation, chi-square, and ANOVA, using exact p-value computation (see src/utils/statistics.ts).
• advanced_data_preprocessing — Normalization, standardization, missing-value handling, and IQR outlier detection on numeric data.
• data_visualization_generator — Generate chart specifications (scatter, line, bar, histogram, box, heatmap, pie, violin, correlation).

Machine Learning

• ml_model_evaluation — Evaluate model predictions: classification metrics (accuracy, precision, recall, F1) or regression metrics (MSE, MAE, RMSE, R²).

Decision Analysis

• decision_analysis — Multi-criteria weighted decision ranking. Requires a scores matrix (options.length rows × criteria.length columns, each value 0-10) in addition to options and criteria; weights is optional and defaults to equal weighting. This is a breaking requirement versus older docs that only described options/criteria/weights.

Logical Reasoning

• logical_argument_analyzer — Analyze argument structure, fallacies, validity, and strength (via dedicated provider classes).
• logical_fallacy_detector — Detect and explain logical fallacies in text with confidence scoring.
• perspective_shifter — Generate alternative perspectives (stakeholder, discipline, contrarian, optimistic, pessimistic) on a problem. Requires EXA_API_KEY: it runs an Exa search per perspective domain to ground each perspective.

Research Verification

• verify_research — Cross-verify research claims from multiple sources. Requires EXA_API_KEY. Returns confidence.score (the actual computed consistency/confidence value, 0-1) and confidence.verified (boolean: whether confidence.score met minConsistencyThreshold) — the threshold is a pass/fail cutoff, never a floor applied to the reported score.

Observability & Metrics

The Analytical MCP Server includes a built-in Prometheus-style metrics HTTP server (src/utils/metrics_server.ts) for monitoring cache performance and system health.

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

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: false; unauthenticated, opt-in)
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

Audit logging

Every tool call emits one structured audit record to stderr (never stdout — that is the MCP protocol channel), independent of LOG_LEVEL:

[2026-07-05T22:56:12.629Z] AUDIT: {"event":"tool_call","tool":"verify_research","ok":true,"durationMs":1352,"argBytes":120,"argHash":"31b769fe1f66","exaCalls":2}

Each record carries the tool name, outcome, duration, the byte size and a SHA-256 fingerprint of the arguments (never the raw argument values, so no content is leaked), and exaCalls — the number of outbound Exa requests the call issued. This gives an operator a forensic trail (oversized or repeated inputs, unexpected external fan-out) without recording sensitive content. It is gated by a single flag, on by default and independent of LOG_LEVEL:

ENABLE_AUDIT_LOG=true   # per-call audit records to stderr (default: true)

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"],
  "scores": [
    [7, 6, 8],
    [5, 9, 6],
    [9, 4, 7]
  ],
  "weights": [0.4, 0.4, 0.2]
}

Hypothesis Testing

{
  "testType": "t_test_independent",
  "data": [[23, 45, 67, 12, 89], [34, 56, 78, 90, 21]],
  "alpha": 0.05
}

Logical Analysis

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

Development

Testing

# Run the offline unit suite (no API key needed) — same as test:unit
npm test

# Unit tests only (offline, no API key needed)
npm run test:unit

# Integration tests (non-blocking heads-up without EXA_API_KEY; live-Exa cases self-skip)
npm run test:integration

# Integration tests excluding the live-API suite
npm run test:integration:no-api

# Or via the thin wrapper script
./tools/test-runner.sh unit
./tools/test-runner.sh integration
./tools/test-runner.sh integration:no-api

Scripts

• npm run build - Build TypeScript to JavaScript
• npm run watch - Watch for changes and rebuild
• npm run typecheck - Type-check src/ (excludes test files)
• npm run typecheck:src - Type-check src/ plus integration tests
• npm run lint / npm run lint:fix - ESLint
• npm run format / npm run format:check - Prettier
• npm test / npm run test:unit / npm run test:integration - Jest (see Testing)
• npm run smoke - Builds, starts the real server, and drives initialize/tools-list/tools-call over stdio JSON-RPC
• npm run cache:stats / cache:clear / cache:preload - Manage the on-disk research cache
• npm run inspector - Start MCP inspector for debugging

Project Structure

analytical-mcp/
├── src/
│   ├── tools/           # MCP tool implementations (12 registered tools + supporting providers)
│   ├── utils/           # Utility functions, regression/NLP providers, caching, resilience, metrics
│   ├── integration/     # Integration tests (live-Exa cases self-skip without EXA_API_KEY)
│   ├── __tests__/       # Server-level protocol test (InMemoryTransport)
│   └── index.ts         # Main server entry point
├── docs/                # Documentation
├── tools/               # Development and testing scripts
├── scripts/             # Build/smoke-test scripts
└── examples/            # Usage examples

Architecture Notes

• Provider architecture: Complex tools (regression, NLP, visualization, argument analysis) are decomposed into single-responsibility provider modules in src/utils/ and src/tools/ (e.g. linear_regression_provider.ts, logistic_regression_provider.ts, polynomial_regression_provider.ts, multivariate_regression_provider.ts, regression_metrics_provider.ts). Tool files orchestrate and format; providers hold the logic.
• Resilience: src/utils/rate_limit_manager.ts handles Exa rate limiting (key rotation, per-endpoint throttling); src/utils/api_helpers.ts provides retry with an explicit shouldRetry predicate.
• Caching: src/utils/cache_manager.ts, src/utils/enhanced_cache.ts, and src/utils/research_cache.ts provide layered, namespace-aware caching (enable with ENABLE_RESEARCH_CACHE=true).
• Statistics: src/utils/statistics.ts implements log-gamma, incomplete beta/gamma, and t/F/chi-square CDFs from first principles for exact p-value computation — no statistical approximations or mocked results.

Tool Categories

Statistical Analysis

• Descriptive statistics: mean, median, standard deviation, quartiles
• Regression analysis: linear, polynomial, logistic, multivariate
• Hypothesis testing: Welch t-test, paired t-test, correlation, chi-square, ANOVA

Decision Support

• Multi-criteria weighted decision ranking from an explicit options × criteria score matrix

Logical Reasoning

• Argument structure, validity, and strength analysis
• Fallacy detection with confidence scoring
• Perspective generation

Research Integration

• Multi-source verification via Exa
• Fact extraction
• Conflict/consistency checking
• Confidence scoring

Security and Privacy

• All analytical processing occurs locally
• Research features use the Exa API (optional, requires EXA_API_KEY)
• No permanent data storage beyond the optional local disk cache
• API keys managed via environment variables

License

MIT License. See LICENSE file for details.

Contributing

See CONTRIBUTING.md for the contribution workflow and conventions, and docs/DEVELOPMENT.md for the full development reference. All participants are expected to follow the Code of Conduct.

In short: branch from main, make sure npm run typecheck, npm run lint, npm test, and npm run smoke all pass, add tests for new behavior, and open a PR using the template.

To report a security vulnerability, follow SECURITY.md — do not open a public issue.

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 fail at call time: Set EXA_API_KEY in your environment or .env file — verify_research and perspective_shifter both require it even though all 12 tools register regardless of whether it is set.

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

See docs/TROUBLESHOOTING.md 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