Physics MCP Server 2.0

<p align="center"> <img src="docs/assets/header.svg" width="960" alt="Physics MCP banner" /> </p>

Home | Docs | Architecture | Configuration | Tool Docs: All Tools | CAS | Plot | NLI | Report | Tensor | Quantum | StatMech

<p align="center"> <a href="docs/guides/educators.md"><img alt="Educators Guide" src="https://img.shields.io/badge/Educators-Handbook-blueviolet?style=for-the-badge&logo=googlescholar&logoColor=white" /></a> <a href="https://github.com/BlinkZer0/Phys-MCP/stargazers"><img alt="Star Phys-MCP" src="https://img.shields.io/github/stars/BlinkZer0/Phys-MCP?style=for-the-badge&label=Star%20Project&logo=github" /></a> </p>

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.