Physics MCP Server

--- title: Phase 2 Implementation kind: tutorial header_svg: src: "/assets/svg/experiment-orchestrator-hero.svg" static: "/assets/svg/experiment-orchestrator-hero-static.svg" title: "Phase 2 Implementation" animate: true theme_variant: "auto" reduced_motion: "auto" --- # Physics MCP Server - Phase 2 Implementation ## Overview Phase 2 significantly extends the Physics MCP Server with advanced CAS capabilities, comprehensive units/constants support, enhanced plotting, session memory, and persistence. This document outlines all implemented features and their usage. ## Implemented Milestones ### M4 - CAS++ (Computer Algebra System Enhanced) #### New CAS Tools - **Enhanced Integration**: `cas_integrate` now supports variable substitution and bounds - **Advanced Equation Solving**: `cas_solve_equation` with symbol assumptions (real, positive, etc.) - **Enhanced ODE Solver**: `cas_solve_ode` with proper initial condition handling - **Uncertainty Propagation**: `cas_propagate_uncertainty` for error analysis using linear approximation #### Safety Features - **Safe Expression Parsing**: Restricted namespace for `sympify` operations - **Execution Timeouts**: Configurable timeouts (default 10s) for all operations - **Memory Limits**: Array size limits to prevent memory exhaustion - **Cross-platform Safety**: Windows-compatible timeout handling #### Example Usage ```json { "tool": "cas_propagate_uncertainty", "args": { "expr": "sqrt(x^2 + y^2)", "vars": { "x": {"value": 3.0, "sigma": 0.1, "unit": "m"}, "y": {"value": 4.0, "sigma": 0.15, "unit": "m"} } } } ``` ### M5 - Units & Constants (Round-trip Support) #### Units Package (`@phys-mcp/tools-units`) - **Unit Conversion**: `units_convert` with full Pint registry support - **Dimensional Analysis**: Automatic dimensionality checking - **Round-trip Compatibility**: Preserves unit information through calculations #### Constants Package (`@phys-mcp/tools-constants`) - **CODATA Constants**: All fundamental physical constants (c, h, ħ, k_B, G, e, etc.) - **Astrophysical Constants**: Solar mass, parsec, light-year, astronomical unit - **Unit-aware Results**: Constants returned with proper units and dimensionality #### Available Constants - `c` - Speed of light (299,792,458 m/s) - `h` - Planck constant (6.626×10⁻³⁴ J⋅s) - `hbar` - Reduced Planck constant - `e` - Elementary charge - `m_e`, `m_p` - Electron and proton masses - `k_B` - Boltzmann constant - `G` - Gravitational constant - `M_sun` - Solar mass - `pc` - Parsec - `ly` - Light year - And many more... ### M6 - Plot++ (Advanced Plotting) #### New Plotting Capabilities - **Phase Portraits**: `plot_phase_portrait` for 2D dynamical systems - **3D Surfaces**: `plot_surface_3d` with contour projections - **Contour Plots**: `plot_contour_2d` with customizable levels - **Enhanced Vector Fields**: Improved `plot_field_2d` with streamlines #### Export Formats - **PNG**: Base64-encoded high-resolution images - **CSV**: Raw data for external analysis - **SVG**: Vector graphics (where applicable) #### Example Usage ```json { "tool": "plot_phase_portrait", "args": { "dx": "y", "dy": "-2*x - 0.5*y", "x_min": -3, "x_max": 3, "y_min": -3, "y_max": 3, "title": "Damped Harmonic Oscillator" } } ``` ### M7 - Session Memory & Persistence #### SQLite Database Schema ```sql CREATE TABLE sessions ( id TEXT PRIMARY KEY, created_at INTEGER ); CREATE TABLE events ( id TEXT PRIMARY KEY, session_id TEXT, ts INTEGER, tool_name TEXT, input_json TEXT, output_json TEXT ); CREATE TABLE artifacts ( id TEXT PRIMARY KEY, session_id TEXT, ts INTEGER, kind TEXT, path TEXT, meta_json TEXT ); ``` #### Persistence Features - **Session Management**: Automatic session creation and tracking - **Event Logging**: All tool calls recorded with inputs/outputs - **Artifact Storage**: Plots and reports stored with metadata - **History Retrieval**: Recent session summary for NLI context #### Artifact Management - **Organized Storage**: `/artifacts/<session_id>/<uuid>.*` - **Metadata Tracking**: File type, creation time, associated tools - **Database Integration**: All artifacts referenced in SQLite ## Architecture Enhancements ### Python Worker Improvements - **Enhanced Error Handling**: Better exception management and reporting - **Memory Management**: Configurable limits and cleanup - **Performance Optimization**: Efficient array operations and caching - **Cross-platform Compatibility**: Windows, macOS, and Linux support ### TypeScript Package Structure ``` packages/ ├── mcp-types/ # Core MCP types and server implementation ├── server/ # Main orchestration server ├── tools-cas/ # Computer Algebra System tools ├── tools-plot/ # Plotting and visualization tools ├── tools-nli/ # Natural Language Interface ├── tools-units/ # Unit conversion tools (NEW) ├── tools-constants/ # Physical constants (NEW) └── python-worker/ # Python computation backend ``` ### Enhanced Tool Routing The server now routes tools based on prefixes: - `cas_*` → CAS tools - `plot_*` → Plotting tools - `units_*` → Units tools - `constants_*` → Constants tools - li_*` → Natural Language Interface ## Usage Examples ### Complete Physics Workflow ```json { "workflow": "Quantum Harmonic Oscillator Analysis", "steps": [ { "tool": "constants_get", "args": {"name": "hbar"}, "description": "Get reduced Planck constant" }, { "tool": "cas_evaluate", "args": { "expr": "hbar * omega * (n + 1/2)", "vars": { "hbar": {"value": 1.055e-34, "unit": "J*s"}, "omega": {"value": 1e14, "unit": "rad/s"}, "n": 0 } }, "description": "Calculate ground state energy" }, { "tool": "cas_propagate_uncertainty", "args": { "expr": "hbar * omega * (n + 1/2)", "vars": { "hbar": {"value": 1.055e-34, "sigma": 1e-37}, "omega": {"value": 1e14, "sigma": 1e12}, "n": {"value": 0, "sigma": 0} } }, "description": "Propagate measurement uncertainties" }, { "tool": "units_convert", "args": { "quantity": {"value": 6.626e-20, "unit": "J"}, "to": "eV" }, "description": "Convert to electron volts" } ] } ``` ## Testing and Validation ### Acceptance Criteria Status - ✅ **M4**: All CAS++ features implemented and tested - ✅ **M5**: Units and constants with round-trip support - ✅ **M6**: Advanced plotting with multiple export formats - ✅ **M7**: Session persistence and memory management ### Test Coverage - **Unit Tests**: Individual function testing in Python worker - **Integration Tests**: End-to-end tool call validation - **Safety Tests**: Timeout and memory limit verification - **Cross-platform Tests**: Windows, macOS, Linux compatibility ## Performance Characteristics ### Execution Limits - **Timeout**: 10 seconds per operation (configurable) - **Array Size**: 100,000 elements maximum - **Plot Resolution**: 100×100 grid maximum for 3D plots - **Memory Usage**: Bounded by array size limits ### Optimization Features - **Lazy Loading**: Tool packages loaded on demand - **Connection Pooling**: Reused Python worker processes - **Caching**: Repeated calculations cached where appropriate - **Efficient Serialization**: Optimized JSON-RPC communication ## Future Extensions ### Phase 3 Roadmap - **Report Generation**: LaTeX/PDF report compilation - **NLI v2**: Context-aware natural language processing - **Advanced ODE Systems**: Higher-order and coupled equations - **Symbolic Units**: Full symbolic unit manipulation - **Interactive Plotting**: Real-time plot updates ### Integration Opportunities - **Jupyter Integration**: Direct notebook support - **Web Interface**: Browser-based physics calculations - **API Gateway**: REST API for external applications - **Cloud Deployment**: Scalable cloud-based physics server ## Conclusion Phase 2 successfully transforms the Physics MCP Server into a comprehensive computational physics platform. With enhanced CAS capabilities, full units/constants support, advanced plotting, and persistent session management, it provides a solid foundation for complex physics calculations and analysis workflows. The implementation maintains backward compatibility with Phase 1 while adding significant new capabilities. All new features are thoroughly tested and documented, ready for production use in physics education, research, and engineering applications.