Physics MCP Server 2.0

A specialized MCP (Model Context Protocol) server for physicists, providing Computer Algebra System (CAS), plotting, and natural language interface capabilities.

Features

Server 2.0 Highlights

Core CAS and graphing: symbolic manipulation, equation solving, and high-resolution plots cover both planning and presentation workflows.
Unit-aware physics: units_convert and constants_get keep results consistent across SI, imperial, and astrophysical contexts.
Spectral and signal analysis: GPU-ready FFT, filtering, spectrogram, and wavelet utilities accelerate large datasets.
Quantum and relativity scaffolding: dedicated toolchains for operator algebra, standard Hamiltonians, and tensor calculus.
Thermodynamics and partition functions: statmech_partition captures canonical ensemble workflows with cached summaries.
Hardware awareness: accel_caps reports device acceleration modes so you can right-size jobs.
Natural language + API ingress: nli_parse bridges plain English to tool calls and api_tools pulls reference data.
AI augmentation: ml_ai_augmentation delivers symbolic regression, PINN surrogates, and derivation explainers with GPU-first defaults.
Collaboration and orchestration: distributed job submission, experiment DAGs, exports, and Markdown report generation stay in-sync.

Tool Suite (17)

cas: Computer Algebra System operations for evaluating expressions, differentiation, integration, solving equations and ODEs, and propagating uncertainty.
units_convert: Convert between units via the Pint registry with SI, imperial, and specialized physics unit coverage.
constants_get: Retrieve CODATA and astrophysical constants including c, h, G, M_sun, pc, ly, and more.
plot: Generate 2D/3D plots, vector fields, phase portraits, contours, volume plots, animations, and interactive visualizations.
accel_caps: Report available acceleration hardware and the active ACCEL_MODE/ACCEL_DEVICE.
nli_parse: Translate natural language physics requests into structured MCP tool calls.
tensor_algebra: Compute Christoffel symbols, curvature tensors, and geodesics (scaffold).
quantum: Quantum computing utilities for operators, solvers, and Bloch/probability visualizations (scaffold).
statmech_partition: Build partition functions and derived thermodynamic quantities from energy levels.
data: Unified data toolkit for HDF5/FITS/ROOT I/O plus GPU-first FFT, filtering, spectrogram, and wavelet analysis via the action parameter.
api_tools: Access external scientific APIs such as arXiv, CERN Open Data, NASA datasets, and NIST references.
export_tool: Publish research artifacts to Overleaf, GitHub, Zenodo, Jupyter, and immersive formats.
ml_ai_augmentation: GPU-first ML workflows for symbolic regression, PDE surrogates, pattern recognition, and derivation explanations.
graphing_calculator: Full-featured calculator with CAS, graphing, statistics, matrices, and programmable utilities.
distributed_collaboration: Distributed job submission, session sharing, lab notebooks, and artifact versioning.
experiment_orchestrator: DAG-driven orchestration with validation, execution, publishing, and collaboration hooks.
report_generate: Summarize MCP sessions into Markdown reports with linked artifacts.

Quick Start

Prerequisites

Node.js 20+
Python 3.11+
pnpm 8+

Optional (recommended for faster NLI):

LM Studio or any OpenAI-compatible local LM server

Installation

One-Command Setup (Recommended):

# Clone repository git clone <repository-url> cd phys-mcp # Single command setup: builds TypeScript, installs Python deps, runs healthcheck, starts server pnpm dev:all

Manual Setup:

# Install Node.js dependencies pnpm install # Install Python dependencies cd packages/python-worker pip install -r requirements.txt cd ../.. # Build all packages pnpm build # Run healthcheck to verify installation pnpm healthcheck # Start development server pnpm dev

Configuration

Copy .env.example to .env and customize:

cp .env.example .env

Key environment variables:

LM_BASE_URL: Local LM server URL (e.g., http://localhost:1234/v1)
DEFAULT_MODEL: Model name for NLI parsing
DEBUG_VERBOSE: Set to 1 for detailed logging
ACCEL_MODE: GPU acceleration mode (auto, cuda, cpu)

See Configuration Guide for details.

Optional: Faster NLI with LM Studio

LM Studio is not required. All CAS/plot/tensor/quantum/stat-mech calculations run in TypeScript/Python workers and work out of the box. Configuring a local LM endpoint such as LM Studio only accelerates the Natural Language Interface (NLI) that turns plain English into structured tool calls.

Why it helps

Lower latency: local inference avoids network round-trips and rate limits.
GPU utilization: LM Studio can use your GPU to speed up prompt parsing.
Better parsing on complex requests: higher-quality intent extraction reduces retries before calculations begin.
Privacy & cost: keep tokens local; no external API keys required.

How it speeds up “calculations” end-to-end

The math is computed by our Python/TS backends; the LM is used to decide “what to compute.” Faster parsing → fewer back-and-forths → quicker CAS/plot calls → faster overall results.

How to enable

Install and run LM Studio (or any OpenAI-compatible local server).
Set LM_BASE_URL (e.g., http://localhost:1234/v1) and DEFAULT_MODEL.
Optionally set LM_API_KEY if your local server requires it.

Example Usage

Consolidated Tool Format (Recommended):

// Computer Algebra System { "jsonrpc": "2.0", "id": "1", "method": "cas", "params": { "action": "diff", "expr": "sin(x**2)", "symbol": "x" } } // Smart Units Evaluation { "jsonrpc": "2.0", "id": "2", "method": "units_smart_eval", "params": { "expr": "c * 1 ns", "constants": {"c": true} } } // Quantum Computing { "jsonrpc": "2.0", "id": "3", "method": "quantum", "params": { "action": "visualize", "state": "0.707,0.707", "kind": "bloch" } } // Advanced Plotting { "jsonrpc": "2.0", "id": "4", "method": "plot", "params": { "plot_type": "function_2d", "f": "sin(x)", "x_range": [0, 6.28318], "dpi": 160, "emit_csv": true } }

Legacy Format (Still Supported):

// Individual tool names work for backward compatibility { "jsonrpc": "2.0", "id": "5", "method": "cas_diff", "params": { "expr": "sin(x**2)", "symbol": "x" } }

Development

Quick Commands

pnpm dev:all # Build, setup, healthcheck, start server pnpm build # Build all TypeScript packages pnpm test # Run all tests pnpm healthcheck # Verify system functionality pnpm lint # Check code style pnpm typecheck # TypeScript type checking pnpm precommit # Run pre-commit checks

Advanced Development

# Generate documentation pnpm docs:generate # Run with coverage pnpm test:coverage # Python worker testing cd packages/python-worker python -m pytest tests/ -v # Type checking pnpm -r typecheck

Documentation

Core Documentation

Tool Index: Complete tool reference with examples
Architecture: System design and components
Configuration: Setup and environment variables
Improvements Summary: Recent enhancements and features

Tool Documentation (Auto-generated)

CAS: Computer Algebra System operations
Plot: Plotting and visualization
Quantum: Quantum computing operations
Units Convert: Unit conversions and smart evaluation
Constants: Physical constants lookup
Data: Data I/O and signal processing

Quickstart Guides

Projectile Motion: Physics with units
Signal Analysis: FFT and spectrograms
Partition Functions: Statistical mechanics
NLI Workflow: Natural language interface

Schemas & Validation

Units Registry: Comprehensive unit definitions
API Schemas: Auto-generated from Zod validation schemas

Side note: We conserve clarity and momentum—any dispersion is purely numerical.

Roadmap

Phase 2+: tensor calculus (sympy.diffgeom), quantum ops (qutip), 3D rendering, PDE/FEM, scientific data I/O, LaTeX/PDF reporting.

License

MIT License - see LICENSE file for details.

Physics MCP Server