SSO MCP Server

# Research Notes: Process Query Feature **Feature**: 003-process-query **Date**: 2025-12-13 **Status**: Complete ## Research Summary This feature follows established patterns from the existing checklist module. No significant unknowns or new technologies required. ## Decision 1: Module Structure **Decision**: Follow parallel module design (separate process module from checklist module) **Rationale**: - Clear separation of concerns between checklists (verification items) and processes (procedural documentation) - Independent evolution without cross-dependencies - Proven pattern from checklist implementation - Search capability is process-specific **Alternatives Considered**: 1. **Unified document module** - Rejected: Violates single responsibility, complicates testing 2. **Extend checklist module** - Rejected: Different semantics (checklists vs. processes) **Architecture Alignment**: ADR-006 (Parallel Module Design for Processes) ## Decision 2: Search Implementation **Decision**: In-memory substring search with relevance ranking **Rationale**: - Expected document count is small (< 100 files) - Performance requirement (< 3 seconds) easily met with in-memory approach - No additional dependencies required - Simple implementation, easy to test and maintain **Relevance Scoring Algorithm**: - Name match: 100 points - Description match: 50 points - Content match: 10 points per occurrence (capped) - Case-insensitive matching - Results sorted by total score descending - Maximum 50 results returned **Alternatives Considered**: 1. **Whoosh (Python full-text search)** - Rejected: Overkill for < 100 documents 2. **SQLite FTS** - Rejected: Unnecessary complexity for read-only markdown files 3. **Elasticsearch** - Rejected: Inappropriate for local CLI tool **Architecture Alignment**: ADR-007 (In-Memory Search with Relevance Ranking) ## Decision 3: Process Name Normalization **Decision**: Normalize process names for case-insensitive matching with special character handling **Rationale**: - Consistent with checklist module behavior - Allows flexible file naming while maintaining searchability - Handles edge cases (spaces, special chars) **Normalization Rules**: 1. Convert to lowercase 2. Replace spaces with hyphens 3. Remove special characters (keep alphanumeric and hyphens) 4. Strip leading/trailing hyphens **Example**: - "Code Review Process" → "code-review-process" - "incident_response" → "incident-response" - "Deploy & Release" → "deploy-release" ## Decision 4: Error Handling Pattern **Decision**: Return structured error responses with actionable guidance (matching checklist pattern) **Rationale**: - Consistent error format across all MCP tools - Actionable error messages per FR-014, FR-015, SC-007 - Lists available processes when requested process not found **Error Response Format**: ```python { "error": "PROCESS_NOT_FOUND", "message": f"Process '{name}' not found.", "available": ["code-review", "deployment", ...] } ``` ## Decision 5: Configuration **Decision**: Add PROCESS_DIR environment variable with default to `./processes` **Rationale**: - Consistent with CHECKLIST_DIR pattern - Separate directory prevents confusion between content types - Default directory allows zero-config startup **Architecture Alignment**: Follows existing Settings pattern in config/settings.py ## Dependencies Confirmed All dependencies are already available in the project: | Dependency | Version | Purpose | Status | |------------|---------|---------|--------| | python-frontmatter | ^1.1.0 | YAML frontmatter parsing | Existing | | structlog | ^24.0.0 | Structured logging | Existing | | pathlib | stdlib | File discovery | Built-in | | re | stdlib | Name normalization | Built-in | ## No New Dependencies Required The process query feature can be implemented entirely with existing dependencies. No changes to pyproject.toml needed. ## Existing Code Patterns to Follow ### From checklists/service.py - Class-based service with constructor taking directory path - `get_*` method returns full content or None - `list_*` method returns metadata only - Case-insensitive name matching - Structured logging with get_logger ### From checklists/discovery.py - `discover_*` function using pathlib glob - Returns Iterator[Path] for memory efficiency - Handles missing directory gracefully ### From checklists/parser.py - `parse_*_file` function using frontmatter library - Returns dict with name, description, content, path - Falls back to filename if frontmatter missing ### From tools/get_checklist.py - `*_impl` function for tool logic - Service instance passed as parameter - Structured response format