boxadm-mcp copilot-instructions.md

Repository overview

boxadm-mcp is an MCP (Model Context Protocol) server exposing Box admin-log analytics (external file access, external sharing exposure) to AI assistants over stdio transport. Built on the official mcp Python SDK's FastMCP (boxadm_mcp/server.py), with BoxClient/BoxOAuthClient (boxadm_mcp/client.py) wrapping the Box Enterprise API. Read-only: no tool ever revokes a share, deletes a file, or otherwise mutates anything.

See CLAUDE.md for the authoritative command list and architecture notes — read it before reviewing changes to client.py, oauth.py, or server.py. In particular, read CLAUDE.md's section on the Box refresh-token rotation invariant before reviewing any change to client.py's cache_lock(), _ensure_token(), _refresh(), or _force_refresh() — it explains why the locking is structured the way it is, not just what it does.

Build & validate

uv sync --dev
uv run pytest -v                    # 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 — there is no Windows job in this repo (unlike some sibling MCP repos in this family), because client.py imports fcntl at module load and would fail on import before any test ran. Don't suggest adding a Windows CI job without also addressing the fcntl dependency.

What to focus review on in this repo

1. Box's refresh token is single-use — a locking bug here is a real outage, not a style issue

Presenting an already-rotated Box refresh token revokes the entire token chain (Box's reuse-detection treats it as compromise), forcing a manual browser re-login via boxadm-mcp auth. cache_lock() in client.py exists specifically to serialize the refresh path across concurrent processes/sessions. When reviewing any change touching cache_lock(), _ensure_token(), _refresh(), or _force_refresh(), check specifically:

• Does every code path that calls _refresh() (persists a new refresh token) do so while holding cache_lock()?
• After acquiring the lock, does the code re-read the on-disk cache before deciding to refresh (another process may have already rotated while this one was waiting for the lock)? Skipping this re-check is the specific bug shape that would present a stale, already-rotated token.
• Is the lock acquired on the <cache>.lock sidecar path, not the cache file itself? (write_token_cache replaces the cache's inode via os.replace — a lock on that file would stop excluding anyone after the first write.) A test change in this area needs to demonstrate the concurrent-refresh scenario, not just the single-process happy path — see tests/test_oauth_client.py's existing lock/rotation tests as the bar.