SSO MCP Server

# Implementation Plan: MCP SSO Checklist Server **Branch**: `001-mcp-sso-checklist` | **Date**: 2025-12-11 | **Spec**: [spec.md](./spec.md) **Input**: Feature specification from `specs/001-mcp-sso-checklist/spec.md` ## Summary Build a local MCP server providing software development checklists to AI coding assistants (GitHub Copilot, Claude Code) with Azure Entra ID SSO authentication. The server exposes two MCP tools (`get_checklist`, `list_checklists`) via HTTP Streamable transport, reads checklist content from local markdown files with YAML frontmatter, and persists authentication tokens using MSAL's encrypted cache. ## Technical Context **Language/Version**: Python 3.11+ **Primary Dependencies**: mcp ^1.23.3, msal ^1.30.0, msal-extensions ^1.2.0, python-frontmatter ^1.1.0, python-dotenv ^1.0.0, structlog ^24.0.0 **Storage**: Local file system (checklists as .md files, tokens in encrypted cache at ~/.sso-mcp-server/token_cache.bin) **Testing**: pytest ^8.0.0, pytest-asyncio ^0.23.0, pytest-cov **Target Platform**: macOS, Linux, Windows (developer workstations) **Project Type**: Single CLI application **Performance Goals**: Server ready in <5s, checklist retrieval in <2s, list in <1s (per spec) **Constraints**: Local-only operation, single-user, read-only checklist access **Scale/Scope**: Single developer per instance, unlimited checklist files ## Ground-rules Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* | Gate | Requirement | Status | Evidence | |------|-------------|--------|----------| | Clean Code | Descriptive names, <30 line functions | PASS | Standards documented in docs/standards.md | | Test-First | Unit tests for critical paths | PASS | Test structure defined, >80% coverage target | | Code Review | PR review required | PASS | Ground-rules mandate peer review | | Documentation | Public APIs documented | PASS | Google-style docstrings required per standards | | Continuous Improvement | Tech debt tracking | PASS | Architecture.md §10 tracks debt | **Pre-commit Quality Gates** (per ground-rules.md): - [ ] Linting passes (ruff) - [ ] No secrets in code (pre-commit hook) - [ ] All CI checks pass before merge - [ ] Security scan clean (bandit) ## Project Structure ### Documentation (this feature) ```text specs/001-mcp-sso-checklist/ ├── design.md # This file ├── research.md # Phase 0 output - technology research ├── data-model.md # Phase 1 output - entity definitions ├── quickstart.md # Phase 1 output - setup guide ├── contracts/ # Phase 1 output - MCP tool schemas │ └── mcp-tools.json # Tool definitions └── tasks.md # Phase 2 output (created by /rainbow.taskify) ``` ### Source Code (repository root) ```text src/ └── sso_mcp_server/ ├── __init__.py # Package init, version, logging setup ├── __main__.py # CLI entry point ├── server.py # MCP Server Core (FastMCP, HTTP Streamable) ├── config/ │ ├── __init__.py │ └── settings.py # Environment configuration (python-dotenv) ├── auth/ │ ├── __init__.py # Auth module exports │ ├── manager.py # Auth Manager (orchestration + token refresh) │ ├── browser.py # Browser Auth (OAuth PKCE flow) │ ├── token_store.py # Token persistence (msal-extensions) │ └── middleware.py # Auth middleware for tool calls ├── checklists/ │ ├── __init__.py # Checklist module exports │ ├── service.py # Checklist business logic │ ├── discovery.py # File discovery (glob) │ └── parser.py # Frontmatter parser (python-frontmatter) └── tools/ ├── __init__.py # Tool registration ├── get_checklist.py # get_checklist MCP tool └── list_checklists.py # list_checklists MCP tool checklists/ # Default checklist directory ├── coding.md ├── architecture.md └── detailed-design.md tests/ ├── conftest.py # Shared fixtures ├── unit/ │ ├── test_auth_manager.py │ ├── test_token_store.py │ ├── test_checklist_service.py │ ├── test_frontmatter_parser.py │ └── test_file_discovery.py └── integration/ ├── test_auth_flow.py └── test_mcp_tools.py ``` **Structure Decision**: Single CLI application per architecture.md ADR-001. Source code in `src/sso_mcp_server/` following Python packaging conventions. Tests mirror source structure. ## Complexity Tracking No violations to justify. Design adheres to ground-rules: - Single project (not multi-project) - Direct file access (no repository pattern needed) - Simple module structure (no over-engineering) --- ## Implementation Phases ### Phase 1: Project Setup & Configuration **Tasks**: 1. Initialize Python project with uv (`pyproject.toml`) 2. Configure dependencies per research.md 3. Create `src/sso_mcp_server/config/settings.py` for environment loading 4. Create `.env.example` template 5. Setup ruff, bandit, pre-commit hooks **Dependencies**: None **Output**: Buildable project skeleton, `uv run sso-mcp-server --help` works ### Phase 2: Authentication Module **Tasks**: 1. Implement `auth/token_store.py` - MSAL cache with msal-extensions 2. Implement `auth/browser.py` - OAuth PKCE flow via MSAL 3. Implement `auth/manager.py` - Auth orchestration and token refresh 4. Implement `auth/middleware.py` - Auth check decorator for tools 5. Write unit tests for each component **Dependencies**: Phase 1 **Key Patterns**: - Silent acquisition first, fallback to interactive (per MSAL best practices) - Refresh when < 5 minutes remaining (per spec clarification) - Encrypted token cache at `~/.sso-mcp-server/token_cache.bin` **Output**: Standalone authentication that can login via browser ### Phase 3: Checklist Module **Tasks**: 1. Implement `checklists/parser.py` - YAML frontmatter parsing 2. Implement `checklists/discovery.py` - File discovery with glob 3. Implement `checklists/service.py` - Business logic (get, list) 4. Write unit tests for each component **Dependencies**: Phase 1 **Key Patterns**: - Use `python-frontmatter` for parsing - Handle BOM with `utf-8-sig` encoding - Cache metadata with mtime validation **Output**: Checklist service that can read/list local markdown files ### Phase 4: MCP Server & Tools **Tasks**: 1. Implement `server.py` - FastMCP server with HTTP Streamable 2. Implement `tools/get_checklist.py` - get_checklist tool 3. Implement `tools/list_checklists.py` - list_checklists tool 4. Wire auth middleware to tools 5. Implement `__main__.py` - CLI entry point 6. Write integration tests for MCP tools **Dependencies**: Phase 2, Phase 3 **Key Patterns**: - `@mcp.tool()` decorator for tool registration - Auth check before tool execution - Error responses per contracts/mcp-tools.json **Output**: Fully functional MCP server accessible via HTTP ### Phase 5: Testing & Documentation **Tasks**: 1. Complete unit test coverage (>80%) 2. Integration tests with mocked Azure 3. 8-hour session test with mocked time 4. Update README.md with quickstart 5. Validate against success criteria **Dependencies**: Phase 4 **Output**: Production-ready server with documentation --- ## Key Design Decisions | Decision | Choice | Rationale | ADR | |----------|--------|-----------|-----| | MCP Transport | HTTP Streamable | Better debugging, URL-based config | ADR-001 | | Auth Library | MSAL | Official Microsoft, auto PKCE | ADR-004 | | Token Storage | msal-extensions | Encrypted, cross-platform | ADR-005 | | Checklist Format | MD + YAML frontmatter | Human-readable, version-controllable | ADR-003 | | Server Port | 8080 (configurable) | Standard HTTP alt port | Spec clarification | --- ## Risk Mitigation | Risk | Mitigation | |------|------------| | Azure auth unavailable | Clear error message, document retry | | Token refresh fails | Graceful fallback to re-authentication | | Port conflict | Fail fast with clear error, suggest MCP_PORT | | Malformed checklist | Return readable error, continue for others | --- ## Success Criteria Mapping | Criteria | Implementation | Validation | |----------|----------------|------------| | SC-001: Auth <30s | Lazy auth on first tool call | Unit test with timing | | SC-002: Retrieval <2s | Direct file read + cache | Integration test | | SC-003: 8-hour session | Proactive token refresh | Mocked time test | | SC-004: 5-min setup | quickstart.md guide | Manual verification | | SC-005: List all checklists | File discovery | Integration test | | SC-006: Actionable errors | Error messages per contracts | Unit tests | | SC-007: Server start <5s | Minimal startup, lazy auth | Timing test | --- ## Related Documents - **Specification**: [spec.md](./spec.md) - **Research**: [research.md](./research.md) - **Data Model**: [data-model.md](./data-model.md) - **MCP Contracts**: [contracts/mcp-tools.json](./contracts/mcp-tools.json) - **Quickstart**: [quickstart.md](./quickstart.md) - **Architecture**: [docs/architecture.md](../../docs/architecture.md) - **Standards**: [docs/standards.md](../../docs/standards.md) - **Ground Rules**: [memory/ground-rules.md](../../memory/ground-rules.md)