# API Reference - MCP Server ROI
## Available Tools
### 1. predict_roi
Generate comprehensive ROI predictions for AI implementation projects with mandatory Dutch market validation. All input values and projected outcomes are validated against Dutch industry benchmarks using Perplexity API.
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| organization_id | string | Yes | Unique identifier for the organization |
| project | object | Yes | Project details |
| project.client_name | string | Yes | Name of the client |
| project.project_name | string | Yes | Name of the project |
| project.industry | enum | Yes | Industry classification |
| project.description | string | No | Project description |
| use_cases | array | Yes | List of use cases to implement |
| implementation_costs | object | Yes | Cost breakdown |
| timeline_months | number | Yes | Implementation timeline (1-120) |
| confidence_level | number | No | Confidence level (0-1, default: 0.95) |
#### Use Case Object Structure
```typescript
{
name: string,
category: 'automation' | 'analytics' | 'customer_service' | 'operations' | 'sales_marketing' | 'hr_recruiting' | 'finance_accounting' | 'custom',
current_state: {
process_time_hours: number, // Time per transaction
cost_per_transaction: number, // Direct cost
error_rate: number, // 0-1 (percentage)
volume_per_month: number, // Monthly volume
fte_required: number // Full-time equivalents
},
future_state: {
automation_percentage: number, // 0-1
time_reduction_percentage: number, // 0-1
error_reduction_percentage: number, // 0-1
scalability_factor: number // >=1
},
implementation: {
development_hours: number,
complexity_score: number, // 1-10
dependencies: string[],
risk_factors: Array<{
name: string,
probability: number, // 0-1
impact: 'low' | 'medium' | 'high' | 'critical'
}>
}
}
```
#### Example Request
```json
{
"organization_id": "org_123",
"project": {
"client_name": "ACME Corp",
"project_name": "Customer Service Automation",
"industry": "retail",
"description": "Automate tier 1 customer support"
},
"use_cases": [
{
"name": "Email Response Automation",
"category": "customer_service",
"current_state": {
"process_time_hours": 0.25,
"cost_per_transaction": 2.5,
"error_rate": 0.05,
"volume_per_month": 10000,
"fte_required": 15
},
"future_state": {
"automation_percentage": 0.8,
"time_reduction_percentage": 0.9,
"error_reduction_percentage": 0.7,
"scalability_factor": 2.0
},
"implementation": {
"development_hours": 320,
"complexity_score": 6,
"dependencies": ["CRM Integration", "Email Gateway"],
"risk_factors": [
{
"name": "Integration Complexity",
"probability": 0.3,
"impact": "medium"
}
]
}
}
],
"implementation_costs": {
"software_licenses": 50000,
"development_hours": 1000,
"training_costs": 25000,
"infrastructure": 30000,
"ongoing_monthly": 5000
},
"timeline_months": 24,
"confidence_level": 0.95
}
```
#### Response Structure
The response follows a multi-layered architecture optimized for LLM consumption:
```typescript
{
// Core Data Layer (Original response)
"project_id": "uuid",
"projection_id": "uuid",
"summary": {
"total_investment": 255000,
"expected_roi": 285.5,
"payback_period_months": 14,
"net_present_value": 450000,
"break_even_date": "2025-08-15T00:00:00Z"
},
"financial_metrics": {
"conservative": { ... },
"expected": { ... },
"optimistic": { ... }
},
// Layer 1: Executive Summary (Context Optimizer - ResponseTransformer)
"executive_summary": {
"headline": "Customer Service Automation will deliver 285% ROI in 2 years",
"confidence": "high",
"key_insight": "Email automation drives 70% of total value with minimal risk",
"primary_metric": "14-month payback period"
},
// Layer 2: Semantic Insights (Context Optimizer - InsightEngine)
"insights": {
"primary": [
"ROI significantly exceeds industry average of 200%",
"Low implementation risk with proven technology stack",
"Strong scalability potential - can handle 2x volume without additional costs"
],
"risks": [
"Integration complexity with legacy CRM system",
"3-month ramp-up period may delay initial benefits"
],
"opportunities": [
"Expand automation to chat and phone channels",
"Apply learnings to other business processes"
],
"patterns": [
"Similar projects typically see 20% additional savings in year 2"
]
},
// Layer 3: ML Predictions (Intelligence Amplifier - PredictiveAnalytics)
"ml_insights": {
"success_probability": 0.87,
"risk_score": 3.2, // 1-10 scale
"similar_projects_performance": "Top 15% in industry",
"predicted_actual_vs_projected": 0.92, // Historical accuracy
"key_success_factors": [
"Strong executive sponsorship",
"Phased implementation approach",
"Clear change management plan"
]
},
// Layer 4: Actionable Recommendations (Context Optimizer - MetadataEnricher)
"recommendations": {
"next_action": "Begin with email automation pilot for quick wins",
"timeline": "Start pilot in 2 weeks, full rollout in 3 months",
"success_criteria": [
"95% email response accuracy",
"< 2 hour average response time",
"80% customer satisfaction score"
],
"alternatives": [
"Consider phased approach starting with order status only",
"Evaluate pre-built solutions vs custom development"
]
},
// Layer 5: Natural Language Narratives (Experience Harmonizer - ConversationalBridge)
"narrative": {
"executive_briefing": "ACME Corp's customer service automation initiative represents an exceptional investment opportunity. With a projected 285% ROI and 14-month payback period, this project significantly outperforms industry benchmarks. The primary value driver is email automation, which alone can save $22,500 monthly by reducing response time by 90% while improving accuracy.",
"technical_summary": "The implementation leverages proven NLP models with 95%+ accuracy on structured queries. Integration with existing CRM systems via REST APIs minimizes technical risk. The phased rollout approach allows for iterative improvements and risk mitigation.",
"voice_output": "Based on my analysis, automating ACME Corp's customer service will save approximately 22 thousand dollars per month, paying for itself in just 14 months. The technology is proven and the implementation risk is low."
},
// Metadata for LLM Context (Intelligence Amplifier - CrossToolMemory)
"metadata": {
"confidence_score": 0.89,
"data_quality": "high",
"calculation_timestamp": "2024-06-15T10:30:00Z",
"assumptions": [
{
"category": "volume",
"description": "Email volume remains stable at 10,000/month",
"impact": "medium",
"sensitivity": 0.15 // 15% change impacts ROI
}
],
"calculation_context": {
"methodology": "Monte Carlo simulation with 10,000 iterations",
"tools_used": ["financial_calculator", "ml_predictor", "benchmark_aggregator"],
"benchmark_sources": ["perplexity_api", "industry_database"],
"computation_time_ms": 2341
}
}
}
```
### 2. compare_projects
Compare multiple AI projects side-by-side for ROI and other metrics with Dutch market validation. Each project undergoes individual validation against Dutch industry standards.
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_ids | string[] | Yes | Array of project IDs (2-10) |
| comparison_metrics | string[] | No | Metrics to compare (default: ['roi', 'payback_period', 'npv']) |
| time_horizon | number | No | Time horizon in months (12-120, default: 60) |
#### Available Comparison Metrics
- `roi` - Return on investment percentage
- `payback_period` - Months to break even
- `npv` - Net present value
- `total_investment` - Total upfront cost
- `monthly_benefit` - Average monthly benefit
- `risk_score` - Calculated risk (1-10)
- `implementation_complexity` - Detailed complexity metrics
#### Example Request
```json
{
"project_ids": ["proj_123", "proj_456", "proj_789"],
"comparison_metrics": ["roi", "payback_period", "risk_score"],
"time_horizon": 36
}
```
#### Response Structure
The response includes multi-layered insights with ML-powered analysis:
```typescript
{
// Core Comparison Data
"comparison_date": "2024-06-15T10:30:00Z",
"time_horizon_months": 36,
"projects": [
{
"project_id": "proj_123",
"project_name": "Customer Service AI",
"client_name": "ACME Corp",
"status": "active",
"roi": 285.5,
"payback_period_months": 14,
"risk_score": 4.5
}
],
"rankings": {
"roi": [/* ranked projects */],
"payback_period": [/* ranked projects */],
"risk_score": [/* ranked projects */]
},
// Layer 1: Executive Comparison Summary (Context Optimizer)
"comparison_summary": {
"best_performer": {
"id": "proj_123",
"name": "Customer Service AI",
"metric": "285.5% ROI"
},
"quickest_payback": {
"id": "proj_456",
"name": "Inventory Optimization",
"metric": "8 months"
},
"lowest_risk": {
"id": "proj_789",
"name": "Document Processing",
"risk_score": 2.1
},
"portfolio_recommendation": "DIVERSIFY"
},
// Layer 2: ML-Powered Insights (Intelligence Amplifier)
"ml_insights": {
"portfolio_score": 8.2, // 1-10 overall portfolio strength
"synergies": [
{
"projects": ["proj_123", "proj_456"],
"type": "shared_infrastructure",
"value": 150000,
"description": "Shared AI platform reduces costs by 25%"
}
],
"risk_correlation": 0.23, // Low correlation = good diversification
"success_patterns": [
"Projects with phased implementation show 40% higher success rate",
"Customer-facing projects deliver faster ROI than backend automation"
],
"portfolio_gaps": [
"No predictive analytics projects - missing growth opportunity"
]
},
// Layer 3: Strategic Recommendations (Experience Harmonizer)
"recommendations": {
"portfolio_strategy": "Implement Customer Service AI first for quick wins, then leverage infrastructure for Inventory Optimization",
"risk_mitigation": "Stagger implementations by 3 months to manage resource constraints",
"optimization_opportunities": [
"Bundle projects for 25% infrastructure savings",
"Apply Customer Service learnings to reduce Document Processing timeline"
],
"next_best_action": "Initiate Customer Service AI pilot within 2 weeks"
},
// Layer 4: Natural Language Insights (ConversationalBridge)
"narrative": {
"executive_summary": "Your AI portfolio shows strong potential with an average ROI of 245%. Customer Service AI stands out as the clear winner with rapid payback and manageable risk. By implementing projects in sequence and sharing infrastructure, you can reduce total costs by 25% while minimizing execution risk.",
"comparison_analysis": "The three projects complement each other well. Customer Service AI provides immediate value, Inventory Optimization offers operational efficiency, and Document Processing reduces compliance risk. The low risk correlation (0.23) indicates good portfolio diversification.",
"voice_ready": "Among your three AI projects, Customer Service automation is your best bet, delivering nearly 300 percent return in just 14 months."
},
// Enhanced Metadata (CrossToolMemory)
"metadata": {
"comparison_confidence": 0.91,
"data_completeness": {
"proj_123": 1.0, // Full data
"proj_456": 0.95, // Missing some risk factors
"proj_789": 1.0
},
"benchmark_context": {
"industry_average_roi": 200,
"percentile_rankings": {
"proj_123": 85, // Top 15%
"proj_456": 72,
"proj_789": 68
}
},
"analysis_methods": ["ml_pattern_matching", "monte_carlo", "industry_benchmarking"]
}
}
```
## Error Responses
All tools return errors in a consistent format:
```json
{
"error": {
"type": "validation_error",
"message": "Invalid arguments: project.industry: Invalid enum value",
"details": {
"field": "project.industry",
"expected": ["financial_services", "healthcare", "retail", ...],
"received": "invalid_industry"
}
}
}
```
### Error Types
- `validation_error` - Input validation failed
- `database_error` - Database operation failed
- `calculation_error` - Financial calculation error
- `timeout_error` - Operation exceeded time limit
- `not_found` - Resource not found
## Rate Limits
- Monte Carlo simulations: Max 100,000 iterations
- Worker pool size: 4 threads (configurable)
- Simulation timeout: 30 seconds
- Project comparison: Max 10 projects
## Response Transformation Services
The MCP Server ROI implements 9 specialized services across 3 agents to optimize responses for LLM consumption:
### Agent 1: Context Optimizer
Transforms raw financial data into semantic-rich, hierarchical information.
#### 1. ResponseTransformer
- **Purpose**: Creates executive summaries and key insights
- **Transforms**: Raw numbers → Natural language headlines
- **Example**: `roi: 285.5` → `"Customer Service Automation will deliver 285% ROI in 2 years"`
#### 2. InsightEngine
- **Purpose**: Generates actionable insights from patterns
- **Identifies**: Risks, opportunities, success patterns
- **Example**: Detects that email automation drives 70% of value
#### 3. MetadataEnricher
- **Purpose**: Adds context and confidence scores
- **Enriches**: Assumptions, methodologies, data quality
- **Example**: Adds sensitivity analysis showing 15% volume change impact
### Agent 2: Intelligence Amplifier
Adds predictive capabilities and cross-tool learning.
#### 4. PredictiveAnalytics
- **Purpose**: ML-based success predictions
- **Predicts**: Success probability, risk scores, performance vs peers
- **Example**: `success_probability: 0.87` based on similar projects
#### 5. CrossToolMemory
- **Purpose**: Maintains context across tool calls
- **Remembers**: Previous analyses, user preferences, project history
- **Example**: Applies learnings from predict_roi to enhance compare_projects
#### 6. RecommendationEngine
- **Purpose**: Generates strategic recommendations
- **Creates**: Next actions, timelines, success criteria
- **Example**: "Start with email automation pilot for quick wins"
### Agent 3: Experience Harmonizer
Adapts output format for optimal consumption.
#### 7. ResponseAdapter
- **Purpose**: Adjusts response based on consumption context
- **Adapts**: Token limits, format preferences, audience type
- **Example**: Full analysis → 100-token executive summary
#### 8. ConversationalBridge
- **Purpose**: Natural language narratives and voice output
- **Generates**: Executive briefings, technical summaries, voice-ready text
- **Example**: Creates Alexa-compatible project summaries
#### 9. QualityAssurance
- **Purpose**: Validates response quality and accuracy
- **Checks**: Calculation accuracy, benchmark alignment, actionability
- **Example**: Flags and caps unrealistic ROI calculations
## Service Integration Flow
```
User Query → MCP Tool → Raw Response
↓
Context Optimizer
(Transform → Insights → Metadata)
↓
Intelligence Amplifier
(Predict → Remember → Recommend)
↓
Experience Harmonizer
(Adapt → Narrate → Validate)
↓
Optimized Response → LLM
```
## Response Customization Options
### Format Preferences
```typescript
{
"preferences": {
"preferred_format": "executive_only" | "comprehensive" | "technical",
"detail_level": "minimal" | "standard" | "detailed",
"include_visuals": boolean,
"max_response_tokens": number,
"language_style": "formal" | "conversational" | "casual",
"enable_voice_mode": boolean
}
}
```
### Progressive Disclosure Levels
1. **Level 1** (50-100 tokens): Executive summary only
2. **Level 2** (200-500 tokens): + Key insights and risks
3. **Level 3** (500-1000 tokens): + Recommendations and ML insights
4. **Level 4** (1000-2000 tokens): + Natural language narratives
5. **Level 5** (2000+ tokens): Complete analysis with all details
## Best Practices
1. **Start with Predict ROI**: Use predict_roi for comprehensive analysis with Dutch market validation
2. **Provide Detailed Metrics**: More accurate inputs = better projections
3. **Include All Costs**: Don't forget training, infrastructure, and ongoing costs
4. **Consider Risk Factors**: Document dependencies and potential delays
5. **Track Actuals**: Use the tracking tools to validate projections
6. **Leverage Progressive Disclosure**: Access only the detail level needed
7. **Use Natural Language Input**: Tools parse conversational descriptions
8. **Enable ML Insights**: Get predictions based on similar projects
9. **Request Voice Output**: For accessibility and multi-modal interfaces
10. **Specify Token Limits**: Optimize responses for your context window
