SSO MCP Server

# Data Model: MCP SSO Checklist Server **Date**: 2025-12-11 **Feature**: 001-mcp-sso-checklist ## Entity Overview ```mermaid erDiagram Checklist ||--o{ ChecklistMetadata : has Session ||--o{ TokenData : stores Configuration ||--|| Session : configures Checklist { string name PK string description string content string file_path datetime modified_at } ChecklistMetadata { string name PK string description } Session { string session_id PK datetime created_at datetime expires_at boolean is_authenticated } TokenData { string access_token string refresh_token datetime expires_at string user_id string tenant_id } Configuration { int port string checklist_dir string azure_client_id string azure_tenant_id string token_cache_path } ``` --- ## Entity Definitions ### 1. Checklist A development quality checklist stored as a markdown file with YAML frontmatter. | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Unique identifier from frontmatter (PK) | | description | string | No | Brief description from frontmatter | | content | string | Yes | Markdown content (excluding frontmatter) | | file_path | Path | Yes | Absolute path to source file | | modified_at | datetime | Yes | File modification timestamp | **Validation Rules**: - `name` must be unique across all checklist files - `name` derived from frontmatter `name` field or filename stem - `content` must be valid UTF-8 encoded text - File must have `.md` extension **State Transitions**: None (read-only entity) **Source**: Local file system (spec FR-009, FR-018) ### 2. ChecklistMetadata Lightweight representation for list operations (avoids loading full content). | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Checklist identifier (PK) | | description | string | No | Brief description for discovery | **Usage**: Returned by `list_checklists` tool for efficient discovery. ### 3. Session Authenticated user session for the MCP server. | Field | Type | Required | Description | |-------|------|----------|-------------| | session_id | string | Yes | Unique session identifier (UUID) | | created_at | datetime | Yes | Session start time | | expires_at | datetime | Yes | Session expiration time | | is_authenticated | boolean | Yes | Current authentication state | **Validation Rules**: - `session_id` must be cryptographically secure (UUID4) - Session expires after 8+ hours (spec assumption) **State Transitions**: ``` [Not Authenticated] --authenticate()--> [Authenticated] [Authenticated] --token_expired()--> [Token Refresh Required] [Token Refresh Required] --refresh_success()--> [Authenticated] [Token Refresh Required] --refresh_failed()--> [Not Authenticated] [Authenticated] --logout()--> [Not Authenticated] ``` ### 4. TokenData OAuth 2.0 tokens from Azure Entra ID authentication. | Field | Type | Required | Description | |-------|------|----------|-------------| | access_token | string | Yes | JWT access token for API calls | | refresh_token | string | Yes | Token for silent re-authentication | | expires_at | datetime | Yes | Access token expiration time | | user_id | string | Yes | Azure AD user principal (UPN or OID) | | tenant_id | string | Yes | Azure tenant identifier | **Validation Rules**: - Tokens must be encrypted at rest (msal-extensions) - Access token typically expires in 1 hour - Refresh token typically expires in 24 hours to 90 days **Storage**: `~/.sso-mcp-server/token_cache.bin` (encrypted) ### 5. Configuration Server configuration settings from environment or config file. | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | port | int | No | 8080 | HTTP server port | | checklist_dir | string | Yes | - | Path to checklist files directory | | azure_client_id | string | Yes | - | Azure App Registration client ID | | azure_tenant_id | string | Yes | - | Azure tenant ID | | token_cache_path | string | No | ~/.sso-mcp-server/token_cache.bin | Token storage path | | log_level | string | No | INFO | Logging level | **Validation Rules**: - `port` must be 1024-65535 (non-privileged ports) - `checklist_dir` must exist and be readable - `azure_client_id` must be valid GUID format - `azure_tenant_id` must be valid GUID format **Source**: Environment variables (spec FR-011, architecture §7.2.3) --- ## Data Flow ### Checklist Retrieval Flow ```mermaid sequenceDiagram participant Client as AI Client participant Server as MCP Server participant Auth as Auth Module participant FS as File System participant Cache as Memory Cache Client->>Server: get_checklist("coding") Server->>Auth: check_auth() Auth-->>Server: authenticated Server->>Cache: get("coding") alt Cache hit (mtime unchanged) Cache-->>Server: Checklist else Cache miss or stale Server->>FS: read_file("coding.md") FS-->>Server: file_content Server->>Server: parse_frontmatter() Server->>Cache: set("coding", Checklist) end Server-->>Client: ChecklistContent ``` ### Token Lifecycle ```mermaid stateDiagram-v2 [*] --> NoTokens: Server Start NoTokens --> BrowserAuth: No cached tokens NoTokens --> ValidTokens: Cached tokens found BrowserAuth --> ValidTokens: Auth success BrowserAuth --> NoTokens: Auth failed/cancelled ValidTokens --> ValidTokens: Token refresh (auto) ValidTokens --> RefreshRequired: Token expired ValidTokens --> NoTokens: Logout RefreshRequired --> ValidTokens: Refresh success RefreshRequired --> BrowserAuth: Refresh failed ValidTokens --> [*]: Server Shutdown ``` --- ## File System Structure ### Checklist Directory ```text checklists/ ├── coding.md # Coding standards checklist ├── architecture.md # Architecture review checklist ├── detailed-design.md # Detailed design checklist └── [custom-name].md # Additional custom checklists ``` ### Checklist File Format ```yaml --- name: Coding Standards Checklist description: Quality checklist for code reviews and development --- # Coding Standards ## Naming Conventions - [ ] Variables use descriptive names - [ ] Functions follow verb_noun pattern - [ ] Classes use PascalCase ## Code Structure - [ ] Single responsibility per function - [ ] Maximum 30 lines per function - [ ] No code duplication (DRY) ... ``` ### Token Cache Location ```text ~/.sso-mcp-server/ └── token_cache.bin # Encrypted token cache (msal-extensions) ``` --- ## Validation Summary | Entity | Constraint | Error Response | |--------|------------|----------------| | Checklist | Name must be unique | 409 Conflict | | Checklist | File must exist | 404 Not Found | | Checklist | Valid UTF-8 encoding | 422 Unprocessable | | Session | Must be authenticated | 401 Unauthorized | | TokenData | Not expired | Trigger refresh | | Configuration | Port in valid range | Startup error | | Configuration | Checklist dir exists | Startup error | | Configuration | Azure credentials set | Startup error | --- ## Architecture Alignment - **ADR-003**: Checklist storage as local markdown files with YAML frontmatter - **ADR-005**: Token persistence in encrypted local cache - **Architecture §4**: Entities map to Container/Component responsibilities - **Architecture §5**: Components implement entity operations