@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):

1. database/schema.sql - Core tables and indexes

2. database/001_security_update.sql - Security and RLS policies

3. database/002_transactional_functions.sql - Transaction functions

Usage with Claude Desktop

1. 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

2. 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

1. Progressive Information Retrieval

   # Start with executive summary
   response.executive_summary
   
   # Drill down as needed
   if needs_details:
       response.insights.primary
       response.financial_metrics.expected

2. Conversation Memory

   • Tools maintain context across calls

   • Reference previous analyses for consistency

   • Build on prior insights

3. 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
   }

4. 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

1. Database Access: Uses Supabase service key for admin operations

2. Input Validation: All inputs validated with Zod schemas

3. Error Handling: Sensitive information sanitized in error messages

4. API Keys: Store securely, never commit to repository

Troubleshooting

Common Issues

1. "Permission denied for table projects"

   • Ensure SUPABASE_SERVICE_KEY is set in environment

   • Check RLS policies in Supabase dashboard

2. "Perplexity API error"

   • Verify API key is valid

   • Check API rate limits

   • System falls back to static benchmarks automatically

3. "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:

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure all tests pass

5. 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