sagemath-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

SageMath MCP is a Model Context Protocol server exposing stateful SageMath computations to LLM clients via FastMCP. Each MCP session gets a dedicated Sage worker subprocess with persistent variable state across tool calls.

Commands

uv pip install -e .[dev]          # Install with dev extras
make lint                          # uv run ruff check
make test                          # uv run pytest (pure Python, no Sage needed)
make integration-test              # pytest inside Sage Docker container
make build                         # Build wheel + sdist via scripts/build_release.py
make sage-container                # Bootstrap the Sage Docker container
uv run pytest tests/test_server.py -k "test_name"  # Run a single test

Unit tests run with SAGEMATH_MCP_PURE_PYTHON=1 (uses Python math stdlib instead of Sage). Integration tests require docker exec sage-mcp and real Sage runtime.

Linting

Ruff with line-length 100, target Python 3.12. Rules: E, F, W, B, UP, ASYNC, RUF, I (import sorting). Run make lint before committing.

Testing

• All async tests use @pytest.mark.asyncio (asyncio_mode is "auto")
• Tests mirror source modules: test_server.py, test_session.py, test_security.py, test_config.py, etc.
• test_integration.py, test_use_cases.py and most of test_math_coverage.py require the Sage container
• Key fixtures: python_settings (injects force_python_worker=True), FakeContext (captures MCP context messages)

Architecture

Source lives in src/sagemath_mcp/:

• server.py - Entry point: the /health route, main(), and the imports that register the tools. Re-exports the tool functions, so from sagemath_mcp import server keeps working.
• app.py - The FastMCP object, instructions, lifespan and middleware. Owns mcp so tool modules can decorate against it without importing the module that imports them.
• runtime.py - SETTINGS, SESSION_MANAGER and resolve_session(). Read the manager through this module (never from .runtime import SESSION_MANAGER) so tests can swap it.
• codegen.py - Building the Sage snippets: prelude, literal encoding, the validation gates and the numeric guards. Any caller string reaching a template must pass a gate — generated code runs under trusted_policy(), which permits sage_eval.
• tools/ - The 40 tools and 3 resources by domain: session, core, calculus, algebra, discrete, stats, plotting, diagnostics, verify. A module missing from tools/__init__.py registers nothing.
• session.py - SageSessionManager (per-client session map with asyncio locks) and SageSession (spawns/manages _sage_worker.py subprocess via JSON stdin/stdout protocol).
• _sage_worker.py - Subprocess worker that executes code in a persistent namespace. Handles execute/reset/shutdown commands. Validates AST before compilation.
• security.py - AST validator enforcing SecurityPolicy. Caller code is deny-by-default: a name is refused unless the allowlist offers it or the caller's own code bound it. On top of that it blocks imports outright, eval/exec, dunder access, string-path attribute primitives (attrgetter and friends, which defeat every AST attribute rule), forbidden modules and known code-executing Sage helpers. Configurable via env vars.
• allowlist.py - Generated, never hand-edited. The names caller code may read, produced from the installed Sage by scripts/generate_allowlist.py (make allowlist, which writes through a temp file because the generator imports the module it replaces). An integration test and a weekly job fail when it and the installed Sage disagree.
• star_exports.py - Generated, never hand-edited. The curated from <module> import * exception to the import ban: internal SageMath modules whose public names are all ordinary mathematics, mapped to the exact names each star may bind. Produced by scripts/generate_star_exports.py, which screens each candidate module clean-as-a-whole with _star_export_screen (same danger basis as the namespace scrub). rewrite_permitted_imports expands a vetted star into these names before validation; nothing is added to the allowlist. test_the_star_exports_match_this_sage fails when a Sage upgrade makes a listed module dirty.
• symbols.py - PREDEFINED_SYMBOLS, the one source of truth for x, y, z, t. Read by the worker, the generated prelude and the refusal message; a test asserts they agree, because them disagreeing is what made the tools and evaluate_sage accept different mathematics.
• text.py - Strings shared between the tool modules and the app. They are part of the tool contract, so they live where both can reach them without a cycle.
• config.py - SageSettings dataclass driven by SAGEMATH_MCP_* environment variables.
• models.py - Pydantic models for results (EvaluateResult, SessionSnapshot, MonitoringSnapshot).
• monitoring.py - Thread-safe EvaluationMetrics (counters, latency, error tracking).