SSO MCP Server

# Feature Specification: MCP SSO Checklist Server **Feature Branch**: `001-mcp-sso-checklist` **Created**: 2025-12-11 **Status**: Draft **Input**: User description: "Develop an MCP server providing software development checklists with Azure Entra ID SSO authentication, compatible with VSCode GitHub Copilot and Claude Code" ## Clarifications ### Session 2025-12-11 - Q: Should authentication tokens persist across server restarts? → A: Yes, persist tokens securely; attempt silent re-auth on restart, prompt only if refresh fails. - Q: How should checklist metadata (name, description) be provided? → A: YAML frontmatter in each markdown file. - Q: Which MCP transport protocol should be used? → A: HTTP Streamable as the default protocol (instead of stdio) for better network flexibility and client compatibility. - Q: What should be the default HTTP port for the MCP server? → A: Port 8080 (standard HTTP alternative port). - Q: How should the server handle port conflicts? → A: Fail with clear error message indicating port is in use. - Q: How should multiple server instances be detected? → A: Check if configured port is in use; fail with error suggesting alternative port (no lock file or multiplexing). - Q: What does "30 seconds authentication flow" measure (SC-001)? → A: Server-side processing only; excludes browser interaction and Azure latency. - Q: When should token refresh occur ("about to expire" threshold)? → A: Refresh when less than 5 minutes remaining on token lifetime. - Q: Should token refresh be a separate component or in Auth Manager? → A: Refresh logic in Auth Manager (manager.py); leverage MSAL's built-in refresh, no separate refresher.py. - Q: How should 8-hour session (SC-003) be validated? → A: Automated integration test with mocked time progression (simulate 8 hours). ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Authenticate and Connect to MCP Server (Priority: P1) As a developer, I want to authenticate with my corporate Azure Entra ID credentials when starting the MCP server so that I can securely access development checklists through my AI coding assistant without managing separate credentials. **Why this priority**: Authentication is the foundation that enables all other functionality. Without secure authentication, the server cannot be used at all. **Independent Test**: Can be fully tested by starting the server and completing the SSO login flow - delivers secure access to the MCP server. **Acceptance Scenarios**: 1. **Given** the MCP server is started for the first time (no stored tokens), **When** the server initializes, **Then** a browser window opens automatically displaying the Azure login page. 2. **Given** a user enters valid Azure Entra ID credentials, **When** authentication succeeds, **Then** the browser shows a success message and the user is redirected back to their development environment. 3. **Given** authentication is complete, **When** the user's AI assistant makes subsequent tool calls, **Then** no re-authentication is required for the duration of the session. 4. **Given** a user enters invalid credentials, **When** authentication fails, **Then** an appropriate error message is displayed and the user can retry. 5. **Given** the server has valid persisted tokens from a previous session, **When** the server restarts, **Then** it silently re-authenticates without opening a browser window. 6. **Given** the server has expired/invalid persisted tokens, **When** the server restarts, **Then** a browser window opens for fresh authentication. --- ### User Story 2 - Retrieve Development Checklists (Priority: P2) As a developer using an AI coding assistant, I want to request specific development checklists through the MCP server so that I can ensure my work follows established quality standards. **Why this priority**: This is the core value proposition - providing checklists is the primary function of the server. Depends on authentication being complete. **Independent Test**: Can be fully tested by calling the checklist retrieval tool with different checklist names - delivers relevant checklist content to the AI assistant. **Acceptance Scenarios**: 1. **Given** the user is authenticated, **When** the AI assistant requests the "coding" checklist, **Then** the server returns the complete coding checklist content. 2. **Given** the user is authenticated, **When** the AI assistant requests the "architecture" checklist, **Then** the server returns the complete architecture checklist content. 3. **Given** the user is authenticated, **When** the AI assistant requests the "detailed-design" checklist, **Then** the server returns the complete detailed design checklist content. 4. **Given** the user requests a checklist that does not exist, **When** the server processes the request, **Then** a clear error message is returned listing available checklists. --- ### User Story 3 - List Available Checklists (Priority: P3) As a developer, I want to see all available checklists so that I know what quality standards I can apply to my work. **Why this priority**: Discovery feature that enhances usability but not essential for basic operation. **Independent Test**: Can be fully tested by calling the list-checklists tool - delivers a complete inventory of available checklists. **Acceptance Scenarios**: 1. **Given** the user is authenticated, **When** the AI assistant requests the list of available checklists, **Then** the server returns all checklist names with brief descriptions. 2. **Given** new checklist files are added to the server, **When** the list is requested, **Then** the new checklists appear in the list without server restart. --- ### User Story 4 - Configure MCP Server in Development Environment (Priority: P4) As a developer, I want to configure the MCP server in my VSCode or Claude Code environment using a JSON configuration file so that my AI assistant can connect to and use the server. **Why this priority**: Configuration is a one-time setup task that enables ongoing usage. Less critical than runtime functionality. **Independent Test**: Can be fully tested by creating a configuration file and verifying the AI assistant connects successfully - delivers working integration. **Acceptance Scenarios**: 1. **Given** a properly formatted JSON configuration file, **When** VSCode with GitHub Copilot loads, **Then** the MCP server is registered and available. 2. **Given** a properly formatted JSON configuration file, **When** Claude Code loads, **Then** the MCP server is registered and available. 3. **Given** an invalid configuration file, **When** the development environment loads, **Then** a clear error message indicates what is wrong with the configuration. --- ### Edge Cases - What happens when the authentication session expires during a long coding session? - System should prompt for re-authentication and resume operation without data loss. - How does the system handle network interruptions during authentication? - System should display a clear error and allow retry without restarting the server. - What happens when checklist markdown files are malformed? - System should return readable content or indicate which files have issues. - How does the system behave when Azure Entra ID service is unavailable? - System should provide a clear error message indicating the authentication service is temporarily unavailable. - What happens when multiple instances of the server are started? - System checks if configured port is in use; fails with clear error message suggesting alternative port via MCP_PORT environment variable. No lock file or multiplexing. - What happens when the configured port is already in use? - System should fail with a clear error message indicating the port is in use and suggest specifying an alternative port via configuration. ## Requirements *(mandatory)* ### Functional Requirements **Authentication & Security** - **FR-001**: System MUST open a browser window for Azure Entra ID authentication when starting a new session. - **FR-002**: System MUST support OAuth 2.0 Authorization Code flow with PKCE for secure authentication. - **FR-003**: System MUST maintain authentication state for the duration of the session without requiring re-authentication for each tool call. - **FR-004**: System MUST securely persist authentication tokens locally and attempt silent re-authentication on server restart; prompt for login only if token refresh fails. - **FR-005**: System MUST handle authentication token refresh automatically when tokens have less than 5 minutes remaining before expiration. **MCP Server Operations** - **FR-006**: System MUST implement the Model Context Protocol specification for communication with AI assistants. - **FR-006a**: System MUST use HTTP Streamable transport as the default MCP protocol, listening on a configurable local port (default: 8080). - **FR-006b**: System MUST support Server-Sent Events (SSE) for streaming responses as required by HTTP Streamable transport. - **FR-007**: System MUST expose tools for retrieving individual checklists by name. - **FR-008**: System MUST expose a tool for listing all available checklists. - **FR-009**: System MUST read checklist content from markdown files stored in a configurable directory. - **FR-010**: System MUST support dynamic checklist discovery without server restart. **Configuration & Integration** - **FR-011**: System MUST be configurable via JSON configuration file for VSCode integration. - **FR-012**: System MUST be compatible with GitHub Copilot's MCP server registration. - **FR-013**: System MUST be compatible with Claude Code's MCP server registration. - **FR-014**: System MUST provide clear error messages when configuration is invalid. **Checklist Management** - **FR-015**: System MUST support multiple checklist types (coding, architecture, detailed-design, and extensible for additional types). - **FR-016**: System MUST return checklist content in a format consumable by AI assistants. - **FR-017**: System MUST provide descriptive error messages when requested checklists are not found. - **FR-018**: System MUST parse YAML frontmatter from checklist markdown files to extract name and description metadata. ### Key Entities - **Checklist**: A quality standard document containing items to verify during software development. Has a unique name, description (provided via YAML frontmatter), and markdown content. Types include: coding, architecture, detailed-design, and potentially others. - **Session**: An authenticated working period. Has an authentication state, creation time, expiration time, and associated user identity from Azure Entra ID. - **Tool**: An MCP-exposed capability. Includes get-checklist (retrieves specific checklist), list-checklists (returns available checklists). - **Configuration**: Server settings for integration. Includes server URL (for HTTP Streamable transport), port number, Azure App Registration details, and checklist directory location. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Server-side authentication processing completes in under 30 seconds from server start to ready state (excludes browser interaction time and Azure service latency). - **SC-002**: Checklist retrieval requests return complete content in under 2 seconds. - **SC-003**: 100% of checklist tool calls succeed without re-authentication during a continuous 8-hour working session. Validated via automated integration test with mocked time progression. - **SC-004**: Users can configure and connect the server to their AI assistant within 5 minutes using documentation. - **SC-005**: System correctly returns all available checklists when the list tool is called. - **SC-006**: Authentication errors provide actionable guidance in 100% of failure cases. - **SC-007**: Server starts and becomes ready for authentication within 5 seconds. ## Assumptions - Users have valid Azure Entra ID accounts in the organization's tenant. - An Azure App Registration will be created/provided for this application. - Users have VSCode with GitHub Copilot extension or Claude Code installed. - Checklist files are stored as standard markdown (.md) files. - Network connectivity to Azure authentication services is available. - The server runs locally on the developer's machine (not as a remote service). - Session duration aligns with typical work session (8+ hours) before re-authentication is needed. ## Out of Scope - Checklist editing or creation through the MCP server (read-only access). - User management or role-based access control beyond Azure Entra ID authentication. - Multi-tenant support (single organization tenant assumed). - Offline operation without Azure authentication. - Mobile or web-based interfaces (CLI/development environment only). - Synchronization of checklists across multiple servers or users.