SSO MCP Server

# Data Model: Process Query Feature **Feature**: 003-process-query **Date**: 2025-12-13 **Status**: Final ## Entities ### Process A development procedure document containing steps, guidelines, or workflows. **Source**: Markdown file with YAML frontmatter in PROCESS_DIR **Fields**: | Field | Type | Required | Source | Description | |-------|------|----------|--------|-------------| | name | str | Yes | Frontmatter or filename | Unique identifier for the process | | description | str | No | Frontmatter | Brief description of the process | | content | str | Yes | Markdown body | Full markdown content | | path | Path | Yes | File system | Absolute path to the source file | **File Format**: ```markdown --- name: Code Review Process description: Standard procedure for code reviews --- # Code Review Process ## Overview ... ``` **Validation Rules**: - Name must be non-empty (derived from filename if frontmatter missing) - Content must be readable (file must exist and be accessible) - Path must point to a .md file **Python Implementation**: ```python @dataclass class Process: name: str description: str content: str path: Path ``` --- ### ProcessMetadata Summary information about a process (without full content). **Purpose**: Used in list responses to avoid transferring full content **Fields**: | Field | Type | Required | Description | |-------|------|----------|-------------| | name | str | Yes | Process name | | description | str | No | Brief description | **Python Implementation**: ```python @dataclass class ProcessMetadata: name: str description: str = "" ``` --- ### SearchResult A process that matches a search query, with relevance scoring. **Purpose**: Used in search responses to rank and display matches **Fields**: | Field | Type | Required | Description | |-------|------|----------|-------------| | name | str | Yes | Process name | | description | str | No | Brief description | | relevance_score | float | Yes | Calculated relevance (0.0 - 1.0) | | snippet | str | No | Content excerpt showing match context | **Relevance Calculation**: - Name match: 100 points (normalized to 1.0) - Description match: 50 points - Content match: 10 points per occurrence (max 50 points) - Final score normalized to 0.0 - 1.0 range **Python Implementation**: ```python @dataclass class SearchResult: name: str description: str relevance_score: float snippet: str = "" ``` --- ## Response Formats ### get_process Response **Success**: ```python { "name": "code-review", "description": "Standard procedure for code reviews", "content": "# Code Review Process\n\n## Overview\n..." } ``` **Error (not found)**: ```python { "error": "PROCESS_NOT_FOUND", "message": "Process 'unknown' not found.", "available": ["code-review", "deployment", "incident-response"] } ``` --- ### list_processes Response **Success**: ```python { "processes": [ {"name": "code-review", "description": "Standard procedure for code reviews"}, {"name": "deployment", "description": "Production deployment steps"}, {"name": "incident-response", "description": "Incident handling procedures"} ], "count": 3 } ``` **Empty directory**: ```python { "processes": [], "count": 0, "message": "No processes found in the process directory." } ``` --- ### search_processes Response **Success (with matches)**: ```python { "results": [ { "name": "deployment", "description": "Production deployment steps", "relevance_score": 0.85, "snippet": "...deploy to production using..." }, { "name": "release-management", "description": "Release planning and execution", "relevance_score": 0.42, "snippet": "...after deployment is verified..." } ], "query": "deployment", "count": 2, "total_processes": 10 } ``` **No matches**: ```python { "results": [], "query": "nonexistent", "count": 0, "total_processes": 10, "message": "No processes matched the search criteria." } ``` --- ## State Transitions Processes are read-only. No state transitions apply. --- ## Relationships ``` ProcessService ├── uses → ProcessDiscovery (file discovery) ├── uses → ProcessParser (frontmatter parsing) └── uses → SearchEngine (keyword search) Process (file) └── parsed into → ProcessMetadata (list response) → SearchResult (search response) ``` --- ## Configuration Entity ### Settings Addition Add to existing `Settings` dataclass in `config/settings.py`: ```python # Process module settings process_dir: Path = field(default_factory=lambda: Path("./processes")) ``` **Validation**: - Directory must exist (skip validation if not using process tools) - Directory must be readable - Separate from checklist_dir