SSO MCP Server

# Tasks: MCP SSO Checklist Server **Input**: Design documents from `specs/001-mcp-sso-checklist/` **Prerequisites**: design.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ **Tests**: Unit and integration tests are defined in design.md test strategy. Tests are included based on the test-first development requirement in ground-rules. **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) - Include exact file paths in descriptions ## Path Conventions - **Single project**: `src/sso_mcp_server/`, `tests/` at repository root (per design.md structure) --- ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Project initialization and basic structure per design.md - [x] T001 Create project structure: `src/sso_mcp_server/`, `tests/unit/`, `tests/integration/`, `checklists/` - [x] T002 Initialize Python project with pyproject.toml and uv dependencies (mcp, msal, msal-extensions, python-frontmatter, python-dotenv, structlog) - [x] T003 [P] Configure ruff linting and formatting in pyproject.toml - [x] T004 [P] Configure pytest and pytest-asyncio in pyproject.toml - [x] T005 [P] Create .env.example with AZURE_CLIENT_ID, AZURE_TENANT_ID, CHECKLIST_DIR, MCP_PORT, LOG_LEVEL - [x] T006 [P] Create sample checklist files in `checklists/` directory (coding.md, architecture.md, detailed-design.md with YAML frontmatter) --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented **⚠️ CRITICAL**: No user story work can begin until this phase is complete - [x] T007 Implement configuration settings module in `src/sso_mcp_server/config/settings.py` (load AZURE_CLIENT_ID, AZURE_TENANT_ID, CHECKLIST_DIR, MCP_PORT, LOG_LEVEL from environment) - [x] T008 [P] Create `src/sso_mcp_server/config/__init__.py` with Settings export - [x] T009 Implement structured logging setup using structlog in `src/sso_mcp_server/__init__.py` - [x] T010 [P] Create shared test fixtures in `tests/conftest.py` (mock settings, temp directories, sample checklist files) - [x] T011 Create entry point in `src/sso_mcp_server/__main__.py` (parse args, initialize server) - [x] T012 Implement MCP Server Core with FastMCP in `src/sso_mcp_server/server.py` (HTTP Streamable transport with SSE streaming per FR-006b, stateless_http=True, json_response=True) **Checkpoint**: Foundation ready - user story implementation can now begin in parallel --- ## Phase 3: User Story 1 - Authenticate and Connect to MCP Server (Priority: P1) 🎯 MVP **Goal**: Developer authenticates with Azure Entra ID credentials when starting the MCP server for secure access to checklists **Independent Test**: Start server and complete SSO login flow - delivers secure access to the MCP server ### Tests for User Story 1 > **NOTE: Write these tests FIRST, ensure they FAIL before implementation** - [x] T013 [P] [US1] Unit test for Token Store in `tests/unit/test_token_store.py` (save, load, clear tokens, encryption) - [x] T014 [P] [US1] Unit test for Auth Manager in `tests/unit/test_auth_manager.py` (ensure_authenticated, get_access_token, is_authenticated) - [x] T015 [P] [US1] Integration test for auth flow in `tests/integration/test_auth_flow.py` (mock MSAL, test browser auth trigger, token persistence) ### Implementation for User Story 1 - [x] T016 [P] [US1] Implement Token Store using msal-extensions in `src/sso_mcp_server/auth/token_store.py` (build_encrypted_persistence, PersistedTokenCache, save/load/clear tokens at ~/.sso-mcp-server/token_cache.bin) - [x] T017 [P] [US1] Implement Browser Auth flow in `src/sso_mcp_server/auth/browser.py` (MSAL PublicClientApplication, acquire_token_interactive with PKCE) - [x] T018 [US1] Implement Auth Manager in `src/sso_mcp_server/auth/manager.py` (orchestrate auth flow: check tokens, refresh or prompt login, ensure_authenticated, get_access_token) - [x] T019 [US1] Implement Auth Middleware in `src/sso_mcp_server/auth/middleware.py` (check auth state before tool calls, trigger auth if needed) - [x] T020 [P] [US1] Create `src/sso_mcp_server/auth/__init__.py` with AuthManager, TokenStore exports - [x] T021 [US1] Integrate Auth Manager with MCP Server startup in `src/sso_mcp_server/server.py` (attempt silent re-auth on restart, prompt only if refresh fails per FR-004) - [x] T022 [US1] Add structured logging for auth events in auth module (success, failure, token refresh per OB-002) - [x] T023 [US1] Handle auth error cases with actionable error messages (invalid credentials, network issues, expired tokens per FR-004, US-002) **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently - server starts, authenticates via Azure SSO, and maintains session --- ## Phase 4: User Story 2 - Retrieve Development Checklists (Priority: P2) **Goal**: Developer requests specific development checklists through the MCP server to ensure work follows quality standards **Independent Test**: Call checklist retrieval tool with different checklist names - delivers relevant checklist content to the AI assistant ### Tests for User Story 2 > **NOTE: Write these tests FIRST, ensure they FAIL before implementation** - [x] T024 [P] [US2] Unit test for Frontmatter Parser in `tests/unit/test_frontmatter_parser.py` (parse YAML frontmatter, extract name/description, return content) - [x] T025 [P] [US2] Unit test for File Discovery in `tests/unit/test_file_discovery.py` (discover .md files, handle missing directory, handle empty directory) - [x] T026 [P] [US2] Unit test for Checklist Service in `tests/unit/test_checklist_service.py` (get_checklist by name, handle not found, handle malformed files) - [x] T027 [US2] Integration test for get_checklist MCP tool in `tests/integration/test_mcp_tools.py` (authenticated call, returns content, error for not found) ### Implementation for User Story 2 - [x] T028 [P] [US2] Implement Frontmatter Parser in `src/sso_mcp_server/checklists/parser.py` (python-frontmatter, extract name/description from YAML, return content body) - [x] T029 [P] [US2] Implement File Discovery in `src/sso_mcp_server/checklists/discovery.py` (glob pattern for *.md in CHECKLIST_DIR, dynamic discovery without caching) - [x] T030 [US2] Implement Checklist Service in `src/sso_mcp_server/checklists/service.py` (get_checklist by name, use parser and discovery, format response) - [x] T031 [P] [US2] Create `src/sso_mcp_server/checklists/__init__.py` with ChecklistService export - [x] T032 [US2] Implement get_checklist MCP tool in `src/sso_mcp_server/tools/get_checklist.py` (FastMCP @mcp.tool decorator, input schema per contracts/mcp-tools.json, call auth middleware, call ChecklistService) - [x] T033 [P] [US2] Create `src/sso_mcp_server/tools/__init__.py` with tool registration - [x] T034 [US2] Register get_checklist tool with MCP Server in `src/sso_mcp_server/server.py` - [x] T035 [US2] Add error handling for checklist not found with available checklists list (per FR-017, mcp-tools.json CHECKLIST_NOT_FOUND error) - [x] T036 [US2] Add structured logging for checklist retrieval operations (per OB-003) **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently - authenticated users can retrieve specific checklists --- ## Phase 5: User Story 3 - List Available Checklists (Priority: P3) **Goal**: Developer sees all available checklists to know what quality standards can be applied to work **Independent Test**: Call list-checklists tool - delivers complete inventory of available checklists with metadata ### Tests for User Story 3 > **NOTE: Write these tests FIRST, ensure they FAIL before implementation** - [x] T037 [P] [US3] Unit test for list_checklists in ChecklistService in `tests/unit/test_checklist_service.py` (return all metadata, handle empty directory) - [x] T038 [US3] Integration test for list_checklists MCP tool in `tests/integration/test_mcp_tools.py` (authenticated call, returns all checklists, dynamic discovery) ### Implementation for User Story 3 - [x] T039 [US3] Implement list_checklists in Checklist Service in `src/sso_mcp_server/checklists/service.py` (return all checklist metadata without full content, use discovery and parser) - [x] T040 [US3] Implement list_checklists MCP tool in `src/sso_mcp_server/tools/list_checklists.py` (FastMCP @mcp.tool decorator, output schema per contracts/mcp-tools.json, call auth middleware) - [x] T041 [US3] Register list_checklists tool with MCP Server in `src/sso_mcp_server/server.py` - [x] T042 [US3] Add structured logging for list operation (per OB-003) **Checkpoint**: All core user stories (US1, US2, US3) should now be independently functional --- ## Phase 6: User Story 4 - Configure MCP Server in Development Environment (Priority: P4) **Goal**: Developer configures the MCP server in VSCode or Claude Code using JSON configuration file for AI assistant connection **Independent Test**: Create configuration file and verify AI assistant connects successfully - delivers working integration ### Implementation for User Story 4 - [x] T043 [P] [US4] Create VSCode MCP configuration example in `docs/examples/vscode-mcp.json` (per architecture.md §7.2.1) - [x] T044 [P] [US4] Create Claude Code configuration example in `docs/examples/claude-config.json` (per architecture.md §7.2.2) - [x] T045 [US4] Update quickstart.md with configuration steps and troubleshooting (validate against actual server behavior) - [x] T046 [US4] Add startup validation with clear error messages for invalid configuration (missing env vars, invalid port per FR-014) **Checkpoint**: All user stories should now be complete with documentation --- ## Phase 7: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories - [x] T047 [P] Add pre-commit hooks configuration (.pre-commit-config.yaml with ruff, bandit) - [x] T048 [P] Create README.md with project overview, prerequisites, installation, and usage - [x] T049 [P] Add bandit security scanning configuration in pyproject.toml - [x] T050 Run full test suite and ensure >80% coverage for auth and MCP modules - [x] T051 Run quickstart.md validation end-to-end (complete flow from install to tool call) - [x] T052 Code cleanup and linting pass (ruff check, ruff format) - [x] T053 [US1] Integration test for 8-hour session maintenance in `tests/integration/test_auth_flow.py` (mock time progression per SC-003, verify no re-auth prompts, validate proactive token refresh) --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies - can start immediately - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories - **User Stories (Phase 3-6)**: All depend on Foundational phase completion - User stories can proceed in parallel (if staffed) - Or sequentially in priority order (P1 → P2 → P3 → P4) - **Polish (Phase 7)**: Depends on all desired user stories being complete ### User Story Dependencies - **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories - **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Auth middleware from US1 required, but US2 tests can mock auth - **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Builds on US2 Checklist Service, can be developed in parallel - **User Story 4 (P4)**: Can start after Foundational (Phase 2) - Documentation only, no code dependencies ### Within Each User Story - Tests MUST be written and FAIL before implementation - Infrastructure before services - Services before tools - Core implementation before integration - Story complete before moving to next priority ### Parallel Opportunities - All Setup tasks marked [P] can run in parallel - All Foundational tasks marked [P] can run in parallel (within Phase 2) - Once Foundational phase completes, all user stories can start in parallel (if team capacity allows) - All tests for a user story marked [P] can run in parallel - Models/components within a story marked [P] can run in parallel - Different user stories can be worked on in parallel by different team members --- ## Parallel Example: User Story 2 ```bash # Launch all tests for User Story 2 together: Task: "Unit test for Frontmatter Parser in tests/unit/test_frontmatter_parser.py" Task: "Unit test for File Discovery in tests/unit/test_file_discovery.py" Task: "Unit test for Checklist Service in tests/unit/test_checklist_service.py" # Launch parallel components for User Story 2: Task: "Implement Frontmatter Parser in src/sso_mcp_server/checklists/parser.py" Task: "Implement File Discovery in src/sso_mcp_server/checklists/discovery.py" ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup 2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) 3. Complete Phase 3: User Story 1 4. **STOP and VALIDATE**: Test User Story 1 independently (server starts, authenticates, maintains session) 5. Deploy/demo if ready ### Incremental Delivery 1. Complete Setup + Foundational → Foundation ready 2. Add User Story 1 → Test independently → Deploy/Demo (MVP: Authentication works!) 3. Add User Story 2 → Test independently → Deploy/Demo (Can retrieve checklists!) 4. Add User Story 3 → Test independently → Deploy/Demo (Can list checklists!) 5. Add User Story 4 → Test independently → Deploy/Demo (Full documentation!) 6. Each story adds value without breaking previous stories ### Parallel Team Strategy With multiple developers: 1. Team completes Setup + Foundational together 2. Once Foundational is done: - Developer A: User Story 1 (Authentication) - Developer B: User Story 2 (Get Checklist) - can mock auth - Developer C: User Story 3 (List Checklists) - can mock auth - Developer D: User Story 4 (Documentation) 3. Stories complete and integrate independently --- ## Architecture Alignment Notes This task list aligns with `docs/architecture.md`: - **ADR-001**: HTTP Streamable transport with FastMCP (T012, T034, T041) - **ADR-002**: OAuth 2.0 with PKCE via MSAL (T016, T017, T018) - **ADR-003**: Local file system storage with YAML frontmatter (T028, T029) - **ADR-004**: MSAL for Azure authentication (T016, T017, T018) - **ADR-005**: Secure token persistence with msal-extensions (T016) - **Component View §5**: Components map to source file structure exactly - **Deployment §7**: Environment variables for configuration (T005, T007) --- ## Summary | Metric | Count | |--------|-------| | **Total Tasks** | 53 | | **Phase 1 (Setup)** | 6 | | **Phase 2 (Foundational)** | 6 | | **Phase 3 (US1 - Auth)** | 11 | | **Phase 4 (US2 - Get Checklist)** | 13 | | **Phase 5 (US3 - List Checklists)** | 6 | | **Phase 6 (US4 - Configuration)** | 4 | | **Phase 7 (Polish)** | 7 | | **Parallelizable Tasks** | 29 | **Suggested MVP Scope**: Phases 1-3 (User Story 1 only) - 23 tasks for working authentication **Independent Test Criteria**: - US1: Server starts, opens browser for SSO, maintains authenticated session for 8+ hours - US2: Authenticated tool call returns full checklist content by name - US3: Authenticated tool call returns all checklist metadata - US4: Configuration files enable AI assistant connection --- ## Notes - [P] tasks = different files, no dependencies - [Story] label maps task to specific user story for traceability - Each user story should be independently completable and testable - Verify tests fail before implementing - Commit after each task or logical group - Stop at any checkpoint to validate story independently - Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence