sso-mcp-server: Instructions file for Claude Code

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

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