SSO MCP Server

# Feature Specification: Project Development Process Query **Feature Branch**: `003-process-query` **Created**: 2025-12-13 **Status**: Draft **Input**: User description: "Add specs to support querying about project development processes. These processes are stored in markdown files. Use the same authentication as previous functions" ## Clarifications ### Session 2025-12-13 - Q: Should search results be limited or paginated? → A: Return all matches up to 50 results maximum. ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Query Development Processes (Priority: P1) As a developer using an AI coding assistant, I want to query project development processes through the MCP server so that I can understand and follow established procedures for activities like code reviews, deployments, incident response, and other workflows. **Why this priority**: Querying processes is the core functionality of this feature. Developers need immediate access to process information to follow correct procedures during their work. **Independent Test**: Can be fully tested by calling the process query tool with different process names - delivers relevant process documentation to the AI assistant. **Acceptance Scenarios**: 1. **Given** the user is authenticated, **When** the AI assistant requests a specific process (e.g., "code-review"), **Then** the server returns the complete process documentation content. 2. **Given** the user is authenticated, **When** the AI assistant requests a process with a name that doesn't match exactly (case-insensitive), **Then** the server returns an error message listing available processes so the user can find the correct name. 3. **Given** the user requests a process that does not exist, **When** the server processes the request, **Then** a clear error message is returned listing available processes. 4. **Given** the user is not authenticated, **When** the AI assistant requests a process, **Then** the server returns an authentication error consistent with existing tool behavior. --- ### User Story 2 - List Available Processes (Priority: P2) As a developer, I want to see all available development processes so that I know what procedures are documented and available for reference. **Why this priority**: Discovery feature that enables users to know what processes exist before querying specific ones. **Independent Test**: Can be fully tested by calling the list-processes tool - delivers a complete inventory of available process documents. **Acceptance Scenarios**: 1. **Given** the user is authenticated, **When** the AI assistant requests the list of available processes, **Then** the server returns all process names with brief descriptions. 2. **Given** new process files are added to the process directory, **When** the list is requested, **Then** the new processes appear in the list without server restart. 3. **Given** the process directory is empty, **When** the list is requested, **Then** the server returns an empty list with a clear message. --- ### User Story 3 - Search Processes by Keyword (Priority: P3) As a developer, I want to search across all process documents for specific keywords or topics so that I can find relevant procedures without knowing exact process names. **Why this priority**: Enhanced discovery that improves usability for finding related processes across the documentation set. **Independent Test**: Can be fully tested by calling the search tool with various keywords - delivers matching processes ranked by relevance. **Acceptance Scenarios**: 1. **Given** the user is authenticated, **When** the AI assistant searches for "deployment", **Then** the server returns all processes containing that keyword in title, description, or content. 2. **Given** the user searches for a keyword that matches multiple processes, **When** the results are returned, **Then** they are ordered by relevance (title matches before content matches). 3. **Given** the user searches for a keyword with no matches, **When** the search completes, **Then** a clear message indicates no processes matched the search criteria. --- ### Edge Cases - What happens when process markdown files are malformed (missing frontmatter)? - System returns readable content with default metadata (filename as name, no description). - What happens when the process directory does not exist? - System returns a clear error message indicating the directory is not configured or missing. - How does the system handle very large process documents? - System returns the full content; AI assistant handles any display truncation. - What happens when process files have duplicate names (case-insensitive)? - System uses case-insensitive matching; first file found is returned with a warning in logs. - How does the system handle special characters in process names? - System normalizes names (removes special chars, replaces spaces with hyphens) for matching. ## Requirements *(mandatory)* ### Functional Requirements **Process Retrieval** - **FR-001**: System MUST expose an MCP tool for retrieving individual processes by name (`get_process`). - **FR-002**: System MUST read process content from markdown files stored in a configurable directory (separate from checklists). - **FR-003**: System MUST parse YAML frontmatter from process markdown files to extract name and description metadata. - **FR-004**: System MUST support case-insensitive process name matching. - **FR-005**: System MUST return process content in a format consumable by AI assistants (matching checklist response format). **Process Discovery** - **FR-006**: System MUST expose an MCP tool for listing all available processes (`list_processes`). - **FR-007**: System MUST support dynamic process discovery without server restart. - **FR-008**: System MUST return process metadata (name, description) in list responses without full content. **Process Search** - **FR-009**: System MUST expose an MCP tool for searching processes by keyword (`search_processes`). - **FR-010**: System MUST search across process name, description, and content fields. - **FR-011**: System MUST return search results ordered by relevance (title matches ranked higher than content matches). - **FR-012**: System MUST support partial keyword matching (substring search). - **FR-012a**: System MUST return up to 50 search results maximum, ordered by relevance. **Authentication & Error Handling** - **FR-013**: System MUST require authentication for all process tools using the existing authentication mechanism (LOCAL, CLOUD, or AUTO mode). - **FR-014**: System MUST provide descriptive error messages when requested processes are not found. - **FR-015**: System MUST provide error messages listing available processes when a specific process is not found. **Configuration** - **FR-016**: System MUST support a configurable process directory path via environment variable (`PROCESS_DIR`). - **FR-017**: System MUST default to a `./processes` directory if `PROCESS_DIR` is not specified. ### Key Entities - **Process**: A development procedure document containing steps, guidelines, or workflows. Has a unique name (derived from filename), description (from YAML frontmatter), and markdown content. Examples include: code-review, deployment, incident-response, release-management. - **ProcessMetadata**: Summary information about a process. Includes name and description without full content. Used in list and search responses. - **SearchResult**: A process that matches a search query. Includes process metadata plus a relevance score and optional snippet showing the matched content. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Process retrieval requests return complete content in under 2 seconds. - **SC-002**: Process listing returns all available processes in under 1 second. - **SC-003**: Process search returns results in under 3 seconds for directories with up to 100 process files. - **SC-004**: 100% of process tool calls succeed without re-authentication during a continuous session (matching checklist behavior). - **SC-005**: System correctly returns all available processes when the list tool is called. - **SC-006**: Search results include all processes containing the search keyword. - **SC-007**: Process tools provide actionable error messages in 100% of failure cases. ## Assumptions - Process files are stored as standard markdown (.md) files with optional YAML frontmatter. - Process file naming follows the pattern: `process-name.md` (lowercase, hyphens for spaces). - The process directory is separate from the checklist directory to maintain clear separation. - Users have the same access to all processes (no per-process access control). - Process content is read-only (no editing through the MCP server). ## Out of Scope - Process editing or creation through the MCP server (read-only access). - Version control or history tracking for process documents. - Per-process access control or permissions. - Process workflow automation or execution. - Integration with external process management tools. - Process approval workflows or sign-offs.