SSO MCP Server

# SSO MCP Server MCP server providing development tools with Azure Entra ID authentication. ## Overview This server implements the Model Context Protocol (MCP) to expose development tools to AI coding assistants like GitHub Copilot and Claude Code. It provides access to organizational resources such as: - **Development Checklists**: Quality standards and verification items for code reviews, architecture, and design - **Process Documentation**: Step-by-step procedures for development workflows like deployments, incident response, and code reviews - **More tools coming soon**: The server is designed to be extensible with additional development resources The server supports two authentication modes: - **Local Mode**: Browser-based Azure SSO for desktop/developer use - **Cloud Mode**: Bearer token validation for server deployments ## Features - Dual-mode authentication (Local SSO / Cloud Bearer tokens) - OAuth 2.1 compliant Resource Server (Cloud mode) - **Checklist tools**: `get_checklist`, `list_checklists` - **Process tools**: `get_process`, `list_processes`, `search_processes` - HTTP Streamable transport for MCP communication - JWKS-based token validation with caching - Secure local token persistence (Local mode) - YAML frontmatter-based metadata for all content types - Keyword search with relevance ranking for processes ## Prerequisites - Python 3.11+ - uv package manager - Azure App Registration - VSCode with GitHub Copilot or Claude Code ## Installation ```bash # Clone the repository git clone <repository-url> cd sso-mcp-server # Install dependencies uv sync # Configure environment cp .env.example .env # Edit .env with your configuration ``` ## Authentication Modes ### Local Mode (Default) For desktop/developer use with browser-based Azure SSO: ```bash AUTH_MODE=local AZURE_CLIENT_ID=your-app-registration-client-id AZURE_TENANT_ID=your-azure-tenant-id CHECKLIST_DIR=./checklists ``` ### Cloud Mode For server deployments with Bearer token validation: ```bash AUTH_MODE=cloud RESOURCE_IDENTIFIER=api://your-app-id ALLOWED_ISSUERS=https://login.microsoftonline.com/your-tenant-id/v2.0 CHECKLIST_DIR=./checklists ``` ### Auto Mode Automatically detects mode from request context: ```bash AUTH_MODE=auto # Configure both local and cloud settings ``` ## Configuration | 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* | - | API resource URL (audience) | | `ALLOWED_ISSUERS` | Cloud | Yes* | - | Comma-separated issuer URLs | | `JWKS_CACHE_TTL` | Cloud | No | `3600` | JWKS cache TTL (seconds) | | `CHECKLIST_DIR` | All | Yes | - | Checklist directory | | `PROCESS_DIR` | All | No | `./processes` | Process documentation directory | | `MCP_PORT` | All | No | `8080` | Server port | | `LOG_LEVEL` | All | No | `INFO` | Log level | ## Usage Start the server: ```bash # Local mode uv run sso-mcp-server # Cloud mode AUTH_MODE=cloud \ RESOURCE_IDENTIFIER=api://my-app \ ALLOWED_ISSUERS=https://login.microsoftonline.com/tenant/v2.0 \ CHECKLIST_DIR=./checklists \ uv run sso-mcp-server ``` The server uses **HTTP Streamable transport**. Configure your AI assistant to connect to `http://localhost:8080/mcp`. ### Supported Clients This MCP server works with: - **Claude Desktop** - Add to `claude_desktop_config.json` - **VSCode with GitHub Copilot** - Add to `.vscode/mcp.json` - **Cline** - Configure via Cline's MCP UI - **GitHub Copilot CLI** - Add to `~/.copilot/mcp-config.json` - **Claude Code CLI** - Add to `~/.claude/claude_desktop_config.json` Example configuration: ```json { "mcpServers": { "sso-checklist": { "type": "http", "url": "http://localhost:8080/mcp" } } } ``` ## Available Tools ### Checklist Tools #### get_checklist Retrieve a specific checklist by name (case-insensitive). ```json { "name": "coding" } ``` #### list_checklists List all available checklists with metadata (name, description). ### Process Tools #### get_process Retrieve a specific process document by name (case-insensitive). ```json { "name": "code-review" } ``` #### list_processes List all available process documents with metadata (name, description). #### search_processes Search for processes by keyword across name, description, and content. Returns up to 50 results ranked by relevance. ```json { "keyword": "deployment" } ``` ## Creating Content ### Checklists Add markdown files to your `CHECKLIST_DIR` with YAML frontmatter: ```markdown --- name: Coding Standards description: Code quality checklist for reviews --- # Coding Standards Checklist ## Naming - [ ] Variables use descriptive names - [ ] Functions follow verb_noun pattern ## Structure - [ ] Single responsibility per function - [ ] No code duplication ``` ### Processes Add markdown files to your `PROCESS_DIR` with YAML frontmatter: ```markdown --- name: Code Review Process description: Step-by-step guide for conducting code reviews --- # Code Review Process ## Before Review 1. Ensure all tests pass 2. Check code coverage ## During Review 1. Review for correctness 2. Check for security issues 3. Verify coding standards compliance ``` ## Development ```bash # Run tests uv run pytest # Run tests with coverage uv run pytest --cov=sso_mcp_server # Run linting uv run ruff check src/ tests/ # Run formatting uv run ruff format src/ tests/ # Run security scan uv run bandit -r src/ ``` ## Documentation - [Quickstart Guide](specs/001-mcp-sso-checklist/quickstart.md) - [Cloud Deployment Guide](docs/cloud-deployment.md) - [Architecture Overview](docs/architecture.md) - [Coding Standards](docs/standards.md) ## Project Structure ``` src/sso_mcp_server/ ├── auth/ # Authentication (local + cloud modes) │ └── cloud/ # JWT validation, JWKS client ├── checklists/ # Checklist service (get, list) ├── processes/ # Process service (get, list, search) ├── config/ # Settings and configuration ├── metadata/ # Protected Resource Metadata ├── tools/ # MCP tool implementations └── server.py # FastMCP server checklists/ # Default checklist directory processes/ # Default process directory tests/ ├── unit/ # Unit tests (266+ total) ├── integration/ # Integration tests └── e2e/ # End-to-end tests (31 scenarios) ``` ## Version History ### v0.3.0 (2025-12-13) - Added Process Query feature with 3 new MCP tools: `get_process`, `list_processes`, `search_processes` - Keyword search with relevance ranking across process documentation - E2E test suite with 31 scenarios (100% pass rate) - Updated project description to reflect multi-function server capability ### v0.2.0 (2025-12-12) - Added dual-mode authentication (LOCAL, CLOUD, AUTO) - Added OAuth 2.1 Resource Server support - Added JWT token validation with JWKS - Added Protected Resource Metadata (RFC 9728) - Added 91 new tests (218 total) ### v0.1.0 (2025-12-11) - Initial release - Azure Entra ID SSO authentication - MCP tools for checklist management - HTTP Streamable transport ## License MIT