Skip to content

CLAUDE.md

Latest commit

 

History

History
133 lines (94 loc) · 3.79 KB

CLAUDE.md

File metadata and controls

133 lines (94 loc) · 3.79 KB
Raw

CLAUDE.md

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

Project Overview

GPU-accelerated MCP (Model Context Protocol) servers for computational mathematics, physics simulations, and machine learning. The system provides 4 specialized MCP servers that enable AI assistants to perform real scientific computing.

Build & Development Commands

# Install all dependencies
uv sync --all-extras

# Install MCP servers in editable mode (required for entry points)
uv pip install --python .venv/bin/python \
  -e servers/math-mcp \
  -e servers/quantum-mcp \
  -e servers/molecular-mcp \
  -e servers/neural-mcp

# Run tests (CPU only)
uv run pytest -m "not gpu"

# Run all tests including GPU
uv run pytest

# Run tests for specific server
uv run pytest servers/math-mcp/tests/

# Run single test
uv run pytest servers/math-mcp/tests/test_symbolic.py::test_solve_quadratic

# Lint and format
uv run ruff check --fix .
uv run ruff format .

# Type checking
uv run mypy shared/ servers/

# Run pre-commit hooks
uv run pre-commit run --all-files

# Run with coverage
uv run pytest --cov=shared --cov=servers

Architecture

Workspace Structure

This is a uv workspace with 6 packages:

  • servers/: 4 MCP server implementations (math-mcp, quantum-mcp, molecular-mcp, neural-mcp)
  • shared/: 2 shared packages (mcp-common, compute-core)

Shared Packages

  • mcp-common: GPUManager (CUDA/CPU backend selection), TaskManager (async task handling), Config (KDL configuration)
  • compute-core: Unified NumPy/CuPy array interface, FFT operations, linear algebra

MCP Server Pattern

Each server follows this structure in servers/<name>/src/<name>/server.py:

from mcp.server import Server
mcp = Server("server-name")

# Storage for stateful objects (avoid passing large arrays)
_arrays: dict[str, np.ndarray] = {}

@mcp.tool()
async def tool_name(param: str) -> dict[str, Any]:
    """Tool description."""
    result_id = f"result://{uuid4()}"
    _results[result_id] = result
    return {"result_id": result_id}

URI-Based References

Large data is stored by reference to minimize token usage:

  • array://uuid, potential://uuid, system://uuid, trajectory://uuid, model://uuid, simulation://uuid

Demo Generation

The demos showcase what users can expect when using the MCP servers through an AI assistant. They can ONLY be generated by prompting an LLM with the MCP tools enabled - this is the entire point. Do not create standalone scripts that bypass the MCP servers.

Use claude -p for one-shot generation:

claude -p "Create a double-slit interference demo with sensor line at x=220, save to /tmp/demo.gif"

Or interactively:

claude
> Simulate two galaxies colliding and render to /tmp/galaxy.gif

Critical Demo Parameters (from lessons learned)

Slit Experiments:

  • Wavefunction velocity = HALF momentum value (use momentum=0.2)
  • Slits at x=85 (1/3 of 256 grid), NOT halfway
  • Wavepacket width=35, time_steps=1400, dt=0.1
  • Sensor line at x=220 with fixed scale

Bragg Scattering:

  • Use tight Gaussian point centers (width=3), NOT cosine waves
  • Lattice spacing=25, depth=100

Galaxy Collision:

  • View bounds from INITIAL frame only (prevents postage stamp effect)
  • Slow approach velocity (0.15) for merge near end
  • Per-particle colors: blue=#4da6ff, red=#ff6b6b

Code Style

  • Line length: 100 characters
  • Type hints required for all functions
  • All MCP tool functions must be async
  • Use Google-style docstrings
  • Conventional commits: feat(math-mcp):, fix(quantum-mcp):, docs:, etc.

Test Markers

@pytest.mark.gpu          # Requires CUDA
@pytest.mark.slow         # Long-running
@pytest.mark.integration  # Cross-component
@pytest.mark.benchmark    # Performance tests