curberator by ridecharge - MCP Server

Curb Analytics - MCP Server

A comprehensive Model Context Protocol (MCP) server for analyzing Curb ride-sharing data and providing business intelligence insights.

Overview

This project provides an MCP-compatible server that integrates with Curb Mobility's Book with Curb API to deliver real-time ride analytics, vehicle availability insights, and fare intelligence. It supports both local Claude Code integration (JSON-RPC) and remote Claude.ai access (HTTP with OAuth).

Features

🌍 Service Discovery

Available ride services at any location (taxi, wheelchair accessible vehicles)
Real-time service availability analysis
Market coverage assessment

🚗 Vehicle Intelligence

Live vehicle tracking and availability
Advanced filtering by service type, features, and location
Fleet composition analysis
Driver performance insights

💰 Fare Intelligence

Comprehensive fare estimation with fee breakdowns
Real-time pricing with surge analysis
Cost optimization recommendations
Route pricing intelligence

📊 Business Analytics

Historical ride pattern analysis
Peak hour identification
Service utilization metrics
Market demand forecasting

🔐 Dual Protocol Support

JSON-RPC over stdio for Claude Code (local development)
HTTP with OAuth 2.0 for Claude.ai (remote access)
Enterprise-grade authentication and rate limiting

Quick Start

Prerequisites

Curb API Access: Contact Curb Mobility to get your API token
Python 3.8+: Required for the server
Claude Code or Claude.ai: For MCP integration

Installation

# Clone and setup
git clone <repository-url>
cd curberator

# Install dependencies  
pip install -r requirements.txt

# Configure API credentials
cp config.example.json config.json
# Edit config.json with your Curb API token

Configuration

Update config.json with your settings:

{
  "curb_api": {
    "base_url": "https://api.release.gocurb.com/v1",
    "api_key": "your-curb-api-token-here", 
    "environment": "sandbox",
    "timeout": 30
  },
  "server": {
    "name": "curb-analyzer",
    "version": "1.0.0", 
    "description": "Curb ride-sharing data analysis and insights tool"
  }
}

Environment Options:

sandbox: Testing environment (api.release.gocurb.com)
production: Live environment (api.gocurb.com)

Usage

For Claude Code (Local)

# Start JSON-RPC server
./run_curb_server.sh

# Or directly
python curb_mcp_server.py

Claude Code Configuration:

{
  "mcpServers": {
    "curb-analyzer": {
      "command": "python",
      "args": ["curb_mcp_server.py"], 
      "cwd": "/path/to/curberator"
    }
  }
}

For Claude.ai (Remote)

# Start HTTP server with OAuth
./run_curb_server.sh --http

# Or with port specification
PORT=8080 python curb_mcp_server.py --http

The server provides OAuth 2.0 endpoints for secure Claude.ai integration.

Available Tools

🌍 discover_services

Find available ride services at a location

discover_services(latitude=40.7580, longitude=-73.9855)

🚗 find_vehicles

Search for available vehicles with advanced filtering

find_vehicles(
    latitude=40.7580, 
    longitude=-73.9855,
    service_types="taxi,wav",
    features="wav,cash",
    max_count=20
)

💰 get_ride_estimates

Get comprehensive fare estimates including fees

get_ride_estimates(
    pickup_latitude=40.7580,
    pickup_longitude=-73.9855,
    dropoff_latitude=40.6413,
    dropoff_longitude=-73.7781,
    service_type="taxi"
)

📋 get_ride_details

Get detailed ride information with event history

get_ride_details(ride_id=12345, include_history=True)

🔍 search_rides

Advanced ride search with business intelligence

search_rides(
    filter_by="past",
    time_interval=24,
    service_type="taxi",
    per=50
)

📊 analyze_vehicle_availability

Analyze vehicle availability patterns and fleet insights

analyze_vehicle_availability(
    latitude=40.7580,
    longitude=-73.9855,
    analysis_type="availability"
)

API Client Features

Professional-Grade Client

Rate Limiting: Automatic rate limit management (60 requests/minute)
Caching: Intelligent response caching with TTL
Error Handling: Comprehensive error management with retry logic
Health Monitoring: API health checks and status monitoring

Supported Endpoints

Location Services: Service types, vehicle search, ETA estimation
Fare Estimation: V1, V3, V4 endpoints with full fee breakdowns
Ride Management: Ride details, search, and history tracking
Vehicle Intelligence: Real-time vehicle tracking and metadata

Testing

Test API Client

python test_curb_client.py

Test MCP Server

# Test basic functionality
python -c "
import asyncio
from curb_mcp_server import CurbMCPJSONRPCServer
server = CurbMCPJSONRPCServer()
# Run integration tests
"

Development

Project Structure

curberator/
├── curb_api_client.py          # Professional Curb API client
├── curb_mcp_server.py          # Dual-protocol MCP server  
├── config.json                 # Configuration file
├── test_curb_client.py         # API client tests
├── run_curb_server.sh          # Startup script
└── requirements.txt            # Dependencies

Adding New Features

New API Endpoints: Extend CurbAPIClient class
New MCP Tools: Add to both JSON-RPC and FastMCP implementations
New Analytics: Implement in tool methods with data processing
Configuration: Update config schema for new parameters

Rate Limiting

The client automatically manages rate limits:

Default: 60 requests per minute
Caching: Reduces API calls with intelligent TTL
Backoff: Automatic retry with exponential backoff

Business Intelligence Capabilities

Market Analysis

Service availability by location and time
Fleet composition and utilization rates
Demand patterns and peak hour identification

Pricing Intelligence

Real-time fare analysis with surge detection
Fee breakdown and cost optimization
Route pricing comparisons

Operational Insights

Vehicle availability patterns
Driver performance metrics
Service quality indicators

Security

Authentication

API Keys: Secure Curb API token management
OAuth 2.0: Enterprise authentication for Claude.ai
Rate Limiting: Protection against API abuse

Data Privacy

No sensitive ride data storage
Minimal caching with TTL expiration
Secure credential management

Deployment

Local Development

./run_curb_server.sh

Production Deployment

# HTTP mode for remote access
PORT=8080 ./run_curb_server.sh --http

Docker Support

FROM python:3.9-slim
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
CMD ["python", "curb_mcp_server.py", "--http"]

Troubleshooting

Common Issues

API Token Invalid

Error: Invalid API credentials
Solution: Check your Curb API token in config.json

Rate Limit Exceeded

Error: Rate limit exceeded
Solution: Client automatically handles this with caching

No Services Available

Error: No services at location
Solution: Location may be outside Curb's service area

Debug Mode

# Enable verbose logging
DEBUG=1 python curb_mcp_server.py

Support

Resources

Curb API Docs: Contact Curb Mobility for documentation
MCP Protocol: https://spec.modelcontextprotocol.io/
Claude Code: https://claude.ai/code

Getting Help

Check the troubleshooting section
Review API client test results
Verify configuration settings
Contact Curb Mobility for API issues

License

MIT License - see LICENSE file for details.

🚕 Ready to analyze ride-sharing data with intelligence and insights!