Travel Company MCP Server

# MCP Server Architecture ## System Overview The Travel Company MCP Server is a Python-based application that implements the Model Context Protocol to provide Claude with access to customer, trip, and request data. ``` ┌─────────────────────────────────────────────────────────────┐ │ Claude Desktop │ │ (MCP Client) │ └────────────────────────┬────────────────────────────────────┘ │ stdio transport │ MCP Protocol ┌────────────────────────▼────────────────────────────────────┐ │ MCP Server (Python) │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Server Core (main.py) │ │ │ │ - Request routing │ │ │ │ - Tool registration │ │ │ │ - Resource management │ │ │ │ - Error handling │ │ │ └─────────┬────────────────────────────────┬───────────┘ │ │ │ │ │ │ ┌─────────▼──────────┐ ┌──────────▼────────────┐ │ │ │ Tools Module │ │ Resources Module │ │ │ │ - search_customers│ │ - destinations │ │ │ │ - get_customer │ │ - travel_packages │ │ │ │ - search_trips │ │ - service_guidelines │ │ │ │ - get_trip_history│ └───────────────────────┘ │ │ │ - search_requests │ │ │ │ - get_pending_req │ │ │ └─────────┬──────────┘ │ │ │ │ │ ┌─────────▼──────────────────────────────────────────┐ │ │ │ Database Layer (database.py) │ │ │ │ - Connection management │ │ │ │ - Query execution │ │ │ │ - Data validation │ │ │ │ - Result formatting │ │ │ └─────────┬──────────────────────────────────────────┘ │ └────────────┼──────────────────────────────────────────────┘ │ ┌────────────▼────────────────────────────────────────────┐ │ SQLite Database │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ customers │ │ trips │ │ requests │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` ## Component Details ### 1. Server Core (`src/server.py`) **Responsibilities:** - Initialize MCP server with metadata - Register all tools and resources - Handle incoming requests from Claude - Route requests to appropriate handlers - Manage server lifecycle **Key Classes/Functions:** ```python class TravelMCPServer: - __init__(): Initialize server with database - register_tools(): Register all MCP tools - register_resources(): Register all MCP resources - run(): Start the server ``` ### 2. Tools Module (`src/tools/`) Each tool is implemented as a function that: - Accepts structured parameters (validated by MCP) - Queries the database layer - Returns formatted results - Handles errors gracefully **Tool Structure:** ``` src/tools/ ├── __init__.py ├── customer_tools.py │ ├── search_customers() │ └── get_customer_profile() ├── trip_tools.py │ ├── search_trips() │ └── get_trip_history() └── request_tools.py ├── search_requests() └── get_pending_requests() ``` **Tool Definitions:** #### customer_tools.py - `search_customers(query: str, search_by: str)` - Search by name, email, phone, or customer_id - Returns list of matching customers - `get_customer_profile(customer_id: int)` - Returns complete customer profile - Includes summary statistics (total trips, lifetime spending) #### trip_tools.py - `search_trips(destination: str, start_date: str, end_date: str, status: str)` - Search trips by various criteria - Returns list of matching trips - `get_trip_history(customer_id: int, limit: int)` - Returns trip history for specific customer - Ordered by date (most recent first) #### request_tools.py - `search_requests(email: str, destination: str, status: str, date_from: str, date_to: str)` - Search information requests - Returns list of matching requests - `get_pending_requests(days_back: int)` - Returns pending requests within timeframe - Useful for follow-up workflows ### 3. Database Layer (`src/database.py`) **Responsibilities:** - Manage SQLite connection - Execute queries safely (parameterized) - Initialize database schema - Seed demo data - Format query results **Key Classes/Functions:** ```python class Database: - __init__(db_path: str): Initialize connection - initialize_schema(): Create tables - seed_data(): Insert demo data - query(sql: str, params: tuple): Execute query - close(): Close connection class CustomerDB: - search(query, search_by): Customer search logic - get_by_id(customer_id): Get customer details - get_profile(customer_id): Get profile with stats class TripDB: - search(filters): Trip search logic - get_by_customer(customer_id): Get customer trips - get_statistics(customer_id): Trip stats class RequestDB: - search(filters): Request search logic - get_pending(days_back): Get pending requests - get_by_status(status): Filter by status ``` ### 4. Resources Module (`src/resources/`) Static resources that Claude can access: ``` src/resources/ ├── __init__.py ├── destinations.json # Popular destinations with descriptions ├── travel_packages.json # Standard package offerings └── service_guidelines.md # Customer service guidelines ``` ### 5. Configuration (`config/`) ``` config/ ├── server_config.json # Server settings └── logging_config.json # Logging configuration ``` **server_config.json:** ```json { "server_name": "travel-company-mcp", "version": "1.0.0", "database": { "path": "data/travel_company.db" }, "logging": { "level": "INFO", "file": "logs/server.log" } } ``` ### 6. Data Initialization (`src/seed_data.py`) **Responsibilities:** - Generate realistic demo data - Insert data into database - Ensure data consistency **Data Generation:** - 100+ customers with realistic names, emails, addresses - 200+ trips across popular destinations - 50+ requests in various states - Relationships between customers and trips ## Project Structure ``` mcpdemo/ ├── README.md ├── REQUIREMENTS.md ├── ARCHITECTURE.md ├── requirements.txt ├── setup.py ├── config/ │ ├── server_config.json │ └── logging_config.json ├── src/ │ ├── __init__.py │ ├── server.py # Main MCP server │ ├── database.py # Database layer │ ├── seed_data.py # Demo data generation │ ├── tools/ │ │ ├── __init__.py │ │ ├── customer_tools.py │ │ ├── trip_tools.py │ │ └── request_tools.py │ └── resources/ │ ├── __init__.py │ ├── destinations.json │ ├── travel_packages.json │ └── service_guidelines.md ├── data/ │ └── travel_company.db # SQLite database (created on init) ├── logs/ │ └── server.log # Server logs └── tests/ ├── __init__.py ├── test_tools.py └── test_database.py ``` ## Data Flow ### Example: Customer Search Request ``` 1. Claude sends request: { "method": "tools/call", "params": { "name": "search_customers", "arguments": { "query": "john", "search_by": "name" } } } 2. Server routes to customer_tools.search_customers() 3. Tool calls database.CustomerDB.search("john", "name") 4. Database executes: SELECT * FROM customers WHERE name LIKE '%john%' LIMIT 50 5. Results formatted and returned: [ { "customer_id": 123, "name": "John Smith", "email": "john.smith@email.com", "phone": "(555) 123-4567", "loyalty_tier": "Gold" }, ... ] 6. Server sends response back to Claude 7. Claude uses data to answer user's question ``` ## Error Handling ### Error Types - **ValidationError**: Invalid input parameters - **DatabaseError**: Database query failures - **NotFoundError**: Resource not found - **AuthenticationError**: Access denied (future) ### Error Response Format ```json { "error": { "code": "NOT_FOUND", "message": "Customer with ID 999 not found", "details": {} } } ``` ## Security Considerations ### Current Implementation (Demo) - No authentication (local use only) - Read-only database access - Input validation and parameterized queries - No real customer PII ### Production Considerations (Future) - API key authentication - Role-based access control - Audit logging - PII encryption - Rate limiting - HTTPS transport ## Performance Considerations ### Optimization Strategies - Database indexes on frequently queried fields - customers(email, name) - trips(customer_id, destination, start_date) - requests(email, status, request_date) - Connection pooling for concurrent requests - Query result caching (future) - Pagination for large result sets ### Expected Performance - Customer search: < 100ms - Trip history: < 150ms - Request search: < 100ms - Cold start: < 500ms ## Extension Points ### Adding New Tools 1. Create tool function in appropriate module 2. Define JSON schema for parameters 3. Implement database queries 4. Register tool in server.py 5. Add tests ### Adding New Data Types 1. Define schema in database.py 2. Create DB access class 3. Add seed data generation 4. Create corresponding tools 5. Update documentation ### Adding Resources 1. Create resource file (JSON/MD) 2. Register in resources module 3. Document resource structure 4. Reference in tool descriptions