Hostaway MCP Server

# Feature Specification: Hostaway MCP Server with Authentication **Feature Branch**: `001-we-need-to` **Created**: 2025-10-12 **Status**: Draft **Input**: User description: "We need to add authentication using the API key and then token exchange so we can access the host. We need to create a full MCP server that can have access to the host. I'm going to put here the documentation for the host API. We should pull down all the relevant information and how we can implement a full operational MCP server that connects to the host API. https://api.hostaway.com/documentation" ## User Scenarios & Testing *(mandatory)* ### User Story 1 - AI Agent Authentication (Priority: P1) An AI assistant needs to authenticate with the Hostaway property management system to access property, booking, and guest information on behalf of a property manager. **Why this priority**: Authentication is the foundation - without it, no other MCP tools can function. This enables the core value proposition of AI-assisted property management. **Independent Test**: Can be fully tested by providing valid credentials and verifying successful authentication, which delivers immediate value by proving the connection to Hostaway works. **Acceptance Scenarios**: 1. **Given** valid Hostaway API credentials (account ID and secret), **When** the AI agent attempts to authenticate, **Then** the system successfully obtains an access token 2. **Given** invalid or expired credentials, **When** authentication is attempted, **Then** the system returns a clear error message indicating authentication failure 3. **Given** a valid access token, **When** the token is near expiration, **Then** the system automatically refreshes the token without user intervention --- ### User Story 2 - Property Information Access (Priority: P1) An AI assistant retrieves property listing details to answer questions about available rentals, amenities, and property characteristics for a property manager or potential guest. **Why this priority**: Accessing property data is the primary use case for property management - AI needs to know what properties exist and their details to be useful. **Independent Test**: Can be tested by authenticating and retrieving a list of properties, then getting detailed information about a specific property - delivers immediate value for property inquiries. **Acceptance Scenarios**: 1. **Given** authenticated access, **When** the AI requests all properties, **Then** the system returns a complete list of managed properties with basic details 2. **Given** a specific property ID, **When** the AI requests detailed information, **Then** the system returns comprehensive property details including amenities, location, and capacity 3. **Given** no properties exist, **When** the AI requests property list, **Then** the system returns an empty list with appropriate messaging --- ### User Story 3 - Booking Management (Priority: P2) An AI assistant searches for, retrieves, and manages booking information to help property managers track reservations, check-ins, check-outs, and guest stays. **Why this priority**: Booking management is the second most critical function after property access - property managers need AI help with reservation logistics. **Independent Test**: Can be tested by searching for bookings within a date range and retrieving specific booking details - provides value for reservation management. **Acceptance Scenarios**: 1. **Given** authenticated access, **When** the AI searches for bookings within a date range, **Then** the system returns all matching reservations with guest and property information 2. **Given** a specific booking ID, **When** the AI requests booking details, **Then** the system returns complete reservation information including dates, guest details, and payment status 3. **Given** booking search filters (property, status, date range), **When** the AI applies these filters, **Then** the system returns only bookings matching all specified criteria --- ### User Story 4 - Guest Communication (Priority: P2) An AI assistant sends messages to guests on behalf of property managers for check-in instructions, local recommendations, or issue resolution. **Why this priority**: Communication automation is a key value driver - AI can handle routine guest messaging, saving property managers significant time. **Independent Test**: Can be tested by sending a test message to a guest and verifying delivery - demonstrates immediate communication automation value. **Acceptance Scenarios**: 1. **Given** a booking ID and message content, **When** the AI sends a message to the guest, **Then** the message is delivered through the appropriate channel (email, SMS, or platform messaging) 2. **Given** invalid booking or guest information, **When** a message send is attempted, **Then** the system returns an error explaining the issue 3. **Given** message templates, **When** the AI uses a template with guest-specific data, **Then** personalized messages are sent with correct guest information --- ### User Story 5 - Financial and Calendar Information (Priority: P3) An AI assistant retrieves financial reports and calendar availability to help property managers understand revenue and manage bookings. **Why this priority**: While important, financial and calendar data are supporting features - the core property and booking management must work first. **Independent Test**: Can be tested by requesting revenue reports or calendar availability for a property - provides analytical value for business decisions. **Acceptance Scenarios**: 1. **Given** a date range, **When** the AI requests revenue data, **Then** the system returns financial summaries for all properties 2. **Given** a property ID and date range, **When** the AI checks availability, **Then** the system returns available and blocked dates 3. **Given** multiple properties, **When** the AI requests comparative financial data, **Then** the system returns aggregated and property-specific metrics --- ### Edge Cases - What happens when the access token expires during an active AI session? - How does the system handle rate limit violations (15 requests per 10 seconds)? - What occurs when Hostaway API is temporarily unavailable or returns errors? - How are partial failures handled (e.g., some properties retrieved, others failed)? - What happens when network connectivity is lost mid-request? - How does the system behave with very large datasets (hundreds of properties or bookings)? - What occurs when guest contact information is missing or invalid? ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST authenticate using Hostaway credentials (account ID and client secret) to obtain OAuth access tokens - **FR-002**: System MUST automatically refresh access tokens before expiration (24-month validity period) - **FR-003**: System MUST respect Hostaway rate limits (15 requests per 10 seconds per IP, 20 per 10 seconds per account) - **FR-004**: System MUST expose property listing operations as AI-callable tools (list all properties, get property details, check availability) - **FR-005**: System MUST expose booking operations as AI-callable tools (search bookings, get booking details, retrieve reservation information) - **FR-006**: System MUST expose guest communication operations as AI-callable tools (send messages via email, SMS, or platform messaging) - **FR-007**: System MUST expose financial operations as AI-callable tools (retrieve revenue reports, expense tracking) - **FR-008**: System MUST expose calendar operations as AI-callable tools (check availability, view blocked dates) - **FR-009**: System MUST provide clear error messages when authentication fails, API limits are exceeded, or Hostaway services are unavailable - **FR-010**: System MUST securely store and manage credentials (environment variables, never in code or logs) - **FR-011**: System MUST validate all inputs to prevent injection attacks or malformed requests - **FR-012**: System MUST log all AI tool invocations with user context for audit purposes - **FR-013**: System MUST handle partial failures gracefully (return available data, report failed operations) - **FR-014**: System MUST support concurrent AI requests without credential conflicts or race conditions - **FR-015**: System MUST automatically retry failed requests with exponential backoff for transient errors ### Key Entities - **Credentials**: Account ID, client secret, and access token used for Hostaway authentication - stored securely, refreshed automatically - **Property/Listing**: Rental property details including location, amenities, capacity, availability - the primary resource managed - **Booking/Reservation**: Guest reservation including dates, guest information, payment status, property assignment - **Guest**: Individual renting a property - includes contact information, preferences, booking history - **Message**: Communication sent to guests - includes content, channel (email/SMS/platform), delivery status - **Access Token**: OAuth token granting API access - valid for 24 months, refreshable, revocable - **Financial Record**: Revenue, expenses, payments associated with properties and bookings - **Calendar**: Property availability including blocked dates, reservations, maintenance windows ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: AI agents can successfully authenticate and access Hostaway data within 5 seconds of first request - **SC-002**: System handles 100 concurrent AI requests without authentication failures or token conflicts - **SC-003**: 99% of property, booking, and guest information requests return results within 2 seconds - **SC-004**: Access tokens are refreshed automatically with zero service interruption or manual intervention - **SC-005**: Rate limit compliance maintained - zero requests rejected due to exceeding Hostaway thresholds - **SC-006**: Property managers can delegate 80% of routine guest communication to AI without manual review - **SC-007**: Financial and booking data retrieval accuracy is 100% (matches Hostaway portal exactly) - **SC-008**: System uptime of 99.9% excluding Hostaway API downtime - **SC-009**: Authentication errors are resolved within one retry attempt 95% of the time - **SC-010**: AI tool response time averages under 1 second for cached property/booking data ### User Value Metrics - **SC-011**: Property managers save 10+ hours per week on routine inquiries and guest communication - **SC-012**: Guest response time improves by 75% compared to manual communication - **SC-013**: Booking inquiry resolution increases by 50% through AI-assisted information access - **SC-014**: Property data accuracy (amenities, availability) improves to 98%+ through real-time API sync ## Assumptions - Hostaway API documentation at https://api.hostaway.com/documentation is current and accurate - OAuth 2.0 Client Credentials Grant is the standard authentication method (not API keys alone) - Property managers have valid Hostaway accounts with API access enabled - Access tokens have 24-month validity as documented - Rate limits (15 req/10s per IP, 20 req/10s per account) are enforced consistently - AI agents will primarily access read operations (listings, bookings, messages) with limited write operations - Network connectivity is generally reliable with standard retry mechanisms sufficient for transient failures - Property managers understand basic MCP tool concepts and can configure AI assistants - Guest contact information in Hostaway is reasonably up-to-date and valid - The MCP server will be deployed in an environment with secure credential storage capabilities ## Scope ### In Scope - OAuth 2.0 authentication with Hostaway API - Automatic token refresh and credential management - Property/listing data access (list, details, availability) - Booking/reservation management (search, details, status) - Guest communication (send messages via email/SMS/platform) - Financial data retrieval (revenue, expenses) - Calendar operations (availability checks, blocked dates) - Rate limit compliance and retry logic - Comprehensive error handling and logging - Audit trail for AI tool invocations ### Out of Scope - Direct database access to Hostaway systems (API-only access) - Real-time streaming of booking updates (polling-based only) - Custom property management features beyond Hostaway API capabilities - Integration with non-Hostaway booking platforms - Advanced analytics or machine learning on property data (beyond simple aggregation) - User interface for direct human interaction (MCP tools for AI only) - Payment processing or financial transactions (read-only financial data) - Property maintenance scheduling (unless supported by Hostaway API) - Multi-tenant support for multiple Hostaway accounts (single account per deployment) ## Dependencies - Hostaway API availability and uptime (external dependency) - Valid Hostaway account with API access enabled - Network connectivity for API requests - Secure credential storage mechanism (environment variables or secrets manager) - AI assistant/agent capable of consuming MCP tools (e.g., Claude Desktop, custom client) - Understanding of Hostaway API rate limits and quotas ## Security Considerations - Credentials MUST be stored in environment variables or dedicated secrets management system - Access tokens MUST be transmitted over HTTPS only - API responses MUST NOT log sensitive guest information (PII, payment details) - Token refresh operations MUST be thread-safe and prevent race conditions - Rate limiting MUST be implemented client-side to prevent API lockout - All AI tool invocations MUST be audit logged with timestamp and user context - Invalid or expired credentials MUST fail fast with clear error messages (no retries with bad creds) - Guest message content MUST be sanitized to prevent injection attacks or unintended disclosure