math-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 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}