Travel Company MCP Server

# MCP Server Demo - System Requirements ## Project Overview An MCP (Model Context Protocol) server that provides Claude with access to a travel company's customer data through a chat interface. The server will expose tools and resources that allow secure querying of customer information, trip history, and customer inquiries. ## Functional Requirements ### 1. MCP Server Core - **FR-1.1**: Implement MCP protocol using Python SDK - **FR-1.2**: Support standard MCP server lifecycle (initialization, request handling, shutdown) - **FR-1.3**: Provide server metadata and capabilities - **FR-1.4**: Handle client connections via stdio transport ### 2. Data Access Tools #### 2.1 Customer Management - **FR-2.1**: Customer search tool - Search by customer ID, name, email, or phone number - Return customer details (id, name, email, phone, address, registration_date, loyalty_tier) - Support partial/fuzzy matching on name - **FR-2.2**: Customer profile tool - Get complete customer profile by customer ID - Include customer details, total trips, lifetime spending, preferences #### 2.2 Trip Management - **FR-2.3**: Trip history tool - Query trips by customer ID - Filter by date range, location, or status - Return trip details (trip_id, customer_id, destination, start_date, end_date, cost, status, booking_date) - **FR-2.4**: Trip search tool - Search all trips by destination, date range, or status - Support aggregation (total trips to destination, revenue by location) #### 2.3 Request Management - **FR-2.5**: Customer inquiry tool - Search information requests by customer email, date, or destination interest - Return request details (request_id, name, email, phone, destination_interest, travel_dates, num_travelers, budget_range, message, request_date, status) - **FR-2.6**: Pending requests tool - List all pending/uncontacted customer requests - Filter by date range or destination ### 3. Resources - **FR-3.1**: Popular destinations resource (list of destinations with descriptions) - **FR-3.2**: Travel packages resource (standard package offerings) - **FR-3.3**: Customer service guidelines resource ### 4. Security & Access Control - **FR-4.1**: Implement basic authentication mechanism - **FR-4.2**: Role-based access control (e.g., sales vs. support access levels) - **FR-4.3**: Audit logging of all data access requests - **FR-4.4**: PII protection and sanitization options ## Non-Functional Requirements ### 1. Performance - **NFR-1.1**: Response time < 2 seconds for typical queries - **NFR-1.2**: Support concurrent client connections - **NFR-1.3**: Efficient data indexing for fast customer/trip searches ### 2. Reliability - **NFR-2.1**: Graceful error handling and recovery - **NFR-2.2**: Proper logging for debugging and monitoring - **NFR-2.3**: Input validation for all tool parameters ### 3. Maintainability - **NFR-3.1**: Well-documented code with docstrings - **NFR-3.2**: Modular architecture for easy extension - **NFR-3.3**: Configuration file for easy deployment ### 4. Usability - **NFR-4.1**: Clear tool descriptions for Claude to understand - **NFR-4.2**: Helpful error messages - **NFR-4.3**: Example queries in documentation ## Technical Requirements ### 1. Technology Stack - **TR-1.1**: Python 3.10 or higher - **TR-1.2**: MCP Python SDK (`mcp` package) - **TR-1.3**: SQLite for demo data storage - **TR-1.4**: JSON for configuration files ### 2. Data Model #### 2.1 Customer Table - customer_id (PRIMARY KEY) - name (TEXT) - email (TEXT, UNIQUE) - phone (TEXT) - address (TEXT) - city (TEXT) - state (TEXT) - country (TEXT) - registration_date (DATE) - loyalty_tier (TEXT: Bronze/Silver/Gold/Platinum) - preferences (JSON: dietary, accessibility, interests) #### 2.2 Trip Table - trip_id (PRIMARY KEY) - customer_id (FOREIGN KEY) - destination (TEXT) - start_date (DATE) - end_date (DATE) - cost (DECIMAL) - status (TEXT: completed/upcoming/cancelled) - booking_date (DATE) - num_travelers (INTEGER) - trip_type (TEXT: adventure/luxury/family/cultural) - notes (TEXT) #### 2.3 Request Table - request_id (PRIMARY KEY) - name (TEXT) - email (TEXT) - phone (TEXT) - destination_interest (TEXT) - travel_dates (TEXT) - num_travelers (INTEGER) - budget_range (TEXT) - message (TEXT) - request_date (DATE) - status (TEXT: pending/contacted/converted/closed) ### 3. MCP Tools Interface Each tool should define: - **TR-3.1**: Clear name and description - **TR-3.2**: JSON schema for input parameters - **TR-3.3**: Structured output format - **TR-3.4**: Error handling with appropriate error types ### 4. Configuration - **TR-4.1**: Server configuration (name, version) - **TR-4.2**: Database connection settings - **TR-4.3**: Access control policies - **TR-4.4**: Logging configuration ## Data Requirements ### 1. Demo Dataset - **DR-1.1**: 100+ customer records with diverse demographics - **DR-1.2**: 200+ trip records spanning multiple destinations and dates - **DR-1.3**: 50+ information requests in various states - **DR-1.4**: 10+ popular destinations ### 2. Data Quality - **DR-2.1**: Realistic travel company data demonstrating use cases - **DR-2.2**: No real customer PII - **DR-2.3**: Consistent formatting and data types - **DR-2.4**: Mix of completed, upcoming, and cancelled trips - **DR-2.5**: Requests at different stages of the sales funnel ## Deployment Requirements ### 1. Installation - **DEP-1.1**: `requirements.txt` with all dependencies - **DEP-1.2**: Setup script for database initialization and seed data - **DEP-1.3**: Configuration template files ### 2. Documentation - **DEP-2.1**: README with installation instructions - **DEP-2.2**: Usage examples for integrating with Claude Desktop - **DEP-2.3**: Architecture diagram - **DEP-2.4**: API documentation for all tools ### 3. Testing - **DEP-3.1**: Example queries to demonstrate functionality - **DEP-3.2**: Test data validation - **DEP-3.3**: Error scenario handling ## Example Use Cases 1. **Customer Support**: "Show me all trips for customer John Smith" 2. **Sales Follow-up**: "List all pending requests from the last week" 3. **Analytics**: "How many customers have traveled to Paris in 2024?" 4. **Customer Service**: "Find the customer with email john@example.com and their trip history" 5. **Lead Management**: "Show me requests for trips to Japan with budgets over $5000" ## Future Enhancements (Out of Scope for Demo) - Real-time booking integration - Payment processing - Email/SMS automation for follow-ups - Advanced analytics and reporting - Multi-tenant support for travel agencies - Integration with external booking systems - Customer feedback and reviews ## Success Criteria 1. MCP server successfully connects with Claude Desktop 2. All defined tools are accessible and functional 3. Demo queries return accurate, well-formatted results 4. System handles errors gracefully 5. Documentation is clear and complete 6. Code is maintainable and extensible