SSO MCP Server

# Quickstart: Process Query Feature **Feature**: 003-process-query **Date**: 2025-12-13 ## Overview This guide demonstrates how to use the Process Query feature to access development process documentation through the MCP server. ## Prerequisites 1. SSO MCP Server running (`uv run sso-mcp-server`) 2. Authentication configured (LOCAL, CLOUD, or AUTO mode) 3. Process files in the PROCESS_DIR (default: `./processes`) ## Configuration ### Environment Variables ```bash # Optional: Set custom process directory (default: ./processes) PROCESS_DIR=/path/to/your/processes # Example .env addition PROCESS_DIR=./processes ``` ### Creating Process Files Process files are markdown files with optional YAML frontmatter: ```markdown --- name: Code Review Process description: Standard procedure for code reviews --- # Code Review Process ## Overview This document describes our code review standards. ## Steps 1. Create a pull request 2. Request reviewers 3. Address feedback 4. Merge after approval ``` **File naming convention**: `process-name.md` (lowercase, hyphens for spaces) ## Using the Tools ### Tool 1: get_process Retrieve a specific process by name. **Request**: ```json { "name": "code-review" } ``` **Response (success)**: ```json { "name": "Code Review Process", "description": "Standard procedure for code reviews", "content": "# Code Review Process\n\n## Overview\n..." } ``` **Response (not found)**: ```json { "error": "PROCESS_NOT_FOUND", "message": "Process 'unknown' not found.", "available": ["code-review", "deployment", "incident-response"] } ``` ### Tool 2: list_processes List all available processes. **Request**: ```json {} ``` **Response**: ```json { "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 } ``` ### Tool 3: search_processes Search across all processes by keyword. **Request**: ```json { "query": "deployment" } ``` **Response**: ```json { "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 } ``` ## Test Scenarios ### Scenario 1: Basic Process Retrieval (User Story 1) **Given**: Server running, user authenticated, process files exist **When**: Request `get_process` with name "code-review" **Then**: Returns complete process content ```bash # Using Claude Code "Get the code-review process" # AI calls get_process tool with name="code-review" ``` ### Scenario 2: Process Not Found **Given**: Server running, user authenticated **When**: Request `get_process` with non-existent name **Then**: Returns error with available processes listed ### Scenario 3: List All Processes (User Story 2) **Given**: Server running, user authenticated **When**: Request `list_processes` **Then**: Returns all process names and descriptions ```bash # Using Claude Code "What development processes are available?" # AI calls list_processes tool ``` ### Scenario 4: Dynamic Discovery **Given**: Server running, user authenticated **When**: New process file added to PROCESS_DIR **Then**: New process appears in `list_processes` without restart ### Scenario 5: Keyword Search (User Story 3) **Given**: Server running, user authenticated, multiple processes exist **When**: Request `search_processes` with keyword "deploy" **Then**: Returns matching processes ranked by relevance ```bash # Using Claude Code "Search for processes related to deployment" # AI calls search_processes tool with query="deployment" ``` ### Scenario 6: Search with No Results **Given**: Server running, user authenticated **When**: Request `search_processes` with non-matching keyword **Then**: Returns empty results with helpful message ### Scenario 7: Authentication Required **Given**: Server running, user NOT authenticated **When**: Request any process tool **Then**: Returns authentication error (consistent with checklist behavior) ## Validation Checklist - [ ] Process retrieval returns content in under 2 seconds - [ ] Process listing returns all processes in under 1 second - [ ] Search returns results in under 3 seconds (up to 100 files) - [ ] Authentication errors are clear and actionable - [ ] Case-insensitive name matching works - [ ] Files without frontmatter use filename as name - [ ] Search results are ordered by relevance - [ ] Maximum 50 search results returned ## Troubleshooting ### Process Not Found 1. Check process file exists in PROCESS_DIR 2. Verify file has `.md` extension 3. Check file permissions 4. Try listing all processes to see available names ### Empty Process List 1. Verify PROCESS_DIR is set correctly 2. Ensure directory contains `.md` files 3. Check file permissions ### Search Returns Unexpected Results 1. Search is case-insensitive 2. Partial matches are included 3. Name matches rank higher than content matches 4. Maximum 50 results returned