SSO MCP Server

# Implementation Plan: Process Query Feature **Branch**: `003-process-query` | **Date**: 2025-12-13 | **Spec**: [spec.md](./spec.md) **Input**: Feature specification from `specs/003-process-query/spec.md` ## Summary Add MCP tools for querying development process documentation stored as markdown files. The feature provides three tools (`get_process`, `list_processes`, `search_processes`) following the existing checklist module pattern with added search capability. Uses existing authentication mechanism (LOCAL, CLOUD, AUTO modes). ## Technical Context **Language/Version**: Python 3.11+ **Primary Dependencies**: - mcp ^1.23.3 (FastMCP HTTP Streamable transport) - existing - python-frontmatter ^1.1.0 (YAML frontmatter parsing) - existing - structlog ^24.0.0 (structured logging) - existing - python-dotenv ^1.0.0 (environment configuration) - existing **Storage**: Local file system (process markdown files with YAML frontmatter) **Testing**: pytest with existing test fixtures and patterns **Target Platform**: Local developer machine (macOS, Linux, Windows) **Project Type**: Single Python package (src/sso_mcp_server/) **Performance Goals**: - Process retrieval: < 2 seconds (SC-001) - Process listing: < 1 second (SC-002) - Process search: < 3 seconds for up to 100 files (SC-003) **Constraints**: - Read-only access to process files - Search results limited to 50 maximum (FR-012a) - Process directory separate from checklist directory **Scale/Scope**: - Recommended up to 100 process files for optimal search performance - Single-user local operation ## Ground-rules Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* | Gate | Status | Evidence | |------|--------|----------| | I. Clean Code | PASS | Follows existing module patterns (checklist module), descriptive naming | | II. Test-First | PASS | Unit tests will be written for all new components | | III. Code Review | PASS | PR required for merge | | IV. Documentation | PASS | docstrings, type hints, README updates | | V. Continuous Improvement | PASS | No tech debt introduced, clean patterns | **Quality Gates**: - Pre-commit: ruff check, ruff format - Pre-merge: All tests pass, review approved - Pre-deploy: N/A (local CLI tool) ## Project Structure ### Documentation (this feature) ```text specs/003-process-query/ ├── design.md # This file ├── research.md # Phase 0 output ├── data-model.md # Phase 1 output ├── quickstart.md # Phase 1 output ├── contracts/ # Phase 1 output │ └── mcp-tools.json # MCP tool definitions └── tasks.md # Phase 2 output ``` ### Source Code (repository root) ```text src/sso_mcp_server/ ├── __init__.py ├── __main__.py ├── server.py # Add process tools registration ├── config/ │ └── settings.py # Add PROCESS_DIR setting ├── auth/ # Existing - no changes ├── checklists/ # Existing - no changes ├── processes/ # NEW: Process module │ ├── __init__.py # Module exports │ ├── service.py # ProcessService class │ ├── discovery.py # discover_processes function │ ├── parser.py # parse_process_file function │ └── search.py # SearchEngine class ├── metadata/ # Existing - no changes └── tools/ ├── __init__.py ├── get_checklist.py # Existing ├── list_checklists.py # Existing ├── get_process.py # NEW: get_process tool ├── list_processes.py # NEW: list_processes tool └── search_processes.py # NEW: search_processes tool tests/ ├── unit/ │ ├── processes/ # NEW: Process unit tests │ │ ├── test_service.py │ │ ├── test_discovery.py │ │ ├── test_parser.py │ │ └── test_search.py │ └── tools/ │ ├── test_get_process.py # NEW │ ├── test_list_processes.py # NEW │ └── test_search_processes.py # NEW └── integration/ └── test_process_tools.py # NEW: Integration tests processes/ # Default process directory ├── code-review.md # Example process file ├── deployment.md # Example process file └── incident-response.md # Example process file ``` **Structure Decision**: Follows parallel module design (ADR-006 from architecture.md). Process module mirrors checklist module structure with added search capability. All tools use existing auth middleware. ## Architecture Alignment Per `docs/architecture.md` v1.2: - **ADR-006**: Parallel Module Design for Processes - Process module follows checklist module structure - **ADR-007**: In-Memory Search with Relevance Ranking - No external search engine needed - **Component View**: ProcessService, ProcessDiscovery, ProcessParser, SearchEngine - **Container View**: Process Module reads from separate PROCESS_DIR ## Dependencies ### Internal Dependencies - `sso_mcp_server.auth.middleware` - existing auth decorator - `sso_mcp_server.config.settings` - add PROCESS_DIR - `sso_mcp_server` - get_logger for structured logging ### External Dependencies - `python-frontmatter` - already in pyproject.toml - `pathlib` - standard library - `re` - standard library (for name normalization) ## Implementation Approach ### Phase 1: Core Process Module (P1 - User Story 1) 1. Add PROCESS_DIR to Settings 2. Create process discovery (discover_processes) 3. Create process parser (parse_process_file) 4. Create ProcessService with get_process method 5. Create get_process MCP tool 6. Write unit tests ### Phase 2: List Processes (P2 - User Story 2) 1. Add list_processes method to ProcessService 2. Create list_processes MCP tool 3. Write unit tests ### Phase 3: Search Processes (P3 - User Story 3) 1. Create SearchEngine class with relevance ranking 2. Add search_processes method to ProcessService 3. Create search_processes MCP tool 4. Write unit tests ### Phase 4: Integration & Polish 1. Register all tools in server.py 2. Integration tests 3. Example process files 4. Update README ## Complexity Tracking No ground-rules violations to justify. Design follows established patterns.