SSO MCP Server

# sso-mcp-server Development Guidelines MCP server providing development tools (checklists, process documentation, and more) with Azure Entra ID SSO authentication. Auto-generated from all feature plans. Last updated: 2025-12-15 ## Server Capabilities The SSO MCP Server exposes the following MCP tools: ### Checklist Tools - `get_checklist` - Retrieve a checklist by name (case-insensitive) - `list_checklists` - List all available checklists with metadata ### Process Tools - `get_process` - Retrieve a process document by name (case-insensitive) - `list_processes` - List all available processes with metadata - `search_processes` - Search processes by keyword with relevance ranking ## Active Technologies - Local file system (markdown files with YAML frontmatter for checklists and processes) ### Core Stack - Python 3.11+ with uv package manager - mcp ^1.24.0 (FastMCP HTTP Streamable transport) - structlog ^24.0.0 (structured logging) - python-dotenv ^1.0.0 (environment configuration) - python-frontmatter ^1.1.0 (markdown parsing) ### Authentication - Local Mode - msal ^1.30.0 (Azure Entra ID OAuth 2.0 PKCE) - msal-extensions ^1.2.0 (encrypted token cache) ### Authentication - Cloud Mode (v0.2.0+) - PyJWT ^2.8.0 (JWT validation) - cryptography ^42.0.0 (JWKS key handling) - httpx ^0.27.0 (async HTTP for JWKS fetching) ### Storage - Local file system for checklists (.md files with YAML frontmatter) - Local file system for processes (.md files with YAML frontmatter) - Encrypted token cache at ~/.sso-mcp-server/token_cache.bin (Local mode) ## Project Structure ```text src/sso_mcp_server/ ├── __init__.py # Package init, version, logging ├── __main__.py # CLI entry point ├── server.py # MCP Server (FastMCP, HTTP Streamable) ├── config/ │ ├── __init__.py │ └── settings.py # Settings with AuthMode enum ├── auth/ │ ├── __init__.py # Auth exports │ ├── manager.py # Local mode: Auth orchestration │ ├── browser.py # Local mode: OAuth PKCE flow │ ├── token_store.py # Local mode: Token persistence │ ├── middleware.py # Dual-mode routing decorator │ ├── exceptions.py # Auth exceptions (local + cloud) │ └── cloud/ # Cloud mode components │ ├── __init__.py │ ├── claims.py # TokenClaims dataclass │ ├── jwks_client.py # JWKS fetching with cache │ └── validator.py # JWT token validation ├── metadata/ # Protected Resource Metadata (RFC 9728) │ ├── __init__.py │ └── resource_metadata.py ├── checklists/ │ ├── __init__.py │ ├── service.py # Checklist business logic │ ├── discovery.py # File discovery │ └── parser.py # Frontmatter parsing ├── processes/ # NEW: Process Query feature (v0.3.0) │ ├── __init__.py │ ├── service.py # Process business logic + search │ ├── discovery.py # File discovery │ ├── parser.py # Frontmatter parsing │ └── search.py # Relevance-based search engine └── tools/ ├── __init__.py ├── get_checklist.py ├── list_checklists.py ├── get_process.py # NEW ├── list_processes.py # NEW └── search_processes.py # NEW tests/ ├── unit/ # Unit tests (218+ total) └── integration/ # Integration tests checklists/ # Default checklist directory processes/ # Default process directory specs/ # Feature specifications docs/ # Documentation ``` ## Commands ```bash # Install dependencies uv sync # Run server (local mode) AUTH_MODE=local AZURE_CLIENT_ID=xxx AZURE_TENANT_ID=xxx CHECKLIST_DIR=./checklists PROCESS_DIR=./processes uv run sso-mcp-server # Run server (cloud mode) AUTH_MODE=cloud RESOURCE_IDENTIFIER=https://api.example.com ALLOWED_ISSUERS=https://login.microsoftonline.com/tenant/v2.0 CHECKLIST_DIR=./checklists PROCESS_DIR=./processes uv run sso-mcp-server # Run tests uv run pytest # Run linting uv run ruff check src/ tests/ # Run security scan uv run bandit -r src/ # Format code uv run ruff format src/ tests/ ``` ## Configuration ### Environment Variables | Variable | Mode | Required | Default | Description | |----------|------|----------|---------|-------------| | `AUTH_MODE` | All | No | `local` | `local`, `cloud`, or `auto` | | `AZURE_CLIENT_ID` | Local | Yes* | - | Azure app client ID | | `AZURE_TENANT_ID` | Local | Yes* | - | Azure tenant ID | | `RESOURCE_IDENTIFIER` | Cloud | Yes* | - | Server's resource URL (audience) | | `ALLOWED_ISSUERS` | Cloud | Yes* | - | Comma-separated issuer URLs | | `JWKS_CACHE_TTL` | Cloud | No | `3600` | JWKS cache TTL (seconds) | | `SCOPES_SUPPORTED` | Cloud | No | - | Advertised scopes | | `CHECKLIST_DIR` | All | Yes | - | Checklist directory path | | `PROCESS_DIR` | All | No | `./processes` | Process directory path | | `MCP_PORT` | All | No | `8080` | Server port | | `LOG_LEVEL` | All | No | `INFO` | Log level | ## Code Style - Follow PEP 8 and Google-style docstrings - Use ruff for linting and formatting - Type hints required for all public APIs - Max function length: 30 lines - Test coverage target: >80% ## Recent Changes ### v0.3.0 (2025-12-15) - Process Query Feature - Added Process Module for development process documentation - Added 3 new MCP tools: get_process, list_processes, search_processes - Keyword search with relevance ranking (title matches ranked higher) - E2E test suite with 31 scenarios (100% pass rate) - Updated project description to reflect multi-function server capability ### v0.2.0 (2025-12-12) - OAuth 2.1 Resource Server Mode - Added dual-mode authentication (LOCAL, CLOUD, AUTO) - Added OAuth 2.1 Resource Server support ### v0.1.0 (2025-12-11) - Initial Release - Azure Entra ID SSO authentication - Checklist MCP tools (get_checklist, list_checklists) ## Feature Specifications - [001-mcp-sso-checklist](specs/001-mcp-sso-checklist/spec.md) - Base MCP server - [002-oauth21-resource-server](specs/002-oauth21-resource-server/design.md) - Cloud mode - [003-process-query](specs/003-process-query/spec.md) - Process query feature <!-- MANUAL ADDITIONS START --> <!-- MANUAL ADDITIONS END -->