quality-screener-mcp-server: Instructions file for Claude Code

CLAUDE.md / AGENTS.md

Guidance for AI coding agents working in this repository. AGENTS.md is a symlink to this file. The workspace root (../CLAUDE.md) owns the cross-repo rules: worktrees, memory, and the REST contract with the quality-screener backend.

Critical rules

1. No business logic here. This is a thin, stateless façade. If a change needs computation, it belongs behind a REST endpoint in quality-screener/. Payload shaping (_slim_score_rows, normalize_config) is the one allowed exception — see Adapters.
2. Branch off main (this repo's default), in a worktree under ../worktrees/quality-screener-mcp-server/<branch-slug>/.
3. The backend ships first. Tools talk to the deployed API; a tool released ahead of its endpoint is broken in production.

Commands

Requires uv. Python >=3.11. No linter or type checker is configured.

uv sync                                          # install deps (incl. dev group)
uv run pytest                                    # full suite; no live backend needed
uv run pytest tests/test_tool_filters.py::test_screen_share_builds_full_url
uv run qscreener-mcp                             # stdio transport (default)

# HTTP mode, mirroring the remote deployment:
QSCREENER_MCP_TRANSPORT=streamable-http QSCREENER_MCP_PORT=8080 \
  QSCREENER_API_URL=http://localhost:8001 uv run qscreener-mcp

Architecture

An MCP façade over the Quality Screener REST API (the "stobot" backend), with no dependency on the backend Python package — every tool builds a request and returns the decoded JSON. Extending it means adding an @mcp.tool() that delegates to _guard.

Four modules under qscreener_mcp/:

• server.py — the whole tool surface (~760 lines). The FastMCP instance, every @mcp.tool(), token resolution, and the main() transport entry point. Config (_API_URL, _WEBSITE_URL, _PUBLIC_URL, _MCP_HOST) resolves at import time from env vars, so tests patch the module attribute (monkeypatch.setattr(server, "_WEBSITE_URL", ...)) rather than the env var.
• constants.py — everything fixed at build time: header names, env-var names and defaults, on-disk filenames, user-facing messages, and the Tool enum of canonical tool names. Env values are deliberately not resolved here.
• client.py — ApiClient, a minimal httpx wrapper. Attaches the bearer token as X-Stobot-CLI-Token, adds the analytics headers, decodes JSON (None for empty bodies), raises ApiError on any non-2xx. Self-contained copy of the backend CLI's client — keep it dependency-free.
• oauth.py — StobotOAuthProvider for HTTP mode. Access tokens are the backend CLI token (validated via whoami). Pending state, auth codes, and client registrations are HMAC-signed JWTs when $QSCREENER_OAUTH_SIGNING_KEY is set (Vercel / multi-instance); otherwise they stay in-memory (_pending, _codes) with clients also written to $QSCREENER_CONFIG_DIR/mcp_clients.json (single-process Railway / local).