entraadm-mcp: Instructions file for Claude Code

CLAUDE.md

Overview

MCP server for Microsoft Entra ID (Azure AD) sign-in and audit-log triage. Transport is stdio only. All 7 tools are read-only — there is no write/mutating tool. Auth is env-var driven (see below); no config file.

Commands

uv sync --dev
uv run pytest -v                  # all tests
uv run ruff check .               # lint (gated in CI)
uv run ruff format --check .      # format (gated in CI)
uv run entraadm-mcp --check       # resolve auth + probe Graph reachability
uv run python scripts/smoke_test.py   # live smoke test against a real tenant

Architecture

• entraadm_mcp/config.py — AuthConfig.from_env(): all three of ENTRAADM_TENANT_ID/_CLIENT_ID/_CLIENT_SECRET set selects app-only (ClientSecretCredential); none set selects azure-cli (AzureCliCredential); one or two set raises ConfigError (never a silent fallback to the wrong mode). max_pages_default() reads ENTRAADM_MAX_PAGES_DEFAULT, clamped to [MIN_MAX_PAGES, MAX_MAX_PAGES] = [1, 50], falling back to DEFAULT_MAX_PAGES = 5 on anything unparsable.
• entraadm_mcp/client.py — GraphClient: token acquisition/caching (_TOKEN_REFRESH_MARGIN_SECONDS = 300), get()/get_paged() (the latter follows @odata.nextLink and returns (items, capped)), and error translation. odata_quote()/validate_upn() are the injection defenses — every $filter built from tool input goes through one or both; MCP tool input is treated as adversarial. HTTP 403 is translated via _PERMISSION_HINTS into an actionable message (which Graph role/permission is missing); unmapped codes fall back to "{code}: {message}", never a raw stack trace. 429 retries once (respecting Retry-After); 5xx retries twice with exponential backoff. credential/http_client constructor params are # injectable for tests (respx-mocked httpx, a stub credential).
• entraadm_mcp/server.py — FastMCP("entraadm-mcp") with 7 tools. AADSTS_CODES is a hand-maintained dict (not exhaustive) annotating sign-in failure codes; missing codes return meaning: null, never hidden. _state = {"client": None} is the sole test-injection point (monkeypatch.setitem). Every tool's entry point catches (ConfigError, GraphError) and returns {"error": str(e)}; GraphPermissionError specifically adds missing_permission naming the actual Graph permission that endpoint needs (not a single global constant — get_user_auth_methods needs a different one than the sign-in/audit tools). Every paged result carries capped: bool.