Physics MCP Server

# 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.