Skip to main content
Glama
SPAIK-io

ROI Prediction MCP Server

by SPAIK-io
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

@spaik/mcp-server-roi

npm version License: MIT

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SPAIK-io/mcp-server-roi'

If you have feedback or need assistance with the MCP directory API, please join our Discord server