@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 indexesdatabase/001_security_update.sql- Security and RLS policiesdatabase/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 identifierproject: Project details with industry classificationuse_cases: Array of current → future state transformationsimplementation_costs: Comprehensive cost breakdowntimeline_months: 1-120 monthsenable_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_idsorproject_names: Projects to comparecomparison_metrics: ['roi', 'npv', 'payback_period', 'risk_score']enable_ml_insights: ML predictions and pattern matchingnatural_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_KEYis set in environment - Check RLS policies in Supabase dashboard
- Ensure
-
"Perplexity API error"
- Verify API key is valid
- Check API rate limits
- System falls back to static benchmarks automatically
-
"Transaction timeout"
- Increase
DEFAULT_TRANSACTION_TIMEOUTin .env - Reduce number of use cases per request
- Increase
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
/examplesdirectory 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_examplesandhelp - 🆕 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