# Physics MCP Server 2.0

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

[Home](README.md) | [Docs](docs/README.md) | [Architecture](docs/Architecture.md) | [Configuration](docs/Configuration.md) | Tool Docs: [All Tools](docs/Tools/AllTools.md) | [CAS](docs/Tools/CAS.md) | [Plot](docs/Tools/Plot.md) | [NLI](docs/Tools/NLI.md) | [Report](docs/Tools/Report.md) | [Tensor](docs/Tools/Tensor.md) | [Quantum](docs/Tools/Quantum.md) | [StatMech](docs/Tools/StatMech.md)

<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):
```bash
# 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**:
```bash
# 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:
```bash
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](docs/Configuration.md) 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):
```json
// 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):
```json
// 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
```bash
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
```bash
# 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](docs/tools/index.md)**: Complete tool reference with examples
- **[Architecture](docs/Architecture.md)**: System design and components
- **[Configuration](docs/Configuration.md)**: Setup and environment variables
- **[Improvements Summary](IMPROVEMENTS_SUMMARY.md)**: Recent enhancements and features

### Tool Documentation (Auto-generated)
- **[CAS](docs/tools/cas.md)**: Computer Algebra System operations
- **[Plot](docs/tools/plot.md)**: Plotting and visualization
- **[Quantum](docs/tools/quantum.md)**: Quantum computing operations
- **[Units Convert](docs/tools/units_convert.md)**: Unit conversions and smart evaluation
- **[Constants](docs/tools/constants_get.md)**: Physical constants lookup
- **[Data](docs/tools/data.md)**: Data I/O and signal processing

### Quickstart Guides
- **[Projectile Motion](examples/quickstart/projectile-motion.mdx)**: Physics with units
- **[Signal Analysis](examples/quickstart/signal-analysis.mdx)**: FFT and spectrograms  
- **[Partition Functions](examples/quickstart/partition-function.mdx)**: Statistical mechanics
- **[NLI Workflow](examples/quickstart/nli-workflow.mdx)**: Natural language interface

### Schemas & Validation
- **[Units Registry](schemas/units.json)**: 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.