boxadm-mcp: Instructions file for Claude Code

CLAUDE.md

Overview

MCP (Model Context Protocol) server surfacing external file flow from a Box admin's point of view — reads the Box enterprise event log (admin_logs) to highlight who shares a lot with the outside and which files get accessed from outside. Built on the official mcp Python SDK's FastMCP (boxadm_mcp/server.py), over stdio transport. Read-only: no tool ever revokes a share, deletes a file, or otherwise mutates anything.

Commands

uv sync --dev
uv run pytest -v                    # run all tests
uv run ruff check .                 # lint
uv run ruff format --check .        # format check

This mirrors .github/workflows/ci.yml: a lint job (ruff check + ruff format --check) and a test job (pytest -v) on Python 3.10/3.12/3.13, Linux only — no Windows job, because client.py imports fcntl at module load (POSIX-only; see below), which would fail before any test runs.

Architecture

• boxadm_mcp/server.py — FastMCP server with 9 tools: health_check, recent_admin_events (raw diagnostic), external_access_events (enterprise-wide DOWNLOAD/PREVIEW analytics, plus a created_by_logins DLP-tracing mode), external_collaborators / public_shared_links / top_external_sharers (enumeration over the co-admin's visible folders, BFS via _scan()), list_folder_items (one folder's contents, with uploader attribution from uploader_display_name — created_by/modified_by are "Anonymous User" for a File Request upload, and since/until are compared as instants because Box's offset differs from the caller's), get_user (one account's current state by exact login — see below), and daily_brief (synthesis of both). _SCAN_CACHE memoizes _scan() results for 60s (_SCAN_TTL) keyed on (root_folder_id, max_folders, max_depth, want_collabs), so external_collaborators/top_external_sharers (same want_collabs=True key) share one traversal instead of re-walking; cleared on reset_client(). _scan() fans the per-folder get_folder_collaborations + get_folder_items calls out across a bounded ThreadPoolExecutor (BOX_SCAN_CONCURRENCY, default 8, clamped 1..32), draining one BFS level at a time up to the folder budget — Box has no enterprise-wide "list all collaborations" API, so the per-folder fan-out is unavoidable and concurrency is the only lever. Concurrency is deliberately not in the cache key (it changes speed, never results), and executor.map's order-preserving merge keeps the visited set, folders_scanned, and output ordering identical to a sequential walk. Per-folder API failures are tolerated but counted in fetch_errors and surfaced by every collab/exposure tool, so a folder dropped by an error is disclosed the same way capped discloses a budget cut — coverage is complete only when capped is false AND fetch_errors is 0. A 429 (honoring Retry-After) or transient 5xx is retried with jittered backoff in client.py's _get first (bounded by an attempt cap and a per-call wall-clock budget), so only a failure that outlasts those retries (e.g. a persistent 403, or a sustained throttle) lands in fetch_errors. That per-_get budget does not bound a whole scan, so _scan() also carries a soft wall-clock deadline (BOX_SCAN_DEADLINE, default 45s; 0 disables), checked only between BFS levels (the in-flight batch always finishes) — when hit it sets capped and returns the disclosed partial rather than letting the tool call run to a gateway timeout that returns nothing. The per-request HTTP timeout is BOX_HTTP_TIMEOUT (default 30s). Neither is in the cache key. When want_collabs=True, folders Box flags with is_externally_owned are skipped (an outside party owns them, so their collaborations aren't the enterprise's to audit) and reported separately under skipped_externally_owned, never silently dropped — this is Box's authoritative signal, and an earlier owner-domain heuristic (is_external(owner)) was tried and reverted as a production regression (it collapsed ~190 audited folders to 9).
• boxadm_mcp/client.py — two read-only client classes sharing _FolderReadMixin (the shared authenticated GET plus the folder/collaboration getters and get_users(), so one implementation serves both auth modes): BoxClient (Client Credentials Grant, server-to-server) and BoxOAuthClient (OAuth 2.0 user auth with an auto-refreshed, cross-process-locked token cache — see below). Exception hierarchy: BoxError (base) → BoxAuthError → BoxNotAuthenticatedError (no usable cache; run boxadm-mcp auth), and BoxError → BoxRequestError (an argument would have built a request other than the one intended — raised instead of being sent). server.py callers only special-case BoxNotAuthenticatedError (surfaced as needs-login); a bare BoxAuthError falls through to the same except BoxError handling as any other Box API failure — it is not given its own except BoxAuthError clause anywhere in server.py today.
• Ids decide the endpoint, so they are validated before interpolation. A folder id goes into the request PATH and httpx.URL resolves .. segments, so ../users rewrites /2.0/folders/../users into /2.0/users — a page of the enterprise directory, i.e. the enumeration get_user refuses. Two layers: _validate_resource_id() (decimal-only, in each folder getter, where a useful message about WHICH argument is possible) and _assert_endpoint_intact() in _get (no dot segment / query / fragment, root-relative), which covers every present and future path at the point the URL is assembled. BoxRequestError is a BoxError on purpose so _scan's per-folder handler absorbs one into fetch_errors instead of it escaping ThreadPoolExecutor.map as a raw traceback. That absorption is NOT the defence for a caller-supplied root: server._checked_root() validates that up front and returns an error dict, because an absorbed refusal would report a request that never left as a complete, empty result.
• boxadm_mcp/config.py — allowed_domains() reads BOX_ALLOWED_DOMAINS (comma-separated); no organization-specific default — an unset/empty value yields no domains, so is_external() treats every address as external until configured (fail-safe for a leakage-detection tool).
• boxadm_mcp/oauth.py — login(): the one-time interactive OAuth flow run via boxadm-mcp auth. Spins up a local http.server to catch the redirect, then writes the token cache through the same cache_lock/write_token_cache path BoxOAuthClient uses for refreshes.
• boxadm_mcp/__main__.py — CLI entry point (--version/auth) and the mcp.run() stdio server start.