entraadm-mcp: Instructions file for Claude Code

CLAUDE.md

Overview

MCP server for Microsoft Entra ID (Azure AD) sign-in and audit-log triage, plus Azure VM backup posture (Azure Resource Manager) and Microsoft 365 service health. Transport is stdio only. The 15 default tools are read-only; one state-changing tool, revoke_sign_in_sessions, is registered only when ENTRAADM_ENABLE_REVOKE_SESSIONS=1 (see Conventions). Auth is env-var driven for one tenant; the optional ENTRAADM_CONFIG INI file ([tenant.<name>] sections) makes one process serve several tenants (see Conventions). The other optional data file is ENTRAADM_SITES_INI (the tenant's own address ranges, same format as keycloak-mcp's KEYCLOAK_SITES_INI), loaded by entraadm_mcp/sites.py with longest-prefix lookup.

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. load_tenants() returns Tenants: env-only (ENTRAADM_CONFIG unset) is one tenant named default that every UPN routes to; with the file, one TenantConfig per [tenant.<name>] (tenant_id, domains, default, optional client_id + client_secret_env; no secret in the file). A section without client_id reuses the env app with its own tenant_id (or az login in that tenant). Unknown section/key, missing tenant_id/domains, a domain in two tenants, two defaults, or no default among several -> ConfigError; __main__ refuses to start then.
• entraadm_mcp/client.py — _RestClient is the shared bearer-token client (token acquisition/caching with _TOKEN_REFRESH_MARGIN_SECONDS = 300, retry budgets, the deadline-bounded request, get()/get_paged() returning (items, capped)); GraphClient (Graph v1.0, @odata.nextLink) and ArmClient (https://management.azure.com, bare nextLink, api-version from ARM_API_VERSIONS on every call, AuthorizationFailed → the Reader-role hint ARM_ROLE_HINT) subclass it. The two share one credential object and each caches its own scope's token. get_paged refuses to follow a continuation link whose scheme/host/port differ from the client's base URL (it would hand the bearer token to that host) — ApiError, not followed. The exception hierarchy is ApiError/ApiDeadline/ApiAuthError/ApiPermissionError, plus ApiTransportError (network failure after the retries), ApiServerError (5xx after the retries) and ApiResponseError (a success status with a non-JSON body). Every ApiError carries may_have_applied (set by _request_tracked, and by post() from all attempts): False only when no attempt can have been acted on. A write tool must branch on it -- never collapse an unknown outcome into a plain GraphError "not done"; GraphError etc. are aliases kept for the older imports. 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 — MCPServer("entraadm-mcp") with 15 tools (16 with the opt-in revoke). AADSTS_CODES is a hand-maintained dict (not exhaustive) annotating sign-in failure codes; missing codes return meaning: null, never hidden. _state = {"client": None, "arm": None} holds the two test-injection points (monkeypatch.setitem; the inject fixture always puts a FakeArmClient in arm, because health_check probes ARM too and a real AzureCliCredential would shell out to az). 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.