JelteVrijhoef/deliverect-conversational-data

Deliverect Analytics MCP Server POC

A Model Context Protocol (MCP) server that provides natural language access to Deliverect restaurant analytics with business insights and controlled data access.

🚀 Status: Core Implementation Complete

✅ Working MCP Server with all 5 tools implemented
✅ Business Intelligence with actionable insights
✅ Rate Limiting & Validation following security best practices
✅ Comprehensive Testing framework included
⏳ Real Data Integration pending database setup

🎯 Quick Start

1. Environment Setup

# Clone and navigate to project
cd deliverect-mcp-poc

# Copy environment template
cp .env.example .env

# Edit .env with your credentials (see section below)

2. Install Dependencies

pip install -r requirements.txt

3. Run the MCP Server

python -m src.deliverect_mcp_server

4. Test the Server

python test_client.py "python -m src.deliverect_mcp_server"

🔧 Required Credentials

Update .env file with these required variables:

# Deliverect API (get from your Deliverect Developer Account)
DELIVERECT_CLIENT_ID=your_client_id_here
DELIVERECT_CLIENT_SECRET=your_client_secret_here
DELIVERECT_ENV=sandbox  # or 'production'
DELIVERECT_BASE_URL=https://staging-api.deliverect.com

# Database (PostgreSQL for analytics storage)
ANALYTICS_DB_URL=postgresql://user:password@localhost:5432/deliverect_analytics

# Cache (Redis for fast data access)
REDIS_URL=redis://localhost:6379/0

# Google Cloud (for BigQuery ETL - optional for testing)
GOOGLE_CLOUD_PROJECT=your_gcp_project_id
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

🛠️ Available MCP Tools

1. get_popular_items

Analyze most popular menu items with sales trends and business insights.

{
    "timeframe": "week",     # day, week, month, quarter
    "location_id": null,     # specific location or null for all
    "limit": 10              # max 50 items
}

2. get_store_performance

Compare restaurant location performance with operational metrics.

{
    "location_ids": ["loc_downtown", "loc_mall"],  # max 10 locations
    "timeframe": "month",                          # analysis period
    "comparison": true                             # include comparisons
}

3. get_revenue_analytics

Analyze revenue trends and financial performance with forecasting.

{
    "timeframe": "quarter",        # week, month, quarter, year
    "breakdown_by": "month",       # day, week, month, category
    "include_forecast": false      # experimental forecasting
}

4. get_order_summary

Analyze order volume patterns and operational efficiency metrics.

{
    "timeframe": "week",           # analysis period
    "include_patterns": true,      # detailed pattern analysis
    "breakdown_by_hour": false     # hourly breakdown data
}

5. search_locations

Discover and list available restaurant locations for analysis.

{
    "search_term": "downtown",     # filter by name/address
    "location_type": "restaurant", # restaurant, food_truck, etc.
    "active_only": true,           # only active locations
    "include_metrics": false       # basic performance metrics
}

🔒 Security & Rate Limiting

• Rate Limited: 5 calls per minute per tool
• Query Limits: Max 90 days, 50 items, 10 locations per query
• Input Validation: All parameters sanitized and validated
• Controlled Access: NO direct database or API access from tools
• Pre-Aggregated Data: Fast responses from cached analytics

📊 Response Format

All tools return standardized responses with:

{
    "success": true,
    "data": {
        # Tool-specific data (items, locations, etc.)
    },
    "business_context": {
        "insights": [],           # Actionable business insights
        "benchmarks": {},         # Performance comparisons
        "trends": [],             # Notable trends identified
        "recommendations": []     # Specific action items
    },
    "metadata": {
        "data_freshness": "15min old",
        "confidence": 0.95,
        "source": "analytics_service",
        "query_time_ms": 87
    }
}

🧪 Testing

The included test client validates all functionality:

# Run comprehensive tests
python test_client.py "python -m src.deliverect_mcp_server"

# Tests include:
# ✅ All 5 MCP tools
# ✅ Error handling scenarios  
# ✅ Rate limiting behavior
# ✅ Response format validation

🏗️ Architecture

LLM/Claude ↔ MCP Protocol ↔ Deliverect MCP Server ↔ Analytics Service ↔ Pre-Aggregated Data

Key Design Principles:

• Business-First: Every response includes actionable insights
• Controlled Access: Tools never query BigQuery/APIs directly
• Rate Limited: Prevents expensive operations and abuse
• Real Data Only: NO mock data (pending database setup)

📝 Current Limitations

• Mock Data: Tools return structured mock data pending database setup
• ETL Pipeline: BigQuery → Analytics DB pipeline not yet implemented
• Docker: Containerization pending
• Real-Time Data: Currently simulated data freshness

🚧 Next Steps

1. Database Setup - PostgreSQL + Redis infrastructure
2. ETL Implementation - BigQuery extraction and aggregation
3. Real API Integration - Connect to actual Deliverect endpoints
4. Docker Deployment - Complete containerization
5. Production Testing - Integration tests with live data

📚 Documentation

• plan.md - Comprehensive implementation plan
• progress.md - Current status and completed milestones
• CLAUDE.md - Development guidelines and architecture requirements
• test_client.py - Testing and validation framework

🆘 Troubleshooting

Server Won't Start

• Check all environment variables are set in .env
• Verify Python dependencies installed: pip install -r requirements.txt
• Check for port conflicts if using WebSocket mode

Tools Return Errors

• Verify .env configuration matches .env.example
• Check rate limiting - wait 1 minute between test runs
• Review server logs for detailed error information

Database Connection Issues

• Ensure PostgreSQL is running and accessible
• Verify ANALYTICS_DB_URL connection string
• Check database permissions and network access

🤝 Contributing

This is a POC implementation following the requirements in CLAUDE.md. Key development principles:

• NO Direct API Access - All tools use controlled analytics service
• Business Context Required - Every response must include insights
• Rate Limiting Enforced - Security and cost controls mandatory
• Real Data Only - NO mock data in production

📄 License

Internal POC - See organization licensing requirements.

🎉 Ready to chat with your restaurant data through natural language queries!