Hostaway MCP Server

# Tasks: Hostaway MCP Server with Authentication **Input**: Design documents from `/Users/darrenmorgan/AI_Projects/hostaway-mcp/specs/001-we-need-to/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/ **Tests**: TDD approach - tests are MANDATORY per constitutional principle IV (80% coverage target) **Organization**: Tasks grouped by user story for independent implementation and testing ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: User story this task belongs to (US1-US5, or SETUP/FOUND for infrastructure) - File paths are absolute for clarity --- ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Project initialization and basic structure - [X] T001 [SETUP] Create project directory structure per plan.md: `src/{api,mcp,services,models}`, `tests/{unit,integration,mcp}` - [X] T002 [P] [SETUP] Initialize Python 3.12 project with pyproject.toml and uv.lock - [X] T003 [P] [SETUP] Install core dependencies: FastAPI 0.100+, fastapi-mcp 0.4+, httpx 0.27+, Pydantic 2.0+, pydantic-settings - [X] T004 [P] [SETUP] Install development dependencies: pytest, pytest-asyncio, pytest-cov, ruff, mypy, tenacity, aiolimiter - [X] T005 [P] [SETUP] Configure ruff for linting and formatting in pyproject.toml - [X] T006 [P] [SETUP] Configure mypy for --strict type checking in pyproject.toml - [X] T007 [P] [SETUP] Create .env.example template with Hostaway credentials placeholders --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Core infrastructure that MUST complete before ANY user story implementation **⚠️ CRITICAL**: No user story work can begin until this phase is complete - [X] T008 [P] [FOUND] Create HostawayConfig model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/config.py` using pydantic-settings for environment variables - [X] T009 [P] [FOUND] Create AccessToken model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/auth.py` with expiration tracking and `should_refresh()` method - [X] T010 [P] [FOUND] Create TokenRefreshRequest and TokenRefreshResponse models in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/auth.py` - [X] T011 [FOUND] Implement TokenManager class in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/auth.py` for OAuth 2.0 Client Credentials Grant flow (depends on T008, T009, T010) - [X] T012 [FOUND] Add automatic token refresh logic to TokenManager with 7-day proactive refresh (depends on T011) - [X] T013 [FOUND] Implement thread-safe token storage using asyncio.Lock in TokenManager (depends on T011) - [X] T014 [P] [FOUND] Create RateLimiter class in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/rate_limiter.py` using aiolimiter for token bucket algorithm - [X] T015 [FOUND] Add dual rate limiting (15 req/10s IP, 20 req/10s account) and Semaphore concurrency control to RateLimiter (depends on T014) - [X] T016 [P] [FOUND] Create HostawayClient class in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` with httpx.AsyncClient singleton - [X] T017 [FOUND] Configure connection pooling (50 max, 20 keep-alive) and timeouts in HostawayClient (depends on T016) - [X] T018 [FOUND] Add exponential backoff retry logic (2s, 4s, 8s) using tenacity to HostawayClient (depends on T016) - [X] T019 [FOUND] Integrate TokenManager and RateLimiter into HostawayClient request flow (depends on T011, T015, T016) - [X] T020 [P] [FOUND] Create FastAPI app instance in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/main.py` with CORS and middleware configuration - [X] T021 [FOUND] Initialize FastAPI-MCP server in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/server.py` and mount to FastAPI app (depends on T020) - [X] T022 [FOUND] Create authentication dependency `get_authenticated_client()` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/auth.py` using Depends() (depends on T011, T016) ### Tests for Foundational Phase - [X] T023 [P] [FOUND] Unit test for HostawayConfig loading environment variables in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_config.py` - [X] T024 [P] [FOUND] Unit test for AccessToken expiration logic and `should_refresh()` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_auth.py` - [X] T025 [P] [FOUND] Unit test for TokenManager OAuth flow (mocked httpx responses) in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_auth.py` - [X] T026 [P] [FOUND] Unit test for TokenManager automatic refresh logic in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_auth.py` - [X] T027 [P] [FOUND] Unit test for RateLimiter token bucket behavior in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_rate_limiter.py` - [X] T028 [P] [FOUND] Unit test for RateLimiter semaphore concurrency control in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_rate_limiter.py` - [X] T029 [P] [FOUND] Unit test for HostawayClient retry logic (simulated failures) in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_hostaway_client.py` **Checkpoint**: Foundation ready - user story implementation can now begin in parallel --- ## Phase 2.5: Cross-Cutting Error Handling (FR-013 Partial Failures) **Purpose**: Implement partial failure handling and error recovery patterns - [ ] T029a [P] [FOUND] Create PartialFailureResponse model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/errors.py` with successful/failed operation tracking - [ ] T029b [P] [FOUND] Add error recovery middleware to FastAPI app in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/main.py` for graceful degradation - [ ] T029c [FOUND] Implement batch operation handler in HostawayClient for partial success scenarios (depends on T029a) - [ ] T029d [P] [FOUND] Unit test for partial failure response model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_errors.py` - [ ] T029e [P] [FOUND] Integration test for batch operations with mixed success/failure in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_error_handling.py` --- ## Phase 3: User Story 1 - AI Agent Authentication (Priority: P1) 🎯 MVP **Goal**: AI assistant authenticates with Hostaway to access property/booking/guest data **Independent Test**: Provide valid credentials → system obtains access token within 5 seconds ### Tests for User Story 1 (TDD - Write FIRST, ensure FAIL before implementation) - [X] T030 [P] [US1] Contract test for OAuth token endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_auth_api.py` - verify token exchange works - [X] T031 [P] [US1] Integration test for authentication flow in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_auth_api.py` - test valid/invalid credentials - [X] T032 [P] [US1] Integration test for token refresh flow in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_auth_api.py` - verify auto-refresh works - [X] T033 [P] [US1] MCP protocol test for authentication tool discovery in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/mcp/test_tool_discovery.py` ### Implementation for User Story 1 - [X] T034 [US1] Add authentication error handling to TokenManager (401, 403, rate limits) in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/auth.py` - [X] T035 [US1] Add audit logging for authentication events (success/failure) to TokenManager in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/auth.py` - [X] T036 [US1] Register `authenticate_hostaway` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/auth.py` (manual token exchange for testing) - [X] T037 [US1] Register `refresh_token` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/auth.py` (manual token refresh) - [X] T038 [US1] Add health check endpoint `/health` to FastAPI app in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/main.py` for deployment verification **Checkpoint**: User Story 1 complete - authentication working, tokens managed, foundation solid --- ## Phase 4: User Story 2 - Property Information Access (Priority: P1) **Goal**: AI retrieves property listing details for property manager inquiries **Independent Test**: Authenticate → list properties → get specific property details → verify data returned ### Tests for User Story 2 (TDD - Write FIRST, ensure FAIL before implementation) - [X] T039 [P] [US2] Contract test for GET /listings endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_listings_api.py` - verify pagination works - [X] T040 [P] [US2] Contract test for GET /listings/{id} endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_listings_api.py` - verify property details - [X] T041 [P] [US2] Contract test for GET /listings/{id}/calendar endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_listings_api.py` - verify availability - [X] T042 [P] [US2] Integration test for property listing flow in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_listings_api.py` - auth → list → details - [X] T043 [P] [US2] Unit test for listings models in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/unit/test_listings.py` ### Implementation for User Story 2 - [X] T044 [P] [US2] Create Listing model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/listings.py` with full property details per data-model.md - [X] T045 [P] [US2] Create ListingSummary model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/listings.py` for abbreviated list responses - [X] T046 [P] [US2] Create PricingInfo model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/listings.py` with rates and fees - [X] T047 [P] [US2] Create AvailabilityInfo model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/listings.py` with calendar data - [X] T048 [US2] Add `get_listings()` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T044, T045) - [X] T049 [US2] Add `get_listing_by_id(listing_id)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T044) - [X] T050 [US2] Add `get_listing_availability(listing_id, check_in, check_out)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T047) - [X] T051 [US2] Create FastAPI route `GET /listings` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/listings.py` with pagination and filters (depends on T048) - [X] T052 [US2] Create FastAPI route `GET /listings/{id}` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/listings.py` (depends on T049) - [X] T053 [US2] Create FastAPI route `GET /listings/{id}/availability` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/listings.py` (depends on T050) - [X] T054 [US2] Register `list_all_properties` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/main.py` - routes auto-exposed as tools (depends on T051) - [X] T055 [US2] Register `get_property_details` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/main.py` - routes auto-exposed as tools (depends on T052) - [X] T056 [US2] Register `check_property_availability` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/main.py` - routes auto-exposed as tools (depends on T053) - [X] T057 [US2] Add error handling for empty property lists and 404 not found in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/listings.py` **Checkpoint**: User Stories 1 AND 2 complete - authentication + property access both work independently --- ## Phase 5: User Story 3 - Booking Management (Priority: P2) **Goal**: AI searches and retrieves booking information for reservation management **Independent Test**: Authenticate → search bookings by date range → get specific booking → verify data ### Tests for User Story 3 (TDD - Write FIRST, ensure FAIL before implementation) - [X] T058 [P] [US3] Contract test for GET /reservations endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_bookings_api.py` - verify search filters - [X] T059 [P] [US3] Contract test for GET /reservations/{id} endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_bookings_api.py` - verify booking details - [X] T060 [P] [US3] Contract test for GET /reservations/{id}/guest endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_bookings_api.py` - verify guest info - [X] T061 [P] [US3] Integration test for booking search flow in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_bookings_api.py` - filters → results - [X] T062 [P] [US3] MCP protocol test for booking tools invocation in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/mcp/test_tool_invocation.py` ### Implementation for User Story 3 - [X] T063 [P] [US3] Create Booking model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/bookings.py` with full reservation details per data-model.md - [X] T064 [P] [US3] Create BookingSearchFilters model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/bookings.py` for search criteria - [X] T065 [P] [US3] Create PaymentInfo model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/bookings.py` with payment status - [X] T066 [P] [US3] Create BookingStatus and PaymentStatus enums in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/bookings.py` - [X] T067 [US3] Add `search_bookings(filters)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T063, T064) - [X] T068 [US3] Add `get_booking_by_id(booking_id)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T063) - [X] T069 [US3] Add `get_booking_guest(booking_id)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T063) - [X] T070 [US3] Create FastAPI route `GET /reservations` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/bookings.py` with search filters (depends on T067) - [X] T071 [US3] Create FastAPI route `GET /reservations/{id}` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/bookings.py` (depends on T068) - [X] T072 [US3] Create FastAPI route `GET /reservations/{id}/guest` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/bookings.py` (depends on T069) - [X] T073 [US3] Register `search_bookings` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/server.py` (depends on T070) - [X] T074 [US3] Register `get_booking_details` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/server.py` (depends on T071) - [X] T075 [US3] Register `get_booking_guest_info` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/server.py` (depends on T072) - [X] T076 [US3] Add error handling for invalid date ranges and booking not found in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/bookings.py` **Checkpoint**: User Stories 1, 2, AND 3 complete - auth + properties + bookings all work independently --- ## Phase 6: User Story 4 - Guest Communication (Priority: P2) **Goal**: AI sends messages to guests for check-in instructions and issue resolution **Independent Test**: Authenticate → send test message to guest → verify delivery status ### Tests for User Story 4 (TDD - Write FIRST, ensure FAIL before implementation) - [ ] T077 [P] [US4] Contract test for POST /messages endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_guests_api.py` - verify message sending - [ ] T078 [P] [US4] Contract test for GET /reservations/{id}/messages endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_guests_api.py` - verify conversation history - [ ] T079 [P] [US4] Integration test for guest messaging flow in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_guests_api.py` - send → verify - [ ] T080 [P] [US4] MCP protocol test for guest communication tools in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/mcp/test_tool_invocation.py` ### Implementation for User Story 4 - [ ] T081 [P] [US4] Create Guest model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/guests.py` with contact info per data-model.md - [ ] T082 [P] [US4] Create Message model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/guests.py` with delivery tracking - [ ] T083 [P] [US4] Create MessageChannel and MessageDeliveryStatus enums in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/guests.py` - [ ] T084 [US4] Add `send_message(booking_id, channel, content)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T082) - [ ] T085 [US4] Add `get_conversation_history(booking_id)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T082) - [ ] T086 [US4] Create FastAPI route `POST /messages` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/guests.py` with message validation (depends on T084) - [ ] T087 [US4] Create FastAPI route `GET /reservations/{id}/messages` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/guests.py` (depends on T085) - [ ] T088 [US4] Register `send_guest_message` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/server.py` (depends on T086) - [ ] T089 [US4] Register `get_conversation_history` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/server.py` (depends on T087) - [ ] T090 [US4] Add input sanitization for message content (prevent injection) in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/guests.py` - [ ] T091 [US4] Add error handling for invalid booking/guest info in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/guests.py` **Checkpoint**: User Stories 1-4 complete - core property management operations functional --- ## Phase 7: User Story 5 - Financial and Calendar Information (Priority: P3) **Goal**: AI retrieves financial reports and calendar availability for business decisions **Independent Test**: Authenticate → request revenue report for date range → verify financial data ### Tests for User Story 5 (TDD - Write FIRST, ensure FAIL before implementation) - [X] T092 [P] [US5] Contract test for GET /financialReports endpoint in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_financial_api.py` - verify revenue data - [X] T093 [P] [US5] Integration test for financial reporting flow in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/integration/test_financial_api.py` - date range → report - [X] T094 [P] [US5] MCP protocol test for financial tools invocation in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/mcp/test_tool_invocation.py` ### Implementation for User Story 5 - [X] T095 [P] [US5] Create FinancialReport model in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/financial.py` with revenue/expense breakdown per data-model.md - [X] T096 [P] [US5] Create RevenueBreakdown and ExpenseBreakdown models in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/models/financial.py` - [X] T097 [US5] Add `get_financial_report(start_date, end_date)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T095) - [X] T098 [US5] Add `get_property_financials(property_id, start_date, end_date)` method to HostawayClient in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/services/hostaway_client.py` (depends on T095) - [X] T099 [US5] Create FastAPI route `GET /financialReports` in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/financial.py` with date filters (depends on T097) - [X] T100 [US5] Register `get_revenue_report` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/server.py` (depends on T099) - [X] T101 [US5] Register `get_property_financials` MCP tool in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/server.py` (depends on T098) - [X] T102 [US5] Add error handling for invalid date ranges in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/api/routes/financial.py` **Checkpoint**: All user stories complete - full MCP server functional --- ## Phase 8: Polish & Cross-Cutting Concerns **Purpose**: Final improvements affecting multiple user stories ### E2E and Performance Testing - [X] T103 [P] [POLISH] E2E test for complete workflow: auth → list properties → search bookings (modified, no messaging) in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/e2e/test_complete_workflow.py` - [X] T104 [P] [POLISH] Load test for 100 concurrent requests in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/performance/test_load.py` - [X] T105 [P] [POLISH] Performance test for rate limiting under load in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/tests/performance/test_rate_limiting.py` ### Deployment & DevOps - [X] T106 [P] [POLISH] Create Dockerfile for containerized deployment with Python 3.12 slim base - [X] T107 [P] [POLISH] Create docker-compose.yml for local development with environment variables - [X] T108 [P] [POLISH] Create GitHub Actions CI/CD pipeline in `.github/workflows/ci.yml` (pytest, ruff, mypy) - [X] T109 [P] [POLISH] Configure pre-commit hooks for ruff format, ruff check, mypy in `.pre-commit-config.yaml` - [X] T110 [P] [POLISH] Add structured logging with correlation IDs for request tracing in `/Users/darrenmorgan/AI_Projects/hostaway-mcp/src/mcp/logging.py` ### Documentation & Code Quality - [X] T111 [P] [POLISH] Generate OpenAPI documentation from FastAPI app (auto-generated at /docs endpoint) - [X] T112 [P] [POLISH] Update README.md with quickstart instructions and MCP tool reference - [X] T113 [P] [POLISH] Create deployment runbook in `docs/DEPLOYMENT.md` with production checklist - [X] T114 [POLISH] Run coverage report - achieved 72.80% (below 80% target, core logic well-covered) - [X] T115 [POLISH] Security audit: no critical issues, 2 false positives (see security-audit.md) - [X] T116 [POLISH] Final code review: 93/100 quality score, production ready (see code-review-report.md) ### Validation - [X] T117 [POLISH] Run quickstart.md validation: Quick Start instructions verified working, fixed README auth endpoint path - [X] T118 [POLISH] Verify all MCP tools discoverable: 9 endpoints confirmed with proper metadata and descriptions - [X] T119 [POLISH] Performance validation: Auth 0.66s (<5s target), API 0.77s (<2s target), concurrent requests OK - [ ] T120 [POLISH] Final deployment to staging environment and smoke test all user stories (requires staging setup) --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies - start immediately - **Foundational (Phase 2)**: Depends on Setup → BLOCKS all user stories - **User Stories (Phases 3-7)**: All depend on Foundational completion - US1 (Auth) can start after Foundational - US2 (Properties) can start after Foundational (uses US1 auth but independently testable) - US3 (Bookings) can start after Foundational (uses US1 auth but independently testable) - US4 (Guests) can start after Foundational (uses US1 auth but independently testable) - US5 (Financial) can start after Foundational (uses US1 auth but independently testable) - **Polish (Phase 8)**: Depends on desired user stories completion ### User Story Dependencies - **US1 (Authentication)**: No dependencies on other user stories - foundational only - **US2 (Properties)**: Uses US1 for auth, but independently testable (can mock auth if needed) - **US3 (Bookings)**: Uses US1 for auth, but independently testable - **US4 (Guests)**: Uses US1 for auth, but independently testable - **US5 (Financial)**: Uses US1 for auth, but independently testable ### Within Each User Story - **Tests FIRST**: Write tests, ensure they FAIL, then implement - **Models before Services**: Pydantic models → service methods - **Services before Routes**: HostawayClient methods → FastAPI routes - **Routes before MCP Tools**: FastAPI endpoints → MCP tool registration - **Core before Polish**: Basic functionality → error handling → logging ### Parallel Opportunities **Setup Phase (Phase 1)**: - T002, T003, T004, T005, T006, T007 can run in parallel **Foundational Phase (Phase 2)**: - T008, T009, T010 can run in parallel (models) - T023, T024, T025, T026, T027, T028, T029 can run in parallel (tests) **User Story 2 (Properties)**: - T039, T040, T041, T042, T043 can run in parallel (tests) - T044, T045, T046, T047 can run in parallel (models) **User Story 3 (Bookings)**: - T058, T059, T060, T061, T062 can run in parallel (tests) - T063, T064, T065, T066 can run in parallel (models) **User Story 4 (Guests)**: - T077, T078, T079, T080 can run in parallel (tests) - T081, T082, T083 can run in parallel (models) **User Story 5 (Financial)**: - T092, T093, T094 can run in parallel (tests) - T095, T096 can run in parallel (models) **Polish Phase (Phase 8)**: - T103, T104, T105 can run in parallel (E2E/performance tests) - T106, T107, T108, T109, T110 can run in parallel (deployment) - T111, T112, T113 can run in parallel (documentation) **Cross-Story Parallelization**: Once Foundational phase completes, ALL user stories (US1-US5) can be developed in parallel by different team members --- ## Parallel Example: User Story 2 (Properties) ```bash # Launch all tests for User Story 2 in parallel: Task: "Contract test for GET /listings in tests/integration/test_listings_api.py" [T039] Task: "Contract test for GET /listings/{id} in tests/integration/test_listings_api.py" [T040] Task: "Contract test for GET /listings/{id}/calendar in tests/integration/test_listings_api.py" [T041] Task: "Integration test for property flow in tests/integration/test_listings_api.py" [T042] Task: "MCP test for listing tools in tests/mcp/test_tool_invocation.py" [T043] # After tests fail (as expected in TDD), launch all models in parallel: Task: "Create Listing model in src/models/listings.py" [T044] Task: "Create ListingSummary model in src/models/listings.py" [T045] Task: "Create PricingInfo model in src/models/listings.py" [T046] Task: "Create AvailabilityInfo model in src/models/listings.py" [T047] ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup (T001-T007) 2. Complete Phase 2: Foundational (T008-T029) - CRITICAL, blocks everything 3. Complete Phase 3: User Story 1 - Authentication (T030-T038) 4. **STOP and VALIDATE**: Test authentication independently 5. Deploy MVP if ready **MVP Delivers**: Working authentication with Hostaway, ready for tool development ### Incremental Delivery (Recommended) 1. **Sprint 1**: Setup + Foundational → Foundation ready 2. **Sprint 2**: User Story 1 (Auth) → Test independently → Deploy MVP 3. **Sprint 3**: User Story 2 (Properties) → Test independently → Deploy v0.2 4. **Sprint 4**: User Story 3 (Bookings) → Test independently → Deploy v0.3 5. **Sprint 5**: User Story 4 (Guests) → Test independently → Deploy v0.4 6. **Sprint 6**: User Story 5 (Financial) + Polish → Test all → Deploy v1.0 Each story adds value without breaking previous stories ### Parallel Team Strategy With 3+ developers after Foundational phase completes: 1. **Team completes Setup + Foundational together** (critical path) 2. **Once Foundational done, split work**: - Developer A: US1 (Auth) - T030-T038 - Developer B: US2 (Properties) - T039-T057 - Developer C: US3 (Bookings) - T058-T076 3. **Stories complete and integrate independently** 4. **Team reconvenes for US4, US5, Polish** --- ## Task Count Summary - **Total Tasks**: 125 - **Setup**: 7 tasks - **Foundational**: 22 tasks (15 implementation + 7 tests) - **Error Handling (FR-013)**: 5 tasks (3 implementation + 2 tests) - **User Story 1 (Auth)**: 9 tasks (4 tests + 5 implementation) - **User Story 2 (Properties)**: 19 tasks (5 tests + 14 implementation) - **User Story 3 (Bookings)**: 19 tasks (5 tests + 14 implementation) - **User Story 4 (Guests)**: 15 tasks (4 tests + 11 implementation) - **User Story 5 (Financial)**: 11 tasks (3 tests + 8 implementation) - **Polish & Cross-Cutting**: 18 tasks **Parallel Opportunities**: 45+ tasks marked [P] can run in parallel within phases --- ## Notes - **[P] tasks**: Different files, no dependencies, can parallelize - **[Story] labels**: Maps task to user story for traceability - **TDD enforced**: Tests written FIRST (must FAIL), then implementation - **Independent stories**: Each user story completable and testable on its own - **80% coverage target**: Constitutional requirement, validated in T114 - **Commit after each task** or logical group for incremental progress - **Stop at checkpoints** to validate story works independently - **Avoid**: Vague tasks, same-file conflicts, cross-story dependencies that break independence --- **Tasks Status**: ✅ READY FOR EXECUTION **Suggested MVP**: Phases 1-3 (Setup + Foundational + US1 Authentication) **Full Feature**: All phases (estimated 6 sprints with incremental delivery)