MCP-Mathematics: 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

MCP Mathematics is a production-ready Model Context Protocol (MCP) server providing comprehensive mathematical computation capabilities. Built with FastMCP v2.0+, it exposes 52 advanced mathematical functions, 158 unit conversions across 15 categories, financial calculations, and statistical operations through 21 specialized MCP tools.

Key Architecture Principle: AST-based expression evaluation ensures security by preventing code injection while maintaining full mathematical capability.

Development Commands

Testing

# Run all tests (130 test cases)
python -m pytest tests/ -v

# Run tests with coverage
python -m pytest tests/ --cov=src --cov-report=html

# Run specific test categories
python -m pytest tests/test_calculator.py -v # Core functionality
python -m pytest tests/performance/ -v       # Performance tests
python -m pytest tests/security/ -v          # Security validation
python -m pytest tests/precision/ -v         # Numerical precision
python -m pytest tests/validation/ -v        # Input validation

Code Quality

# Auto-format code (100-character line limit)
black src/ tests/ --line-length 100

# Lint with Ruff
ruff check src/ tests/ --fix

# Type checking
mypy src/

# Security analysis
bandit -r src/

# Run all pre-commit checks
pre-commit run --all-files

Running the Server

# Development mode (local testing)
python -m mcp_mathematics

# Using uv (recommended for production)
uvx mcp-mathematics

# Install in editable mode for development
pip install -e .

Building and Distribution

# Clean previous builds
rm -rf dist/ build/

# Build source and wheel distributions
python -m build

# Verify package integrity
twine check dist/*

# Test installation in clean environment
pip install dist/*.whl

Architecture Overview

Core Components

Single-File Architecture: All functionality is consolidated in src/mcp_mathematics/calculator.py (~4500 lines) for maximum portability and minimal dependencies.