@spaik/mcp-server-roi

A Model Context Protocol (MCP) server for AI ROI prediction and tracking with Monte Carlo simulations, real-time industry benchmarks, and ML-powered insights. Now with mandatory Dutch market validation and natural language support!

🆕 What's New in v1.3.1

Bug Fixes

Fixed critical "Cannot read properties of undefined (reading 'industry')" error
Enhanced input validation for all tools
Improved error messages for better user experience

What's New in v1.3.0

Breaking Changes

Removed quick-assessment tool: Replaced by enhanced predict_roi with Dutch validation
PERPLEXITY_API_KEY now required: Mandatory for Dutch market validation

New Features

Dutch Market Validation: All predictions validated against Dutch industry averages
Automatic Value Adjustment: Unrealistic values (>3x industry average) are intelligently adjusted
Market-Specific Insights: Dutch trends and patterns incorporated in analysis
Enhanced Confidence Scoring: Based on alignment with Dutch market data

From v1.2.0

Natural Language Input: Use conversational text instead of complex JSON
Smart Defaults: 80% reduction in required fields
Flexible Formats: Accept "$50k", "85%", "6 months" formats

Key Features

🎯 Core Capabilities

ROI Predictions: Generate detailed 5-year financial projections with Dutch market validation
Monte Carlo Simulations: Advanced risk analysis with multiple distribution models
Multi-Project Comparison: Compare up to 10 projects with ML-powered insights
Dutch Market Validation: Mandatory validation against Dutch industry benchmarks
Industry Benchmarks: Real-time data via Perplexity API integration

🤖 AI & ML Features

Universal NLP: All tools support natural language input
Intent Detection: Automatically routes to the correct tool
Context Awareness: Maintains conversation history
ML Comparison Engine: Pattern recognition and success prediction
Voice Output: Accessibility-friendly summaries
Synergy Detection: Identify value-add opportunities between projects
Risk Scoring: Multi-factor risk assessment with confidence levels

💼 Financial Metrics

NPV (Net Present Value) with customizable discount rates
IRR (Internal Rate of Return) using Newton's method
Payback Period with linear interpolation
Break-even Analysis with monthly precision
Cash Flow Projections with ramp-up modeling

🔄 Production Features

Transaction Management: Atomic operations with rollback
Retry Logic: Exponential backoff for resilience
Real-time Benchmarks: Perplexity Sonar API integration
Graceful Degradation: Fallback to static data when APIs unavailable
Comprehensive Logging: Structured logs with context

Installation

From npm

npm install @spaik/mcp-server-roi

From source

git clone https://github.com/SPAIK-io/mcp-server-roi.git
cd mcp-server-roi
npm install
npm run build

Quick Start

Simple Natural Language Example

Instead of complex JSON, just describe what you need:

// Using natural language
await predictROI({
  natural_language_input: "Help ACME Corp automate their customer service. They're in retail, handle 5000 emails monthly taking 15 minutes each. Budget is around $100k and we need this done in 6 months."
});

// Or use the simplified format
await predictROI({
  client: "ACME Corp",
  project: "Customer Service Automation",
  industry: "retail",
  budget: "$100k",
  timeline: "6 months"
});

Get Help Anytime

// Get examples for any tool
await getExamples({ tool_name: "predict_roi" });

// Get interactive help
await help({ query: "How do I calculate ROI for a healthcare project?" });

Configuration

1. Environment Setup

Create a .env file based on .env.example:

cp .env.example .env

2. Required Environment Variables

# Required - Supabase Configuration
SUPABASE_URL=https://xxxxxxxxxxxxx.supabase.co
SUPABASE_ANON_KEY=your_supabase_anon_key

# Required for full functionality
SUPABASE_SERVICE_KEY=your_service_key  # Admin access
PERPLEXITY_API_KEY=your_perplexity_key # Real-time benchmarks

# Optional - Enhanced Features
FMP_API_KEY=your_fmp_key              # Financial market data
LOG_LEVEL=info                        # debug|info|warn|error
WORKER_POOL_SIZE=4                    # CPU cores
MAX_SIMULATION_ITERATIONS=100000      # Monte Carlo precision

3. Database Setup

Run these SQL scripts in your Supabase SQL editor (in order):

database/schema.sql - Core tables and indexes
database/001_security_update.sql - Security and RLS policies
database/002_transactional_functions.sql - Transaction functions

Usage with Claude Desktop

Database Setup (Required):

# Apply required database functions
# See database/APPLY_FUNCTIONS.md for detailed instructions

# Option 1: Via Supabase Dashboard
# Copy contents of database/002_transactional_functions.sql
# Paste into SQL Editor and run

# Option 2: Using npm script (requires service key)
npm run apply-db-functions

Claude Desktop Configuration:

Add to your configuration file (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "roi": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-roi/dist/index.js"],
      "env": {
        "SUPABASE_URL": "your_supabase_url",
        "SUPABASE_ANON_KEY": "your_anon_key",
        "SUPABASE_SERVICE_KEY": "your_service_key",
        "PERPLEXITY_API_KEY": "your_perplexity_key",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Available Tools

1. predict_roi

Generate comprehensive ROI predictions with Monte Carlo simulations.

🆕 Natural Language Example:

"Help ACME Bank reduce fraud losses. They process 1M transactions monthly with 0.5% fraud rate and $500 average loss. Need real-time detection system. Budget is $200k plus training."

Simplified JSON Example:

{
  "client": "ACME Bank",
  "project": "Fraud Detection System",
  "industry": "finance",  // or "financial_services" 
  "budget": "$200k",
  "timeline": "6 months"
}

Traditional Example (still supported):

"Create an ROI prediction for ACME Corp's fraud detection system:
- Industry: Financial Services
- Use Case: Transaction monitoring
  - Current: 1M transactions/month, 0.5% fraud rate, $500 avg loss
  - Future: 95% detection rate, real-time processing
- Implementation: $200k software, 1000 dev hours, $50k training
- Timeline: 6 months"

Key Parameters:

organization_id: Organization identifier
project: Project details with industry classification
use_cases: Array of current → future state transformations
implementation_costs: Comprehensive cost breakdown
timeline_months: 1-120 months
enable_benchmarks: Use real-time industry data

2. compare_projects

Compare multiple projects with ML-powered insights and visualizations.

🆕 Natural Language Example:

"Compare customer service automation vs inventory optimization vs predictive maintenance projects for ACME Corp"

Simplified Example:

{
  "projects": ["Customer Service Bot", "Smart Inventory", "Machine Monitoring"],
  "focus": "roi and risk"
}

Traditional Example:

"Compare these three AI projects:
- Project A: Customer service automation (ID: xxx)
- Project B: Inventory optimization (ID: yyy)  
- Project C: Predictive maintenance (ID: zzz)
Include risk analysis and synergy opportunities"

Key Parameters:

project_ids or project_names: Projects to compare
comparison_metrics: ['roi', 'npv', 'payback_period', 'risk_score']
enable_ml_insights: ML predictions and pattern matching
natural_language_input: Describe what to compare

3. get_examples (🆕)

Get relevant usage examples for any tool.

Usage:

{
  "tool_name": "predict_roi",
  "category": "healthcare"  // optional
}

4. help (🆕)

Get interactive help and tool recommendations.

Usage:

{
  "query": "How do I calculate ROI for a hospital automation project?"
}

Industry Support

Pre-configured benchmarks and calculations for:

🏦 Financial Services (fraud detection, compliance, trading)
🏥 Healthcare (patient records, diagnostics, scheduling)
🛍️ Retail (inventory, customer service, personalization)
🏭 Manufacturing (predictive maintenance, quality control)
💻 Technology (DevOps, security, analytics)
🎓 Education (grading, admissions, tutoring)
🏛️ Government (document processing, citizen services)

Advanced Features

Real-time Benchmarks

When Perplexity API key is provided:

Current industry ROI ranges
Implementation timelines
Success rates by company size
Technology adoption trends

ML-Powered Insights

Success probability prediction (0-100%)
Risk factor identification
Synergy opportunities between projects
Industry-specific pattern matching

Natural Language Processing

Parse requirements from conversational input
Extract metrics and volumes automatically
Generate structured use cases
Support for voice-friendly outputs

LLM Usage Guide

Optimized for AI Agents

This MCP server has been specifically optimized for use with LLMs and AI agents, featuring:

1. Semantic-Rich Responses

All tools return multi-layered responses with progressive disclosure:

{
  "executive_summary": { /* High-level insights */ },
  "insights": { /* Detailed analysis */ },
  "recommendations": { /* Actionable next steps */ },
  "narrative": { /* Natural language explanation */ },
  "metadata": { /* Context and confidence */ }
}

2. Natural Language Elements

Pre-generated summaries and explanations
Voice-ready output for accessibility
Conversational tone options
Context-aware recommendations

3. Token Optimization

Hierarchical data structure for selective parsing
Summary-first approach reduces token usage
Optional detail levels based on agent needs
Efficient JSON structure with clear semantics

4. Multi-Agent Coordination

The server implements three internal optimization agents:

Context Optimizer: Transforms raw data into semantic layers
Intelligence Amplifier: Adds ML insights and predictions
Experience Harmonizer: Adapts output format for optimal consumption

Best Practices for LLM Integration

Progressive Information Retrieval

# Start with executive summary
response.executive_summary

# Drill down as needed
if needs_details:
    response.insights.primary
    response.financial_metrics.expected

Conversation Memory
- Tools maintain context across calls
- Reference previous analyses for consistency
- Build on prior insights

Format Preferences

{
  "preferred_format": "executive_only",  // For quick summaries
  "detail_level": "comprehensive",       // For full analysis
  "include_visuals": true,              // For chart-ready data
  "max_response_tokens": 1000           // For token limits
}

Error Handling
- All errors include actionable guidance
- Graceful degradation with fallbacks
- Clear validation messages for corrections

Response Structure Example

// predict_roi response optimized for LLMs
{
  summary: {
    expected_roi: 8500,        // Key metric upfront
    confidence: "high",        // Natural language
    recommendation: "PROCEED"  // Clear action
  },
  narrative: {
    executive_briefing: "This AI investment will deliver 8,500% ROI...",
    key_insights: ["Automation will save 10,000 hours monthly", ...],
    risk_assessment: "Low risk with proven technology"
  },
  details: { /* Full calculations available if needed */ }
}

Performance Benchmarks

Tool Execution: 1-3 seconds average
Perplexity API: ~15 seconds for complex queries
Database Operations: < 500ms
Monte Carlo (100k iterations): < 5 seconds
ML Predictions: < 1 second
LLM Response Generation: < 100ms

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run comprehensive tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

Testing

The project includes comprehensive test coverage:

# Run all tests
npm test

# Test database connection
npx tsx test-db-connection.ts

# Run comprehensive integration tests
npx tsx test-comprehensive.ts

Security Considerations

Database Access: Uses Supabase service key for admin operations
Input Validation: All inputs validated with Zod schemas
Error Handling: Sensitive information sanitized in error messages
API Keys: Store securely, never commit to repository

Troubleshooting

Common Issues

"Permission denied for table projects"
- Ensure SUPABASE_SERVICE_KEY is set in environment
- Check RLS policies in Supabase dashboard
"Perplexity API error"
- Verify API key is valid
- Check API rate limits
- System falls back to static benchmarks automatically
"Transaction timeout"
- Increase DEFAULT_TRANSACTION_TIMEOUT in .env
- Reduce number of use cases per request

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│   MCP Server     │────▶│    Supabase     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │                           │
                               ▼                           ▼
                        ┌──────────────┐           ┌──────────────┐
                        │ Worker Pool  │           │  PostgreSQL  │
                        │(Monte Carlo) │           └──────────────┘
                        └──────────────┘
                               │
                               ▼
                        ┌──────────────────────────────┐
                        │   External APIs              │
                        ├──────────────────────────────┤
                        │ • Perplexity Sonar          │
                        │ • Financial Modeling Prep   │
                        └──────────────────────────────┘

License

MIT © SPAIK

Support

Issues: https://github.com/SPAIK-io/mcp-server-roi/issues
Documentation: See CLAUDE.md for detailed development guide
Examples: Check /examples directory for usage patterns

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Changelog

v1.3.0 (2025-07-03)

Breaking: Removed quick-assessment tool
Breaking: PERPLEXITY_API_KEY now required
🆕 Mandatory Dutch market validation for all predictions
🆕 Automatic adjustment of unrealistic values
🆕 Market-specific insights based on Dutch trends
🆕 Enhanced confidence scoring aligned with market data

v1.2.0 (2025-07-01)

🆕 Universal natural language support for all tools
🆕 Smart defaults reduce required fields by 80%
🆕 Flexible input formats ("$50k", "85%", "6 months")
🆕 User-friendly error messages with suggestions
🆕 New utility tools: get_examples and help
🆕 Intent detection automatically routes to correct tool
🆕 Context awareness for conversation history
🆕 Self-documenting tools with embedded examples
🆕 LLM-optimized response structure
🆕 Comprehensive prompt engineering guide

v1.1.1 (2025-06-30)

Bug fixes and performance improvements

v1.0.0 (2025-06-24)

Initial release with full MCP implementation
Real-time benchmark integration
ML-powered project comparison
Natural language input support
Comprehensive transaction management

SPAIK AI ROI