Skip to main content
Glama
chrishayuk

Physics MCP Server

by chrishayuk
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Physics MCP Server

License: MIT Python 3.11+ Test Coverage Tests

Features: 🌀 Magnus Force • 💨 Wind Effects • 🏔️ Altitude • 🌡️ Temperature • 🔄 Tumbling Drag • 🎮 Rigid-Body Sims • 📊 515 Tests

A Model Context Protocol (MCP) server that brings comprehensive physics simulation and calculation capabilities to Large Language Models.

Transform your LLM into a physics engine! This MCP server provides 55 specialized tools spanning classical mechanics, fluid dynamics, rotational motion, and rigid-body simulations. Built for seamless integration with Claude, ChatGPT, and any MCP-compatible AI system.

📚 Table of Contents

🌟 What is This?

Physics MCP Server enables LLMs to perform sophisticated physics calculations and simulations through a standardized protocol. Instead of hallucinating physics formulas or making calculation errors, LLMs can now:

  • Calculate precisely: Use validated physics formulas for exact results

  • Simulate realistically: Run rigid-body physics with the Rapier engine

  • Visualize motion: Generate trajectory data for React Three Fiber, Remotion, and other 3D frameworks

  • Teach interactively: Answer physics questions with real calculations, not memorized facts

  • Design intelligently: Analyze forces, collisions, and motion for engineering applications

Why MCP?

The Model Context Protocol provides a standardized way to extend LLM capabilities beyond text generation. This server implements MCP to give language models direct access to:

  • ⚡ Instant physics calculations (projectile motion, forces, energy)

  • 🎮 Rigid-body simulations (collisions, bounces, stacking)

  • 📊 Motion analysis (trajectory fitting, kinematics, velocity profiles)

  • 🌊 Fluid dynamics (drag, buoyancy, lift, Bernoulli)

  • 🔄 Rotational mechanics (torque, angular momentum, gyroscopes)

  • ⚖️ Static analysis (equilibrium, beam reactions, friction)

  • 🔄 Unit conversions (62 unit types: velocity, distance, mass, time, acceleration, torque, frequency, data size, and more)

📦 What's Included

55 Physics Tools Across 10 Categories

Category

Tools

Description

Basic Mechanics

8 tools

Projectile motion, forces, energy, momentum, collisions

Fluid Dynamics

10 tools

Drag, buoyancy, terminal velocity, lift, Magnus force, Bernoulli

Rotational Dynamics

5 tools

Torque, moment of inertia, angular momentum, rotational KE

Oscillations

5 tools

Springs, pendulums, harmonic motion, damping

Circular Motion

5 tools

Centripetal force, orbits, banking angles, escape velocity

Statics

7 tools

Force balance, torque balance, friction, beam reactions

Kinematics

7 tools

Motion analysis, trajectory fitting, velocity calculations, projectile with drag

Collisions

2 tools

Elastic and inelastic 3D collisions with energy loss

Conservation Laws

4 tools

Energy, momentum, and angular momentum verification

Unit Conversions

2 tools

62 unit types across 16 categories (velocity, distance, mass, time, acceleration, torque, frequency, data, etc.)

Realistic vs Ideal Physics Comparison

See the dramatic difference when including real-world effects:

Sport

Scenario

Ideal (No Drag)

Realistic (With Enhancements)

Difference

⚾ Baseball

90 mph fastball

87.5m

52.3m (with drag)

-40% range

⛳ Golf

Pro drive at sea level

251m

129m (with drag)

-49% range

⛳ Golf

Same drive in Denver

251m

181m (drag + altitude)

-28% range

⚽ Soccer

Free kick with wind

25m straight

26m + 5.6m curve (wind + spin)

Bends 5.6m!

🎾 Tennis

Serve on hot day

27m

26.8m (less drag)

+2.3% vs cold

💡 Key Insight: Real physics matters! Air resistance can reduce range by 20-70% depending on the sport.

Two Calculation Modes

  1. Analytic Mode (Built-in, no setup)

    • Instant mathematical calculations

    • Perfect for education and quick answers

    • Exact solutions using physics formulas

    • Now includes: Advanced drag, spin (Magnus), wind, altitude effects

  2. Simulation Mode (Requires Rapier service)

    • Full rigid-body dynamics

    • Complex multi-object interactions

    • Realistic material properties and constraints

🚀 Quick Start (30 seconds)

# Try it instantly with uvx (no installation needed) uvx chuk-mcp-physics # Or with the public Rapier service for simulations RAPIER_SERVICE_URL=https://rapier.chukai.io uvx chuk-mcp-physics # Or use the public hosted MCP server (no local installation) # Add to Claude Desktop config with URL: https://physics.chukai.io/mcp

For Claude Desktop: Add to your config file:

Option 1: Public Hosted MCP Server (Easiest - No Installation)

{ "mcpServers": { "physics": { "command": "node", "args": ["-e", "require('https').get('physics.chukai.io/mcp')"] } } }

Option 2: Local uvx (Recommended)

{ "mcpServers": { "physics": { "command": "uvx", "args": ["chuk-mcp-physics"], "env": { "RAPIER_SERVICE_URL": "https://rapier.chukai.io" } } } }

🎯 Use Cases

1. Interactive Physics Education

LLM as Physics Tutor

User: "If I throw a ball at 20 m/s at 45°, how far will it go?" LLM: [calls calculate_projectile_motion] "The ball will travel 40.8 meters and reach a maximum height of 10.2 meters..." [generates visualization with trajectory points]

Real-World Problem Solving

  • Students ask physics questions in natural language

  • LLM calculates exact answers using the MCP tools

  • Can generate trajectory plots, force diagrams, energy graphs

  • Interactive "what-if" scenarios: "What if gravity was half?"

2. Game Development & Prototyping

Ballistics Design

User: "I'm designing a cannon in my game. Initial velocity 50 m/s, 30° angle. Will it clear a 15m wall at 80m distance?" LLM: [calls calculate_projectile_motion] "At 80m, the projectile is at 18.6m height - it WILL clear the wall. It lands at 110.9m range."

Collision Detection

User: "Two spaceships: Ship A at (0,0,0) moving at (10,0,0) m/s, Ship B at (100,5,0) moving at (-8,0,0) m/s. Will they collide?" LLM: [calls check_collision] "Yes, collision in 5.3 seconds at position (53.0, 2.65, 0.0) with impact speed 18 m/s"

Rapid Iteration

  • Test different launch angles, speeds, masses without coding

  • Verify collision logic before implementation

  • Generate realistic physics data for procedural content

3. 3D Visualization & Animation (React Three Fiber)

Automated Animation Data Generation

User: "Create a realistic basketball shot animation - 7m throw into 3m high basket" LLM: [calls calculate_projectile_motion with solved angle] [returns trajectory_points array] "Here's the trajectory data for R3F. The ball needs 52° launch angle..." <mesh position={interpolate(trajectory)}> <sphereGeometry args={[0.12]} /> </mesh>

Rigid-Body Simulations

User: "Simulate 10 boxes falling and stacking in a pile" LLM: [calls create_simulation] [calls add_rigid_body for ground + 10 boxes with random positions] [calls record_trajectory for each box] "Here are 10 trajectory arrays for your R3F scene, ready to use..."

Use Cases:

  • Product visualizations (dropping phones, bouncing balls)

  • Architectural collapse simulations (building demolition previews)

  • Sports analytics visualizations (ball trajectories, collision analysis)

  • Sci-fi effects (asteroid fields, debris clouds)

4. Engineering & Design Analysis

Vehicle Crash Prediction

User: "Two cars: Car A (1500kg) at 30 m/s, Car B (1200kg) at 25 m/s approaching. Distance 100m. When do they collide and what's the impact energy?" LLM: [calls check_collision for timing] [calls calculate_kinetic_energy for both cars] [calls calculate_momentum for momentum analysis] "Collision in 1.82 seconds. Total kinetic energy: 1,050,000 J..."

Safety Analysis

  • Calculate impact forces for crash test scenarios

  • Predict collision times for autonomous vehicle planning

  • Analyze momentum transfer in industrial equipment

Structural Testing (with Rapier simulations)

  • Simulate falling objects hitting structures

  • Test load-bearing capacity under dynamic loads

  • Model chain reactions (domino effects)

5. Sports & Athletics

Realistic Ball Trajectories with Air Resistance

User: "How far does a 90 mph baseball fastball actually travel with air resistance?" LLM: [calls calculate_projectile_with_drag with baseball parameters] "With drag (realistic): 52.3m range Without drag (vacuum): 87.5m range Air resistance reduces range by 40%! Energy lost to drag: 89.2 J..."

Golf Drive Analysis

User: "Pro golfer hits 70 m/s (155 mph) at 12° angle. How far with real air resistance?" LLM: [calls calculate_projectile_with_drag with golf ball parameters] "With drag: 129.4m (142 yards) Without drag: 251.0m (274 yards) Dimples reduce drag coefficient from 0.47 to 0.25 - saves ~50% range loss!"

Basketball 3-Pointer

User: "What launch angle for a 7.5 m/s shot from 6.75m away (3-point line)?" LLM: [calls calculate_projectile_with_drag iterating angles] "With air resistance, optimal angle is 48° (high arc). Range: 6.73m (close!), max height: 3.2m, flight time: 1.1s..."

Shot Analysis Applications

  • Baseball: Pitch trajectories, drag reduces 90mph fastball range by 40%

  • Golf: Drive distance with dimpled ball (Cd=0.25 vs smooth ball Cd=0.47)

  • Basketball: Arc optimization for free throws and 3-pointers

  • Soccer: Penalty kick trajectories, minimal drag at short distances

  • Track & field: Javelin, shot put with realistic air resistance

  • Tennis: Serve and groundstroke trajectory analysis

6. Astrophysics & Space Exploration

Orbital Mechanics (Simplified)

User: "Two asteroids on collision course. A: 500m radius at (0,0,0) moving 15 km/s. B: 300m radius at (100km, 2km, 0) moving -12 km/s. Impact prediction?" LLM: [calls check_collision with appropriate units] "Collision in 3.47 seconds at closest approach distance 650m. They will NOT collide - miss distance is 150m..."

Applications:

  • Asteroid impact prediction

  • Satellite collision avoidance

  • Debris field analysis

  • Launch trajectory planning (simplified cases)

7. Fluid Dynamics & Marine/Aerospace Engineering

Underwater Torpedo Simulation

User: "A torpedo is launched underwater at 20 m/s. It weighs 100kg, has a streamlined shape (Cd=0.04), and cross-section of 0.03 m². How far does it travel in 30 seconds?" LLM: [calls simulate_underwater_motion] "The torpedo travels 147.5 meters before drag and buoyancy slow it down. Final velocity: 0.2 m/s. Maximum depth: 729.9 m..."

Terminal Velocity & Drag Analysis

User: "What's the terminal velocity of a skydiver (70kg, 0.7m² area)?" LLM: [calls calculate_terminal_velocity] "Terminal velocity is 40 m/s (90 mph) in belly-down position. Takes 12.2 seconds to reach 95% of terminal velocity..."

Buoyancy & Float/Sink Predictions

User: "Will a 1kg steel ball (10cm diameter) float in water?" LLM: [calls calculate_buoyancy] "No, it will sink. Buoyant force is 5.14 N, but weight is 9.81 N. The ball is denser than water..."

Applications:

  • Marine engineering: Submarine drag, torpedo trajectories, underwater vehicles

  • Aerospace: Parachute descent, atmospheric re-entry, drag optimization

  • Sports science: Swimming efficiency, diving trajectories

  • Product design: Floatation devices, drag reduction, hydrodynamics

  • Environmental: Particle settling rates, pollutant dispersion

8. Film & VFX Pre-visualization

Stunt Planning

User: "Car jumps off 3m ramp at 25 m/s, 20° angle. How far does it fly and where does it land?" LLM: [calls calculate_projectile_motion] "Airtime: 1.75 seconds, landing at 42.9m horizontal distance, impact speed 26.3 m/s. Recommend crashmat at 40-45m mark..."

Destruction Sequences

  • Building collapses with rigid-body sim

  • Explosion debris trajectories

  • Vehicle stunts and crashes

  • Realistic object interactions

8. Military & Defense (Training/Education)

Ballistics Training

User: "Artillery shell: muzzle velocity 800 m/s, 45° elevation. Range and time of flight?" LLM: [calls calculate_projectile_motion] "Range: 65.3 km, flight time: 115.5 seconds, max altitude: 16.3 km"

Collision Avoidance

  • Projectile trajectory analysis

  • Impact point prediction

  • Intercept course calculations

9. Robotics & Automation

Path Planning

User: "Robot arm needs to toss part into bin 2m away, 0.5m higher. What velocity is needed?" LLM: [reverse-calculates using projectile_motion multiple times] "Minimum velocity: 4.7 m/s at 38° angle. Recommend 5.0 m/s for safety margin..."

Collision Detection

  • Multi-robot coordination

  • Object catching/throwing

  • Assembly line optimization

10. Data Science & Research

Physics Simulations for ML Training Data

# Generate thousands of collision scenarios for ML model training for i in range(10000): result = await check_collision(random_params()) training_data.append({ 'features': params, 'label': result.will_collide, 'impact_time': result.collision_time })

Use Cases:

  • Generate labeled physics data for ML models

  • Validate physics-informed neural networks

  • Test scientific hypotheses with rapid iteration

  • Monte Carlo simulations (vary parameters, aggregate results)

🚀 Real-World Example Workflows

Workflow 1: Basketball Shot Optimizer

1. User: "I'm 2m tall shooting from free-throw line (4.6m). Basket is 3.05m high. What's the minimum velocity needed?" 2. LLM calls calculate_projectile_motion with varying velocities - Try v=5 m/s → doesn't reach - Try v=7 m/s → reaches - Binary search finds minimum: v=6.2 m/s at 52° angle 3. LLM: "Minimum velocity is 6.2 m/s at 52° launch angle. For comfortable margin, use 7.0 m/s (typical free throw speed). Here's the trajectory visualization..."

Workflow 2: Car Crash Investigation

1. User: "Analyze accident: Car A (1500kg) skid marks 30m, Car B (1200kg) skid marks 25m. Coefficient of friction 0.7. What were impact speeds?" 2. LLM: - Calculates deceleration from friction: a = μg = 0.7 × 9.81 = 6.87 m/s² - Uses v² = 2ad to find velocities - Calls calculate_kinetic_energy for both cars - Calls calculate_momentum for momentum analysis 3. LLM: "Car A impact speed: ~20.3 m/s (45 mph), Car B: ~18.5 m/s (41 mph). Total kinetic energy at impact: 513,000 J. Here's the force analysis..."

Workflow 3: Game Level Design with Physics Simulation

1. User: "Create a Rube Goldberg machine: ball rolls down ramp, hits dominos, dominos knock ball into basket" 2. LLM: - Calls create_simulation(gravity_y=-9.81) - Adds ground plane (static) - Adds ramp (static, angled) - Adds ball (dynamic, sphere, position at ramp top) - Adds 10 dominos (dynamic boxes in a line) - Adds basket (static) - Calls step_simulation(steps=1000) - Analyzes contacts to verify chain reaction - Calls record_trajectory for each piece 3. LLM: "Simulation complete! Ball triggers all dominos successfully. Here are the trajectories for R3F visualization. Domino #3 falls at t=1.2s, domino #7 at t=2.1s..."

Workflow 4: Satellite Collision Warning

1. User: "Satellite A: position (6700km, 0, 0), velocity (0, 7.5km/s, 0) Satellite B: position (6650km, 50km, 0), velocity (0, 7.6km/s, 0.1km/s) Collision risk?" 2. LLM: - Calls check_collision with satellite data - Analyzes closest approach 3. LLM: "No collision. Closest approach: 48.3 km at t=412 seconds. Satellites are in similar orbits but safe separation. Recommend: monitor as orbits may precess over time."

🎨 Visualization Integration

React Three Fiber (R3F) Example

function PhysicsAnimation() { const [trajectory, setTrajectory] = useState([]); useEffect(() => { // LLM generated this trajectory data via MCP fetch('/api/mcp/record_trajectory', { body: JSON.stringify({ sim_id: "sim_xyz", body_id: "ball", steps: 300 }) }).then(res => setTrajectory(res.frames)); }, []); return ( <Canvas> <AnimatedBall trajectory={trajectory} /> <Ground /> </Canvas> ); } function AnimatedBall({ trajectory }) { const ref = useRef(); useFrame((state) => { const t = state.clock.getElapsedTime(); const frame = trajectory[Math.floor(t / 0.016) % trajectory.length]; if (frame && ref.current) { ref.current.position.fromArray(frame.position); ref.current.quaternion.fromArray(frame.orientation); } }); return ( <mesh ref={ref}> <sphereGeometry args={[0.5]} /> <meshStandardMaterial color="orange" /> </mesh> ); }

📊 Trajectory Data Format

All trajectory recordings follow a canonical schema for maximum interoperability with R3F, Remotion, Three.js, and other animation systems.

Schema Definition

interface Trajectory { dt: number; // Time step between frames (seconds) frames: Frame[]; // Ordered list of frames meta: { body_id: string; // Fully qualified: "rapier://sim-123/body-1" total_time: number; // Total duration (seconds) num_frames: number; // Frame count }; } interface Frame { t: number; // Absolute time (seconds) position: [number, number, number]; // [x, y, z] in meters rotation: [number, number, number, number]; // Quaternion [x, y, z, w] velocity?: [number, number, number]; // Optional: linear velocity (m/s) angular_velocity?: [number, number, number]; // Optional: angular velocity (rad/s) }

JSON Example

{ "dt": 0.016, "frames": [ { "t": 0.0, "position": [0, 1, 0], "rotation": [0, 0, 0, 1], "velocity": [0, 0, 0] }, { "t": 0.016, "position": [0.1, 1.01, 0], "rotation": [0, 0.01, 0, 0.9999], "velocity": [6.25, 0.61, 0] } ], "meta": { "body_id": "rapier://sim-abc123/ball", "total_time": 4.8, "num_frames": 300 } }

Usage in React Three Fiber

import { useRef } from "react"; import { useFrame } from "@react-three/fiber"; function AnimatedObject({ trajectory }) { const ref = useRef(); useFrame((state) => { const elapsed = state.clock.getElapsedTime(); const frameIdx = Math.floor(elapsed / trajectory.dt); const frame = trajectory.frames[frameIdx % trajectory.frames.length]; if (frame && ref.current) { ref.current.position.fromArray(frame.position); ref.current.quaternion.fromArray(frame.rotation); } }); return ( <mesh ref={ref}> <sphereGeometry args={[0.5]} /> <meshStandardMaterial color="orange" /> </mesh> ); }

Usage in Remotion

import { useCurrentFrame } from "remotion"; import { ThreeCanvas } from "@remotion/three"; export const PhysicsAnimation = ({ trajectory }) => { const frame = useCurrentFrame(); const frameData = trajectory.frames[frame]; return ( <AbsoluteFill> <ThreeCanvas> <mesh position={frameData.position}> <sphereGeometry /> </mesh> </ThreeCanvas> </AbsoluteFill> ); };

Design Notes

  • Quaternions for rotation: More compact and interpolation-friendly than Euler angles

  • Absolute time: Each frame has absolute time t, making scrubbing easier

  • Constant dt: Frames are evenly spaced, simplifying playback

  • Optional velocities: Include if needed for motion blur or physics visualization

  • Qualified body_id: Format is rapier://sim-{id}/{body_id} for traceability

🛠️ Installation

Prerequisites

  • Python 3.11+

  • For simulations: Rapier service (see RAPIER_SERVICE.md)

    • Public service available at:

    • Or run locally with Docker (see below)

Quick Start with uvx (Recommended)

The fastest way to try chuk-mcp-physics without installation:

# Run directly with uvx (no installation needed) uvx chuk-mcp-physics # With environment variables uvx --with chuk-mcp-physics chuk-mcp-physics

Installation Methods

Option 1: Install from PyPI (Recommended)

# Install globally pip install chuk-mcp-physics # Or with pipx (isolated environment) pipx install chuk-mcp-physics # Run the server chuk-mcp-physics # Or via python module python -m chuk_mcp_physics.server

Option 2: Install from Source

# Clone repository git clone https://github.com/yourusername/chuk-mcp-physics cd chuk-mcp-physics # Install in development mode make dev-install # Run the server chuk-mcp-physics

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Using uvx (Recommended - No Installation Required)

{ "mcpServers": { "physics": { "command": "uvx", "args": ["chuk-mcp-physics"], "env": { "PHYSICS_PROVIDER": "rapier", "RAPIER_SERVICE_URL": "https://rapier.chukai.io" } } } }

Option 2: Using Installed Package

{ "mcpServers": { "physics": { "command": "python", "args": ["-m", "chuk_mcp_physics.server"], "env": { "PHYSICS_PROVIDER": "rapier", "RAPIER_SERVICE_URL": "https://rapier.chukai.io" } } } }

Option 3: Analytic Only (No External Service)

{ "mcpServers": { "physics": { "command": "uvx", "args": ["chuk-mcp-physics"], "env": { "PHYSICS_PROVIDER": "analytic" } } } }

📖 Available Tools

Tool Organization

Tools are organized into two tiers to help you choose the right abstraction:

1️⃣ Analytic Primitives (No External Service)

Best for: Quick calculations, education, simple scenarios

Direct formula-based calculations that return instant results:

Tool

What It Does

Example Use Case

calculate_projectile_motion

Ballistic trajectory using kinematic equations

"How far does a cannonball go?"

check_collision

Predict if two spheres will collide

"Will these asteroids hit?"

calculate_force

F = ma calculations

"What force accelerates this car?"

calculate_kinetic_energy

KE = ½mv²

"How much energy in this crash?"

calculate_momentum

p = mv

"What's the momentum transfer?"

calculate_potential_energy

PE = mgh

"What's the energy at height?"

calculate_work_power

Work (F·d) and power (W/t)

"How much work lifting this box?"

calculate_elastic_collision

1D elastic collision (conserves energy & momentum)

"Pool balls colliding?"

calculate_drag_force

Air/water resistance (F = ½ρv²C_dA)

"What's the drag on this car?"

calculate_buoyancy

Will it float? (Archimedes)

"Does a steel ball float in water?"

calculate_terminal_velocity

Maximum fall speed

"How fast does a skydiver fall?"

simulate_underwater_motion

Underwater trajectory with drag & buoyancy

"How far does a torpedo travel?"

Characteristics:

  • ⚡ Instant execution (< 1ms)

  • 📦 No external dependencies

  • 🎯 Exact mathematical solutions

  • ✅ Always available (no service required)

Limitations:

  • Only spherical objects (for collisions)

  • No complex shapes

  • No multi-body interactions

  • No friction or material properties

2️⃣ Simulation Primitives (Requires Rapier Service)

Best for: Complex physics, multi-body dynamics, visualization data

Low-level building blocks for rigid-body simulations:

Tool

What It Does

When to Use

create_simulation

Initialize physics world

Start any simulation

add_rigid_body

Add objects (box, sphere, capsule, etc.)

Build scene

step_simulation

Advance time

Run physics

record_trajectory

Capture motion for R3F/Remotion

Generate animation data

destroy_simulation

Cleanup resources

End simulation

Characteristics:

  • 🦀 Requires Rapier service

  • 🔄 Stateful (track simulation ID)

  • 🧩 Composable (combine for complex scenarios)

  • 💪 Full rigid-body dynamics

Typical workflow:

# 1. Create world sim = create_simulation(gravity_y=-9.81) # 2. Add objects add_rigid_body(sim.sim_id, "ground", type="static", shape="plane") add_rigid_body(sim.sim_id, "ball", type="dynamic", shape="sphere", radius=0.5, position=[0, 5, 0]) # 3. Run simulation step_simulation(sim.sim_id, steps=300) # 4. Record for visualization trajectory = record_trajectory(sim.sim_id, "ball", steps=300) # 5. Cleanup destroy_simulation(sim.sim_id)

📋 Complete Tool Reference

Basic Mechanics (8 tools)

Tool

Purpose

Example

calculate_projectile_motion

Ballistic trajectories

"How far does a cannonball travel?"

check_collision

Predict sphere collisions

"Will these asteroids hit?"

calculate_force

F = ma calculations

"What force accelerates this car?"

calculate_kinetic_energy

KE = ½mv²

"Energy in moving object?"

calculate_momentum

p = mv

"Momentum of moving object?"

calculate_potential_energy

PE = mgh

"Energy at height?"

calculate_work_power

Work (F·d) and power (W/t)

"Work done lifting object?"

calculate_elastic_collision

1D elastic collision

"Pool ball velocities after impact?"

Fluid Dynamics (10 tools)

Tool

Purpose

Example

calculate_drag_force

Air/water resistance

"Drag on car at speed?"

calculate_buoyancy

Will it float? (Archimedes)

"Does steel ball float?"

calculate_terminal_velocity

Maximum fall speed

"Skydiver terminal velocity?"

simulate_underwater_motion

Underwater trajectory

"How far does torpedo travel?"

calculate_lift_force

Aerodynamic lift

"Lift on aircraft wing?"

calculate_magnus_force

Force on spinning ball

"Why does curveball curve?"

calculate_bernoulli

Pressure in flowing fluid

"Pressure in pipe constriction?"

calculate_pressure_at_depth

Hydrostatic pressure

"Pressure at 30m depth?"

calculate_reynolds_number

Flow regime classification

"Is flow turbulent?"

calculate_venturi_effect

Flow through constriction

"Velocity in throat?"

Rotational Dynamics (5 tools)

Tool

Purpose

Example

calculate_torque

τ = r × F (cross product)

"Torque from wrench?"

calculate_moment_of_inertia

Rotational inertia

"MOI of spinning disk?"

calculate_angular_momentum

L = Iω

"Angular momentum of wheel?"

calculate_rotational_kinetic_energy

Rotational KE = ½Iω²

"Energy in flywheel?"

calculate_angular_acceleration

α = τ/I

"How fast does it spin up?"

Oscillations & Waves (5 tools)

Tool

Purpose

Example

calculate_hookes_law

Spring force F = -kx

"Force in compressed spring?"

calculate_spring_mass_period

Oscillation period

"How fast does mass oscillate?"

calculate_simple_harmonic_motion

Position at time t

"Where is mass at t=2s?"

calculate_damped_oscillation

Motion with damping

"How quickly does it settle?"

calculate_pendulum_period

Pendulum swing time

"Period of 1m pendulum?"

Circular Motion & Orbits (5 tools)

Tool

Purpose

Example

calculate_centripetal_force

F_c = mv²/r

"Force for circular motion?"

calculate_orbital_period

Kepler's 3rd law

"Satellite orbital period?"

calculate_banking_angle

Optimal curve angle

"Banking for highway curve?"

calculate_escape_velocity

Escape from gravity

"Earth escape velocity?"

analyze_circular_orbit

Complete orbital analysis

"Analyze ISS orbit?"

Statics & Equilibrium (7 tools)

Tool

Purpose

Example

check_force_balance

Verify ΣF = 0

"Are forces balanced?"

check_torque_balance

Verify Στ = 0

"Will seesaw balance?"

calculate_center_of_mass

Balance point

"Where is center of mass?"

calculate_static_friction

Max friction force

"Will object slip?"

calculate_normal_force

Force on incline

"Normal force on ramp?"

check_equilibrium

Force + torque balance

"Is structure stable?"

calculate_beam_reactions

Support forces

"Reaction forces on beam?"

Kinematics Analysis (7 tools)

Tool

Purpose

Example

calculate_acceleration_from_position

Derive from position data

"Acceleration from motion capture?"

calculate_jerk

Rate of acceleration change

"How jerky is motion?"

fit_trajectory

Find trajectory equation

"Fit parabola to data?"

generate_motion_graph

Position/velocity/accel graphs

"Generate motion graphs?"

calculate_average_speed

Speed along path

"Average speed on route?"

calculate_instantaneous_velocity

Velocity at exact time

"Speed at t=2.5s?"

calculate_projectile_with_drag

Realistic projectile with air resistance

"How far does baseball actually go?"

Advanced Collisions (2 tools)

Tool

Purpose

Example

calculate_elastic_collision_3d

3D perfect collision

"Pool balls in 3D?"

calculate_inelastic_collision_3d

3D collision with energy loss

"Car crash analysis?"

Conservation Laws (4 tools)

Tool

Purpose

Example

check_energy_conservation

Verify energy conserved

"Is collision realistic?"

check_momentum_conservation

Verify momentum conserved

"Is momentum preserved?"

check_angular_momentum_conservation

Verify L conserved

"Is rotation valid?"

track_energy_dissipation

Energy loss over time

"Where did energy go?"

Unit Conversions (2 tools)

Tool

Purpose

Supported Units

convert_unit

Convert between units

Velocity: m/s, km/h, mph, ft/s, knots

Distance: m, km, mi, ft, yd, in

Mass: kg, g, lb, oz

Force: N, kN, lbf

Energy: J, kJ, cal, BTU, kWh

Power: W, kW, hp

Temperature: K, C, F

Angle: rad, deg

Pressure: Pa, kPa, bar, psi, atm

Area: m², km², ft², acre

Volume: m³, L, gal, ft³

Time: s, min, hr, day

Acceleration: m/s², g, ft/s²

Torque: N·m, lb·ft, lb·in

Frequency: Hz, kHz, MHz, GHz

Data Size: B, KB, MB, GB

list_unit_conversions

Get all supported units

Returns complete list of conversions

Examples:

# Natural language queries work perfectly "Convert 60 mph to m/s" # → 26.82 m/s "How fast is 100 km/h in mph?" # → 62.14 mph "What's 10 kg in pounds?" # → 22.05 lb "Convert 100 feet to meters" # → 30.48 m "What's 98.6°F in Celsius?" # → 37°C "Convert 3 g-force to m/s²" # → 29.42 m/s² "What's 300 N·m in lb·ft?" # → 221.27 lb·ft "Convert 1 hour to seconds" # → 3600 s

Features:

  • ⚡ Instant conversions (no external service needed)

  • 🔄 Automatic indirect conversions (e.g., mph → km/h via m/s)

  • 📐 70+ unit types across 16 categories

  • 🎯 Perfect for natural language physics queries

  • 🚀 Includes engineering units (torque, acceleration, frequency)

Common Drag Coefficients (Cd) Reference

For use with calculate_projectile_with_drag tool:

Object

Drag Coefficient (Cd)

Notes

Sports Balls

Baseball

0.4

Stitched surface

Golf ball (dimpled)

0.25

Dimples reduce drag by ~50%

Golf ball (smooth)

0.47

Without dimples (don't use!)

Basketball

0.55

Large, textured surface

Soccer ball

0.25

Modern, smooth panels

Tennis ball

0.55

Fuzzy surface

Football (American)

0.05-0.15

Highly streamlined, orientation-dependent

Generic Shapes

Sphere (smooth)

0.47

Default reference

Flat plate (perpendicular)

1.28

Maximum drag

Streamlined body

0.04

Teardrop/airfoil

Cylinder (perpendicular)

1.15

Like a pole

Vehicles

Car (modern)

0.25-0.35

Aerodynamic design

Truck

0.6-0.9

Boxy shape

Bicycle + rider

0.9

Upright position

Human Body

Skydiver (belly-down)

1.0-1.3

Maximum drag

Skydiver (head-down)

0.7

Streamlined

Projectiles

Bullet (supersonic)

0.295

Pointed nose

Artillery shell

0.15-0.25

Streamlined

Basic Usage Example:

# Baseball pitch with realistic drag result = await calculate_projectile_with_drag( initial_velocity=40.23, # 90 mph angle_degrees=10, mass=0.145, cross_sectional_area=0.0043, # π × (0.037m)² drag_coefficient=0.4 # Baseball Cd )

Advanced Projectile Features

The calculate_projectile_with_drag tool supports optional enhancements for ultra-realistic simulations:

🌀 Magnus Force (Spin Effects)

Spin creates a pressure differential that deflects the ball's path. Essential for:

  • Baseball: Curveballs (topspin drops), fastballs (backspin lifts)

  • Golf: Backspin increases carry, sidespin causes slices/hooks

  • Soccer: Bending free kicks around defensive walls

  • Tennis: Topspin brings ball down faster

# Baseball curveball with topspin result = await calculate_projectile_with_drag( initial_velocity=35, angle_degrees=0, mass=0.145, cross_sectional_area=0.0043, drag_coefficient=0.4, spin_rate=261.8, # 2500 rpm = 261.8 rad/s spin_axis=[0, 0, -1] # Topspin (negative z-axis) ) # Returns lateral_deflection and magnus_force_max

Spin Parameters:

  • spin_rate: Rotation speed in rad/s (convert from RPM: rpm × 2π/60)

  • spin_axis: Unit vector [x, y, z] indicating spin direction

    • [0, 0, 1] = Backspin (lifts)

    • [0, 0, -1] = Topspin (drops)

    • [0, 1, 0] = Sidespin (hooks/slices)

💨 Wind Effects

Constant wind vector affects trajectory throughout flight:

# Soccer free kick with 5 m/s crosswind result = await calculate_projectile_with_drag( initial_velocity=28, angle_degrees=12, mass=0.43, cross_sectional_area=0.0388, drag_coefficient=0.25, wind_velocity=[5.0, 0.0] # [horizontal, vertical] in m/s ) # Returns wind_drift showing total deflection

Wind Types:

  • Tailwind: [+X, 0] - increases range

  • Headwind: [-X, 0] - decreases range

  • Crosswind: [X, 0] - lateral deflection

  • Updraft: [0, +Y] - increases height and flight time

  • Downdraft: [0, -Y] - decreases height

🏔️ Altitude & Temperature Effects

Air density varies with elevation and temperature, dramatically affecting drag:

# Golf drive in Denver (1600m elevation, 20°C) result = await calculate_projectile_with_drag( initial_velocity=70, angle_degrees=12, mass=0.0459, cross_sectional_area=0.00143, drag_coefficient=0.25, altitude=1600, # meters above sea level temperature=20 # Celsius ) # Returns effective_air_density showing actual density used

Real-World Impact:

  • Denver (1600m): ~10% longer drives than sea level

  • Hot day (+20°C): ~2-3% less drag than cold day

  • Everest Base Camp (5300m): ~50% less air density!

Air Density Formula:

ρ(h,T) = ρ₀ × exp(-Mgh/RT₀) × (T₀/T)

Where:

  • ρ₀ = sea level density (1.225 kg/m³)

  • h = altitude (meters)

  • T = temperature (Kelvin)

  • M = molar mass of air (0.029 kg/mol)

  • g = gravity (9.81 m/s²)

  • R = gas constant (8.314 J/(mol·K))

🌟 Combined Effects Example

# Golf ball with ALL effects (spin + wind + altitude) result = await calculate_projectile_with_drag( initial_velocity=70, angle_degrees=12, mass=0.0459, cross_sectional_area=0.00143, drag_coefficient=0.25, spin_rate=200, # Backspin spin_axis=[0, 0, 1], wind_velocity=[3, 0], # Tailwind altitude=1000, # Moderate elevation temperature=25 # Warm day ) # All effects combine for maximum realism!

See Examples:

  • examples/sports_projectiles_with_drag.py - Basic drag effects

  • examples/advanced_projectile_effects.py - Magnus force, wind, altitude

🔄 Orientation-Dependent Drag (Rapier Simulations)

For tumbling objects like footballs, frisbees, and javelins, drag varies dramatically based on orientation. A football in a perfect spiral has 3-6× less drag than when tumbling end-over-end!

Available via Rapier rigid-body simulations using the add_rigid_body tool with orientation-dependent drag parameters.

How It Works

Objects moving through air experience drag that depends on their orientation:

  • Football spiral: Streamlined along flight path → low drag (~0.1 Cd)

  • Football tumbling: Broadside to airflow → high drag (~0.6 Cd)

  • Frisbee flat: Minimal cross-section → low drag (~0.08 Cd)

  • Frisbee tilted: Larger cross-section → higher drag

New

drag_coefficient: float # Base Cd value drag_area: float # Reference cross-sectional area (m²) drag_axis_ratios: [x, y, z] # Drag variation along body axes fluid_density: float # Fluid density (air=1.225, water=1000)

Example: Football Spiral vs Tumble

# Perfect spiral (low drag along Y-axis) await add_rigid_body( sim_id, id="spiral", shape="capsule", size=[0.17, 0.28], # diameter, length mass=0.42, position=[0, 2, 0], velocity=[vx, vy, 0], angular_velocity=[0, 126, 0], # 20 rev/s spin # Orientation-dependent drag drag_coefficient=0.1, drag_area=0.023, # End-on area drag_axis_ratios=[1.0, 0.2, 1.0], # 5× less drag along Y fluid_density=1.225 ) # Tumbling (higher drag, averaging all orientations) await add_rigid_body( sim_id, id="tumble", shape="capsule", size=[0.17, 0.28], mass=0.42, position=[0, 2, 0], velocity=[vx, vy, 0], angular_velocity=[31.4, 0, 0], # Tumbling rotation # Orientation-dependent drag drag_coefficient=0.6, # Higher base Cd drag_area=0.048, # Broadside area drag_axis_ratios=[0.8, 1.0, 0.8], # Less streamlining fluid_density=1.225 )

Result: Spiral can travel 20-40% farther than tumble!

Common drag_axis_ratios Patterns

The drag_axis_ratios parameter specifies how drag varies along each body-local axis [X, Y, Z]:

Object

Ratios

Streamlined Axis

Use Case

Football spiral

[1.0, 0.2, 1.0]

Y (length)

Perfect pass

Javelin

[1.5, 0.2, 1.5]

Y (length)

Optimal flight

Frisbee flat

[1.0, 0.1, 1.0]

Y (vertical)

Stable throw

Sphere

[1.0, 1.0, 1.0]

None

Basketball, etc.

Disc tumbling

[0.8, 1.0, 0.8]

Less variation

Wobbly throw

Physical Meaning:

  • 0.2 = 20% of base drag along that axis (very streamlined)

  • 1.0 = 100% of base drag (normal)

  • 1.5 = 150% of base drag (higher resistance)

Real-World Examples

⚽ Football Throw (spiral vs tumble):

# Spiral: 45-50 yards typical # Tumble: 30-35 yards (30-40% loss)

🥏 Frisbee (stable vs wobbling):

# Stable (600 rpm spin): 60-80 meters # Wobbling (slow spin): 30-40 meters (50% loss)

🏹 Javelin (optimal vs poor technique):

# Optimal angle: 70-90 meters (Olympic level) # Poor release: 40-50 meters (45% loss)

Important Notes

⚠️ Requires Rapier Service: Orientation-dependent drag calculations are performed by the Rapier physics service (Rust implementation). The Python MCP server defines the API and passes parameters to Rapier.

🎯 When to Use:

  • Sports simulations (football, frisbee, discus)

  • Projectile accuracy (javelin, arrows, darts)

  • Aerospace applications (rocket tumbling, debris)

🔬 Physics: The drag force is calculated in the Rapier service using the body's current orientation (quaternion) to transform body-local drag coefficients into world-space drag forces.

Hybrid Drag Implementation: Rapier uses a hybrid approach to handle extreme drag cases:

  • Normal drag (ratio < 2.0): Force-based orientation-dependent drag with full anisotropic behavior

  • Extreme drag (ratio ≥ 2.0): Damping-based drag for stability when drag-to-weight ratio is very high

    • Automatically activates for objects like ping pong balls (high drag, low mass)

    • Prevents numerical instabilities while maintaining realistic energy dissipation

    • Logged as INFO when triggered: "Body 'name' has extreme drag (ratio=X.XX), using damping"

Where drag_ratio = 0.5 * fluid_density * drag_coefficient * drag_area * v_typical^2 / (mass * g)

Measurement Notes: When analyzing trajectories, use max(x_positions) instead of final_x to measure range. Rapier's solver may occasionally jitter backward slightly near ground impact, but this is a measurement artifact, not a physics error. The drag forces always oppose motion correctly.

See Example:

  • examples/tumbling_projectiles.py - Football, frisbee, and javelin orientation effects

✨ Phase 1 Features (Production Ready)

All Phase 1 features are complete, tested (98% coverage), and deployed to production!

Phase 1.1: Bounce Detection 🏀

Automatically detect and analyze bounces in ball trajectories with energy loss calculations.

What it does:

  • Detects bounce events from trajectory data (velocity reversals near ground)

  • Calculates energy loss percentage for each bounce

  • Provides before/after velocities and heights

  • Perfect for answering "how many bounces?" and "when does it stop?"

Tool: record_trajectory_with_events

Example:

# Record a bouncing ball traj = await record_trajectory_with_events( sim_id=sim_id, body_id="ball", steps=300, detect_bounces=True, bounce_height_threshold=0.01 # 1cm = "on ground" ) print(f"Detected {len(traj.bounces)} bounces") for bounce in traj.bounces: print(f"Bounce #{bounce.bounce_number}:") print(f" Time: {bounce.time:.2f}s") print(f" Height: {bounce.height_at_bounce:.3f}m") print(f" Energy loss: {bounce.energy_loss_percent:.1f}%") print(f" Speed before: {bounce.speed_before:.2f} m/s") print(f" Speed after: {bounce.speed_after:.2f} m/s")

Output:

Detected 5 bounces Bounce #1: Time: 1.43s, Height: 0.00m, Energy loss: 36.0%, Speed: 14.0→9.0 m/s Bounce #2: Time: 2.51s, Height: 0.00m, Energy loss: 36.0%, Speed: 8.9→5.7 m/s Bounce #3: Time: 3.23s, Height: 0.00m, Energy loss: 36.0%, Speed: 5.7→3.6 m/s ...

Use Cases:

  • Sports analytics (basketball arc, tennis serve bounces)

  • Product testing (phone drop tests, durability simulations)

  • Game development (realistic ball physics)

  • Education (demonstrate energy conservation)

See: examples/06_bounce_detection.py for full demo

Phase 1.2: Contact Events 📊

Real-time collision tracking with detailed contact information from the physics engine.

What it does:

  • Tracks all contact events between bodies during simulation

  • Reports contact start, ongoing, and end events

  • Provides impulse magnitudes, normals, and relative velocities

  • Essential for collision analysis and force calculations

Included in: All trajectory recordings (record_trajectory, record_trajectory_with_events)

Contact Event Data:

ContactEvent( time=1.43, # When contact occurred body_a="ball", # First body body_b="ground", # Second body contact_point=[0.0, 0.05, 0.0], # World space position normal=[0.0, 1.0, 0.0], # Contact normal (from A to B) impulse_magnitude=14.2, # Collision impulse (N⋅s) relative_velocity=[0.0, -14.0, 0.0], # Relative velocity event_type="started" # "started", "ongoing", or "ended" )

Example:

traj = await record_trajectory(sim_id, "ball", steps=300) # Analyze contacts for event in traj.contact_events: if event.event_type == "started": print(f"Collision at t={event.time:.2f}s") print(f" Bodies: {event.body_a} ↔ {event.body_b}") print(f" Impulse: {event.impulse_magnitude:.1f} N⋅s") print(f" Impact speed: {abs(event.relative_velocity[1]):.1f} m/s")

Use Cases:

  • Collision analysis (car crashes, sports impacts)

  • Force calculations (derive forces from impulses)

  • Interaction tracking (which objects touched what)

  • VFX triggers (spark effects on collisions)

See: examples/07_contact_events.py for full demo

Phase 1.3: Joints & Constraints 🔗

Connect rigid bodies with realistic joints for complex mechanical systems.

What it does:

  • Create constraints between bodies (hinges, sliders, ball-and-socket, fixed)

  • Build complex systems (pendulums, chains, ragdolls, machinery)

  • Realistic mechanical motion (doors, wheels, linkages)

  • Perfect for simulating articulated structures

Tool: add_joint

Joint Types:

Type

Description

Example Uses

FIXED

Rigid connection (glue)

Attach hat to head, weld joints

REVOLUTE

Hinge rotation around axis

Doors, pendulums, wheels

SPHERICAL

Ball-and-socket rotation

Ragdoll shoulders, gimbal mounts

PRISMATIC

Sliding along axis

Pistons, elevators, sliders

Example - Simple Pendulum:

# Create anchor point await add_rigid_body( sim_id=sim_id, body_id="anchor", body_type="static", shape="sphere", size=[0.05], position=[0.0, 3.0, 0.0] ) # Create pendulum bob await add_rigid_body( sim_id=sim_id, body_id="bob", body_type="dynamic", shape="sphere", size=[0.2], mass=1.0, position=[1.5, 1.5, 0.0] # Start displaced ) # Connect with revolute joint (hinge) await add_joint( sim_id=sim_id, joint=JointDefinition( id="hinge", joint_type=JointType.REVOLUTE, body_a="anchor", body_b="bob", anchor_a=[0.0, 0.0, 0.0], # Center of anchor anchor_b=[0.0, 0.2, 0.0], # Top of bob axis=[0.0, 0.0, 1.0] # Rotate around Z-axis ) ) # Simulate and see realistic pendulum motion! traj = await record_trajectory(sim_id, "bob", steps=300)

Example - Multi-Link Chain:

# Create anchor await add_rigid_body(sim_id, "anchor", body_type="static", ...) # Create 3 chain links for i in range(3): await add_rigid_body( sim_id, f"link{i}", body_type="dynamic", shape="box", size=[0.1, 0.4, 0.1], position=[0.0, 2.5 - i*0.5, 0.0] ) # Connect with spherical joints (ball-and-socket) await add_joint(sim_id, JointDefinition( id="joint0", joint_type=JointType.SPHERICAL, body_a="anchor", body_b="link0", anchor_a=[0.0, 0.0, 0.0], anchor_b=[0.0, 0.2, 0.0] )) await add_joint(sim_id, JointDefinition( id="joint1", joint_type=JointType.SPHERICAL, body_a="link0", body_b="link1", anchor_a=[0.0, -0.2, 0.0], anchor_b=[0.0, 0.2, 0.0] )) # ... and so on

Use Cases:

  • Mechanical systems (engines, gears, levers)

  • Character animation (ragdolls, inverse kinematics)

  • Vehicle suspension (wheels, shocks)

  • Architectural simulations (doors, drawbridges)

See: examples/08_pendulum.py for full demo

Phase 1.4: Damping & Advanced Controls 🌬️

Realistic energy dissipation through linear and angular damping.

What it does:

  • Simulates air resistance (linear damping)

  • Simulates rotational friction (angular damping)

  • Makes simulations more realistic and stable

  • Perfect for settling physics and reducing "floaty" motion

Parameters: Added to add_rigid_body tool

Damping Parameters:

await add_rigid_body( sim_id=sim_id, body_id="damped_ball", body_type="dynamic", shape="sphere", size=[0.5], mass=1.0, position=[0.0, 5.0, 0.0], # Phase 1.4: Damping linear_damping=0.5, # 0.0 (none) to 1.0 (high) - like air resistance angular_damping=0.3 # 0.0 (none) to 1.0 (high) - like rotational friction )

Effect of Linear Damping:

  • 0.0 = No air resistance (vacuum physics)

  • 0.1-0.3 = Light damping (tennis ball in air)

  • 0.5-0.7 = Moderate damping (underwater motion)

  • 0.9+ = Heavy damping (very viscous fluid)

Effect of Angular Damping:

  • 0.0 = Spins forever (vacuum)

  • 0.1-0.3 = Realistic friction (rolling ball)

  • 0.5-0.7 = High friction (rough surface)

  • 0.9+ = Almost no rotation (sticky surface)

Comparison:

# Without damping - bounces forever await add_rigid_body(..., linear_damping=0.0) # Result: Ball bounces 20+ times, takes 30+ seconds to settle # With damping - realistic settling await add_rigid_body(..., linear_damping=0.5) # Result: Ball bounces 5 times, settles in ~5 seconds

Use Cases:

  • Realistic object motion (not "floaty" game physics)

  • Faster settling (less simulation time needed)

  • Underwater simulations (high damping)

  • Space simulations (zero damping)

See: examples/09_phase1_complete.py for all Phase 1 features combined

Phase 1.5: Fluid Dynamics 🌊

Analytical fluid calculations for drag, buoyancy, and underwater motion.

What it does:

  • Calculates drag forces (quadratic air/water resistance)

  • Computes buoyancy using Archimedes' principle

  • Determines terminal velocity for falling objects

  • Simulates underwater projectile motion with drag and buoyancy

Tools Available:

1. calculate_drag_force - Air/Water Resistance

Calculate the force opposing motion through a fluid.

# Ball falling through water result = await calculate_drag_force( velocity=[0, -5.0, 0], # 5 m/s downward cross_sectional_area=0.00785, # π*r² for 10cm diameter fluid_density=1000, # water (air=1.225) drag_coefficient=0.47, # sphere (streamlined=0.04) viscosity=1.002e-3 # optional: water viscosity for accurate Re ) print(f"Drag force: {result['magnitude']:.1f} N (upward)") print(f"Reynolds number: {result['reynolds_number']:.0f}")

Common drag coefficients:

  • Sphere: 0.47

  • Streamlined (torpedo): 0.04

  • Flat plate: 1.28

  • Human (standing): 1.0-1.3

  • Car: 0.25-0.35

Optional viscosity parameter (for accurate Reynolds number):

  • Water at 20°C: 1.002e-3 Pa·s

  • Air at 20°C: 1.825e-5 Pa·s

  • Motor oil: 0.1 Pa·s

  • If omitted, estimated from density (water-like if >100 kg/m³, else air-like)

2. calculate_buoyancy - Will it Float?

Determine buoyant force and whether objects float or sink.

# Check if 1kg steel ball floats volume = (4/3) * π * (0.05)**3 # 10cm diameter sphere result = await calculate_buoyancy( volume=0.000524, # m³ fluid_density=1000 # water ) weight = 1.0 * 9.81 # 9.81 N buoyancy = result['buoyant_force'] # 5.14 N # weight > buoyancy → SINKS

3. calculate_terminal_velocity - Maximum Fall Speed

Calculate the speed where drag equals weight.

# Skydiver terminal velocity result = await calculate_terminal_velocity( mass=70, # kg cross_sectional_area=0.7, # m² (belly-down) fluid_density=1.225, # air drag_coefficient=1.0 # human ) print(f"Terminal velocity: {result['terminal_velocity']:.1f} m/s") # Result: ~40 m/s (90 mph) print(f"Time to 95%: {result['time_to_95_percent']:.1f}s")

4. simulate_underwater_motion - Full Fluid Simulation

Simulate motion through fluids with drag and buoyancy forces.

# Torpedo launched underwater result = await simulate_underwater_motion( initial_velocity=[20, 0, 0], # 20 m/s forward mass=100, # kg volume=0.05, # m³ cross_sectional_area=0.03, # m² fluid_density=1000, # water drag_coefficient=0.04, # streamlined duration=30.0 ) print(f"Distance traveled: {result['total_distance']:.1f}m") print(f"Final velocity: {result['final_velocity']}") print(f"Max depth: {result['max_depth']:.1f}m")

Use Cases:

  • Marine engineering: Torpedo trajectories, submarine drag

  • Aerospace: Skydiving, parachute descent, atmospheric re-entry

  • Sports: Swimming, diving, underwater ballistics

  • Product design: Drag optimization, floatation devices

  • Environmental: Particle settling, pollutant dispersion

Physics Models:

  • Quadratic drag: F_drag = 0.5 * ρ * v² * C_d * A

  • Buoyancy: F_b = ρ_fluid * V * g (Archimedes)

  • Terminal velocity: v_t = √(2mg / ρC_dA)

  • Numerical integration for complex underwater motion

See: examples/10_fluid_dynamics.py for comprehensive demonstrations

🎉 Phase 1 Complete Summary

Status: ✅ All features production-ready

Feature

Status

Tool

Coverage

Bounce Detection

✅ Shipped

record_trajectory_with_events

100%

Contact Events

✅ Shipped

All trajectory tools

100%

Joints & Constraints

✅ Shipped

add_joint

100%

Damping Controls

✅ Shipped

add_rigid_body

100%

Fluid Dynamics

✅ Shipped

calculate_drag_force, calculate_buoyancy, calculate_terminal_velocity, simulate_underwater_motion

100%

Test Coverage: 98% (350 tests passing)

Deployment:

Examples: See examples/06_bounce_detection.py through examples/10_fluid_dynamics.py

🚀 Phase 2 Features (Production Ready)

All Phase 2 features are complete, tested (98% coverage), and deployed to production!

Phase 2.1: Rotational Dynamics 🔄

Complete rotational motion calculations including torque, moment of inertia, angular momentum, and rotational kinetic energy.

Tools Available:

Tool

Description

Example Use

calculate_torque

Calculate torque from force and position (τ = r × F)

"What torque does this wrench apply?"

calculate_moment_of_inertia

Moment of inertia for common shapes (disk, sphere, rod, etc.)

"What's the rotational inertia?"

calculate_angular_momentum

Angular momentum (L = Iω)

"How much rotational momentum?"

calculate_rotational_kinetic_energy

Rotational KE (½Iω²)

"Energy in spinning flywheel?"

calculate_angular_acceleration

Angular acceleration (α = τ/I)

"How fast does it spin up?"

Example - Calculate Torque:

result = await calculate_torque( force_x=50.0, force_y=0.0, force_z=0.0, position_x=0.0, position_y=0.0, position_z=0.8 # 80cm wrench ) # torque magnitude = 40 N⋅m

Use Cases:

  • Mechanical engineering (gear systems, engines)

  • Robotics (joint torques, motor sizing)

  • Sports science (bat swings, golf clubs)

  • Aerospace (satellite attitude control)

Phase 2.2: Oscillations & Waves 🌊

Harmonic motion and spring systems with damping effects.

Tools Available:

Tool

Description

Example Use

calculate_hookes_law

Spring force and potential energy (F = -kx)

"How much force in compressed spring?"

calculate_spring_mass_period

Period and frequency of spring-mass system

"How fast does it oscillate?"

calculate_simple_harmonic_motion

Position, velocity, acceleration at time t

"Where is the mass at t=2s?"

calculate_damped_oscillation

Damped harmonic motion (underdamped, critically damped, overdamped)

"How quickly does it settle?"

calculate_pendulum_period

Period of simple pendulum

"How long is one swing?"

Example - Spring-Mass System:

result = await calculate_spring_mass_period( mass=0.5, # 500g mass spring_constant=20.0 # N/m ) # period ≈ 0.99s, frequency ≈ 1.01 Hz

Use Cases:

  • Mechanical design (suspension systems, vibration isolation)

  • Seismology (earthquake oscillations)

  • Electronics (LC circuits, resonance)

  • Horology (pendulum clocks)

Phase 2.3: Circular Motion & Orbits 🌍

Circular motion, orbital mechanics, and centripetal forces.

Tools Available:

Tool

Description

Example Use

calculate_centripetal_force

Force required for circular motion

"What force keeps car on curve?"

calculate_orbital_period

Period and velocity for circular orbit

"How long is satellite orbit?"

calculate_banking_angle

Optimal banking for curved road

"What angle for this turn?"

calculate_escape_velocity

Minimum velocity to escape gravity

"Can rocket escape Earth?"

analyze_circular_orbit

Complete orbital analysis (altitude, period, velocity)

"Analyze ISS orbit"

Example - Satellite Orbit:

result = await analyze_circular_orbit( altitude=400000.0, # 400 km above surface planet_mass=5.972e24, # Earth mass planet_radius=6.371e6 # Earth radius ) # orbital_velocity ≈ 7670 m/s # period ≈ 5530 seconds (92 minutes)

Use Cases:

  • Space missions (orbital calculations, satellite deployment)

  • Astrophysics (planetary motion, binary stars)

  • Transportation (highway curve design)

  • Amusement parks (loop-the-loop, centrifuges)

Phase 2.4: Advanced Collisions 💥

3D collision calculations with elastic and inelastic collisions.

Tools Available:

Tool

Description

Example Use

calculate_elastic_collision_3d

3D elastic collision (energy conserved)

"Pool ball collisions in 3D"

calculate_inelastic_collision_3d

3D inelastic collision with restitution

"Car crash with energy loss"

Example - Car Crash:

result = await calculate_inelastic_collision_3d( mass1=1500.0, velocity1=[20.0, 0.0, 0.0], mass2=1200.0, velocity2=[-15.0, 0.0, 0.0], coefficient_of_restitution=0.0 # Perfectly inelastic ) # final_velocity1 = [1.11, 0, 0] # final_velocity2 = [1.11, 0, 0] # Stick together # energy_loss > 0 (deformation energy)

Phase 2.5: Conservation Laws ⚖️

Verify and track conservation of energy, momentum, and angular momentum.

Tools Available:

Tool

Description

Example Use

check_energy_conservation

Verify total energy is conserved

"Is this collision realistic?"

check_momentum_conservation

Verify momentum is conserved

"Does this violate physics?"

check_angular_momentum_conservation

Verify angular momentum conserved

"Is rotation energy conserved?"

track_energy_dissipation

Track energy loss over trajectory

"Where did the energy go?"

Example - Validate Collision:

result = await check_energy_conservation( initial_kinetic_energy=100.0, final_kinetic_energy=50.0, initial_potential_energy=0.0, final_potential_energy=50.0 ) # is_conserved = True (100 = 50 + 50) # energy_difference ≈ 0

Phase 2.6: Statics & Equilibrium ⚖️

Static equilibrium analysis for structures and forces.

Tools Available:

Tool

Description

Example Use

check_force_balance

Verify ΣF = 0 (force equilibrium)

"Are these forces balanced?"

check_torque_balance

Verify Στ = 0 (torque equilibrium)

"Will this seesaw balance?"

calculate_center_of_mass

Find center of mass for system

"Where is the balance point?"

calculate_static_friction

Maximum friction force, will object slip?

"Will box slide down ramp?"

calculate_normal_force

Normal force on inclined plane

"What force on ramp?"

check_equilibrium

Complete equilibrium check (force + torque)

"Is structure stable?"

calculate_beam_reactions

Reaction forces for simply supported beam

"What are support forces?"

Example - Beam Analysis:

result = await calculate_beam_reactions( beam_length=10.0, loads=[1000, 500], # Two point loads load_positions=[3.0, 7.0] # Positions along beam ) # reaction_left = 800 N # reaction_right = 700 N # is_balanced = True

Use Cases:

  • Structural engineering (bridges, buildings)

  • Mechanical design (levers, balances)

  • Architecture (load analysis)

  • Safety analysis (stability checks)

Phase 2.7: Kinematics Analysis 📊

Analyze motion data to extract velocities, accelerations, and trajectories.

Tools Available:

Tool

Description

Example Use

calculate_acceleration_from_position

Derive velocity and acceleration from position data

"Analyze motion capture data"

calculate_jerk

Calculate jerk (rate of change of acceleration)

"How jerky is this motion?"

fit_trajectory

Fit polynomial to trajectory (linear, quadratic, cubic)

"Find trajectory equation"

generate_motion_graph

Generate position/velocity/acceleration graphs

"Visualize kinematics"

calculate_average_speed

Average speed along path

"What's average speed?"

calculate_instantaneous_velocity

Velocity at specific time with interpolation

"Speed at exact moment?"

Example - Motion Analysis:

result = await calculate_acceleration_from_position( times=[0, 1, 2, 3, 4], positions=[[0,0,0], [5,0,0], [10,0,0], [15,0,0], [20,0,0]] ) # velocities = [[5,0,0], [5,0,0], ...] # Constant 5 m/s # average_acceleration ≈ [0,0,0] # No acceleration

Use Cases:

  • Motion capture analysis (sports, biomechanics)

  • Robotics (trajectory planning, motion smoothness)

  • Autonomous vehicles (trajectory optimization)

  • Scientific research (particle tracking)

Phase 2.8: Advanced Fluid Dynamics 💨

Extended fluid calculations including lift, Magnus force, Bernoulli, and viscous flow.

Tools Available:

Tool

Description

Example Use

calculate_lift_force

Aerodynamic lift (L = ½ρv²C_LA)

"What lift on wing?"

calculate_magnus_force

Force on spinning ball

"Why does curveball curve?"

calculate_bernoulli

Bernoulli's equation for flowing fluids

"Pressure in pipe constriction?"

calculate_pressure_at_depth

Hydrostatic pressure

"Pressure at 30m depth?"

calculate_reynolds_number

Flow regime (laminar/turbulent)

"Is flow turbulent?"

calculate_venturi_effect

Flow through constriction

"Velocity in throat?"

Example - Aircraft Wing:

result = await calculate_lift_force( velocity=70, # m/s (~250 km/h) wing_area=20.0, # m² lift_coefficient=1.2, fluid_density=1.225 # air ) # lift_force ≈ 73,500 N

Use Cases:

  • Aerospace engineering (aircraft design, aerodynamics)

  • Marine engineering (hull design, submarine motion)

  • Sports science (ball trajectories, swimming efficiency)

  • HVAC design (airflow optimization)

🎉 Phase 2 Complete Summary

Status: ✅ All features production-ready

Feature Area

Tools

Coverage

Rotational Dynamics

5 tools

100%

Oscillations

5 tools

100%

Circular Motion

5 tools

100%

Advanced Collisions

2 tools

100%

Conservation Laws

4 tools

100%

Statics

7 tools

100%

Kinematics Analysis

6 tools

100%

Advanced Fluids

6 tools

100%

Total Tools: 79 tools across all categories Test Coverage: 98% overall (350 tests passing)

Next Up: Phase 3 - Performance Optimization & Visualization

  • Batch simulation API for ML training data

  • Parameter sweep utilities

  • Enhanced visualization exports

  • Performance profiling and optimization

🎓 Example Conversations

Projectile Motion

User: A golf ball is hit at 70 m/s at 15 degrees. How far does it go and what's the flight time? LLM: [calls calculate_projectile_motion(70, 15)] Range ≈ 249.7 m Time of flight ≈ 3.694 s Maximum height ≈ 16.73 m Here are 50 trajectory points for visualization...
User: What angle gives maximum range for a cannonball fired at 100 m/s? LLM: [calls calculate_projectile_motion multiple times with different angles] The optimal angle is 45°, which gives: - Maximum range: 1019.4 m - Flight time: 14.4 s - Peak height: 254.8 m

Collision Detection

User: Two asteroids: one at (0,0,0) moving at 1000 m/s in x direction, another at (50000, 100, 0) moving at -800 m/s in x. Will they collide? LLM: [calls check_collision with both objects] Yes, they will collide! - Collision time: ~27.8 seconds - Impact location: (27,778, 100, 0) - Impact speed: 1,800 m/s - This would be a devastating impact given the closing speed.
User: Two cars 500m apart, one at 60 mph, other at 45 mph heading toward each other. When do they collide? LLM: [calls check_collision] Collision in 10.7 seconds at position 250m from car 1's starting point. Combined approach speed is 105 mph (46.9 m/s).

Force & Energy Calculations

User: What force is needed to accelerate a 1500 kg car at 3 m/s²? LLM: [calls calculate_force(1500, 3)] Force required: 4,500 N (Newtons) This is about 1,011 pounds of force.
User: What's the kinetic energy of a 2000 kg car at 30 m/s (about 67 mph)? LLM: [calls calculate_kinetic_energy(2000, 30)] Kinetic energy: 900,000 J (Joules) That's 900 kJ or 0.25 kWh of energy. For perspective, this is why car crashes at highway speeds are so dangerous.

Momentum Analysis

User: Calculate momentum of a 70 kg runner at 10 m/s LLM: [calls calculate_momentum(70, 10)] Momentum: 700 kg⋅m/s Direction: same as velocity vector

Complex Multi-Step Problems

User: I'm designing a water fountain. Water shoots up at 15 m/s. How high does it go and when does it come back down? LLM: [calls calculate_projectile_motion(15, 90)] The water will: - Rise to maximum height: 11.47 m - Take 1.53 seconds to reach peak - Return to ground level after 3.06 seconds total - Have the same 15 m/s speed when it lands (just downward)
User: A basketball player shoots from 2m high at 7 m/s toward a hoop 3.05m high and 4.6m away. What angles work? LLM: [calls calculate_projectile_motion with various angles] Two possible angles work: 1. Low arc: 38° (faster, flatter shot) 2. High arc: 52° (slower, higher shot) Most players use 50-55° for better chance of going in.

Rigid Body Simulations

User: Create a simulation of a ball dropping from 10 meters and bouncing LLM: [calls create_simulation(gravity_y=-9.81)] [calls add_rigid_body for ground plane (static)] [calls add_rigid_body for ball (dynamic, sphere, position=(0,10,0))] [calls record_trajectory(steps=200)] Simulation complete! The ball: - Hits ground at t=1.43s with velocity 14.0 m/s - Bounces to 7.5m (with restitution=0.8) - Makes 5 bounces before settling Here's the full trajectory data for R3F visualization...
User: Simulate 5 boxes stacked, then another box hits them from the side LLM: [calls create_simulation] [calls add_rigid_body for ground] [calls add_rigid_body 5 times for stacked boxes] [calls add_rigid_body for projectile box with velocity] [calls step_simulation(300)] [calls record_trajectory for each box] The collision causes a realistic toppling effect! Boxes 1-2 fall left, boxes 3-5 scatter right. Peak chaos at t=0.8s. All settled by t=3.2s. Full trajectory data ready for 3D visualization...

💡 Try These Prompts

Copy and paste these into your LLM chat to see the physics tools in action:

Projectile Motion

  • A golf ball is hit at 70 m/s at 15 degrees. How far does it go and what's the flight time?

  • What angle gives maximum range for a cannonball fired at 100 m/s?

  • If I throw a javelin at 28 m/s from 2 meters high, what angle gives maximum distance?

  • A basketball player shoots from 2m high at 7 m/s toward a hoop 3.05m high and 4.6m away. What angles work?

Collision Detection

  • Two cars 500m apart, one at 60 mph, other at 45 mph heading toward each other. When do they collide?

  • Two asteroids: one at (0,0,0) moving at 1000 m/s in x direction, another at (50000, 100, 0) moving at -800 m/s in x. Will they collide?

  • Spaceship A at (10000,0,0) moving at (-50,0,0) m/s, spaceship B at (-10000,100,0) moving at (45,0,0) m/s. Collision check?

Force, Energy & Momentum

  • What force is needed to accelerate a 1500 kg car at 3 m/s²?

  • What's the kinetic energy of a 2000 kg car traveling at 30 m/s?

  • Calculate the momentum of a 70 kg runner sprinting at 10 m/s

  • How much energy does a 0.145 kg baseball have when pitched at 45 m/s?

Real-World Applications

  • I'm designing a water fountain. Water shoots up at 15 m/s. How high does it go?

  • A cannon on a 50 meter cliff fires horizontally at 200 m/s. How far from the base does the projectile land?

  • Two cars crash: Car A (1500kg) at 30 m/s, Car B (1200kg) at 25 m/s. What's the total kinetic energy at impact?

Simulations (Requires Rapier Service)

  • Create a simulation of a ball dropping from 10 meters height and bouncing on the ground

  • Simulate 5 boxes stacked on top of each other, then have another box hit them from the side

  • Create a Newton's cradle with 5 spheres and record their motion

  • Simulate a sphere rolling down a 30-degree ramp

📝 Example Scripts

The examples/ directory contains working demonstration scripts:

Ready to Run (No External Services Required)

These examples use the built-in analytic provider and work immediately:

  • 00_quick_start.py - Quick demo of all 5 analytic tools

  • 01_simple_projectile.py - Cannonball trajectories, basketball shots, angle comparisons

  • 02_collision_detection.py - Car crashes, near misses, asteroid collisions

  • 03_force_energy_momentum.py - F=ma, kinetic energy, momentum conservation

  • 04_r3f_visualization.py - Generate React Three Fiber visualization data

# Run any example python examples/00_quick_start.py python examples/01_simple_projectile.py # ... etc

Requires Rapier Service

These examples demonstrate rigid-body simulations and Phase 1 features. They need the Rapier service running:

  • 05_rapier_simulation.py - Bouncing balls, collisions, stacking boxes

  • 06_bounce_detection.py - Phase 1.1: Automatic bounce detection and energy analysis

  • 07_contact_events.py - Phase 1.2: Real-time contact tracking and collision events

  • 08_pendulum.py - Phase 1.3: Joints and constraints (pendulums, chains)

  • 09_phase1_complete.py - Phase 1.4: All Phase 1 features (damping, bounces, contacts, joints)

  • 10_fluid_dynamics.py - Phase 1.5: Fluid calculations (drag, buoyancy, terminal velocity)

  • 11_rotational_dynamics.py - Phase 2.1: Torque, angular momentum, gyroscopes

  • 12_oscillations.py - Phase 2.2: Springs, pendulums, harmonic motion, damping

  • 13_circular_motion.py - Phase 2.3: Orbital mechanics, centripetal force

  • 14_statics.py - Phase 2.6: Static equilibrium, force balance, beam analysis

  • 15_kinematics_analysis.py - Phase 2.7: Motion analysis, trajectory fitting

  • 16_roulette_simulation.py - 🎰 Casino Roulette - Complete showcase of multi-body physics, collisions, and energy dissipation

# Option 1: Use public Rapier service (easiest) export RAPIER_SERVICE_URL=https://rapier.chukai.io python examples/05_rapier_simulation.py python examples/06_bounce_detection.py # ... etc # Option 2: Run local Rapier service with Docker docker run -p 9000:9000 chuk-rapier-service export RAPIER_SERVICE_URL=http://localhost:9000 python examples/05_rapier_simulation.py

Note:

  • Examples 00-04 work instantly (no external services)

  • Examples 05-09 showcase advanced rigid-body physics with Rapier

  • Use the public Rapier service at https://rapier.chukai.io or run your own

⚙️ Configuration

Environment Variables

# Provider selection PHYSICS_PROVIDER=analytic # or "rapier" # Rapier service (only if using Rapier provider) # The default is automatically determined: # - On Fly.io: uses https://rapier.chukai.io (public service) # - Locally: uses http://localhost:9000 # # Override with: RAPIER_SERVICE_URL=https://rapier.chukai.io # or http://localhost:9000 # Optional configuration RAPIER_TIMEOUT=30.0 RAPIER_MAX_RETRIES=3 RAPIER_RETRY_DELAY=1.0

YAML Configuration

Create physics.yaml in your working directory or ~/.config/chuk-mcp-physics/:

default_provider: rapier providers: # Override provider per tool type simulations: rapier projectile_motion: analytic rapier: # Public service (recommended) service_url: https://rapier.chukai.io # Or local development # service_url: http://localhost:9000 timeout: 30.0 max_retries: 3 retry_delay: 1.0

🛡️ Safety & Limits

Recommended Ranges

Understanding these limits helps prevent timeouts, instabilities, and confusion:

Parameter

Recommended

Maximum

Notes

Units

meters, kg, seconds

-

SI units throughout

dt

0.008 - 0.033

0.001 - 0.1

<0.008 = overkill, >0.033 = unstable

steps

100 - 5000

10,000

Depends on dt and complexity

bodies

1 - 100

1,000

Performance degrades >100

gravity

-20 to 0 m/s²

-100 to +100

Earth = -9.81

velocity

0 - 100 m/s

1,000 m/s

Very high speeds may cause tunneling

mass

0.1 - 10,000 kg

1e-6 - 1e6

Extreme ratios cause instability

Public Service Limits

The public Rapier service at https://rapier.chukai.io has these limits:

  • Max steps per call: 5,000

  • Max bodies per simulation: 100

  • Max concurrent simulations: 10 per IP

  • Request timeout: 30 seconds

  • Max simulation lifetime: 1 hour (auto-cleanup)

For larger simulations, run your own Rapier service (see RAPIER_SERVICE.md).

Common Pitfalls

❌ Simulation explodes or bodies fly away

Symptoms:

  • Bodies gain extreme velocities

  • Objects disappear from view

  • NaN values in positions

Causes:

  • dt too large for the forces involved

  • Very high mass ratios (1g object hitting 1000kg object)

  • Extreme initial velocities

Solutions:

  • Reduce dt to 0.008 or lower

  • Use more similar masses (within 2-3 orders of magnitude)

  • Limit initial velocities to <100 m/s

❌ Simulation runs very slowly

Symptoms:

  • Request takes >10 seconds

  • Timeout errors

  • High CPU usage

Causes:

  • Too many bodies (>100)

  • Very small dt (<0.005)

  • Complex mesh colliders

  • Too many steps (>5000)

Solutions:

  • Reduce body count or simplify shapes

  • Increase dt (balance accuracy vs. speed)

  • Break large step counts into multiple calls

  • Use primitive shapes (sphere, box) instead of meshes

❌ Objects tunnel through each other

Symptoms:

  • Fast-moving objects pass through walls

  • Collisions not detected

  • Objects appear inside each other

Causes:

  • Very high velocities + large dt

  • Thin colliders (<0.1m)

  • Disabled continuous collision detection (CCD)

Solutions:

  • Reduce dt for high-speed scenarios

  • Thicken colliders (minimum 0.1m recommended)

  • Reduce velocities

  • Enable CCD if available (future feature)

Best Practices

  1. Start simple: Test with 2-3 bodies before scaling up

  2. Validate inputs: Check for NaN, Inf, extreme values before simulation

  3. Monitor performance: Track step time, adjust dt/steps accordingly

  4. Cleanup: Always destroy_simulation when done (prevent memory leaks)

  5. Use analytic when possible: For simple scenarios, analytic is faster and exact

🔧 Development

# Clone repository git clone https://github.com/yourusername/chuk-mcp-physics cd chuk-mcp-physics # Install in development mode make dev-install # Run tests make test # Run tests with coverage make test-cov # Format code make format # Run all checks make check # Build package make build

🐳 Docker Deployment

# Build image make docker-build # Run container make docker-run # Access at http://localhost:8000

☁️ Production Deployment

Live Public Services

Current Production Services:

  • MCP Physics Server: https://physics.chukai.io/mcp

    • Public hosted MCP server endpoint

    • No local installation required

    • Pre-configured with Rapier service

    • Ready to use in Claude Desktop

  • Rapier Physics Engine: https://rapier.chukai.io

    • Public API for physics simulations

    • No authentication required for basic usage

    • Rate limits may apply

Quick Test:

# Test the public Rapier service curl https://rapier.chukai.io/health # Use with chuk-mcp-physics locally export RAPIER_SERVICE_URL=https://rapier.chukai.io uvx chuk-mcp-physics

Deploy Your Own Rapier Service

If you need your own private Rapier service instance:

1. Deploy Rapier Service to Fly.io with Redis

cd rapier-service # Login to Fly.io fly auth login # Create Redis instance for distributed storage fly redis create # Choose: your-rapier-redis, region sjc (or your preferred region), plan 256MB # Set Redis URL secret (use URL from previous step) fly secrets set REDIS_URL="redis://default:password@fly-your-rapier-redis.upstash.io" # Create and deploy the service fly apps create your-rapier-physics fly deploy # Verify Redis connection in logs fly logs # Look for: "📦 Initialized RedisStorage backend" # Add custom domain (optional) fly certs add rapier.yourdomain.com -a your-rapier-physics # Verify service is running curl https://your-rapier-physics.fly.dev/health

Redis Benefits:

  • ✅ Horizontal scaling (multiple service instances share state)

  • ✅ Automatic cleanup (TTL-based simulation expiration)

  • ✅ Distributed coordination across instances

  • ✅ Session persistence within TTL window

Configuration: The service uses Redis automatically on Fly.io (see rapier-service/fly.toml). For local development, it defaults to in-memory storage.

See rapier-service/FLY_REDIS_SETUP.md for detailed Redis setup guide, monitoring, and troubleshooting.

2. Configure chuk-mcp-physics to Use Your Service

# Option 1: Environment variable export RAPIER_SERVICE_URL=https://rapier.yourdomain.com uvx chuk-mcp-physics # Option 2: YAML config (physics.yaml) # rapier: # service_url: https://rapier.yourdomain.com

Why deploy your own?

  • 🔒 Private instance for production workloads

  • 📈 Custom scaling and resource allocation

  • 🌍 Deploy closer to your users (different regions)

  • 💾 Persistent simulations and custom configurations

See DEPLOYMENT.md for complete deployment guide, scaling strategies, and CI/CD setup.

🦀 Rapier Service Setup

For full rigid-body simulations, you have several options:

Option 1: Use Public Service (Easiest)

# No setup required - just configure the URL export RAPIER_SERVICE_URL=https://rapier.chukai.io uvx chuk-mcp-physics

Option 2: Run Locally with Docker

# Using Docker docker run -p 9000:9000 chuk-rapier-service # Configure to use local service export RAPIER_SERVICE_URL=http://localhost:9000 uvx chuk-mcp-physics

Option 3: Build from Source

# Build and run the Rust service cd rapier-service cargo run --release # In another terminal export RAPIER_SERVICE_URL=http://localhost:9000 uvx chuk-mcp-physics

See RAPIER_SERVICE.md for:

  • Complete API specification

  • Rust implementation guide

  • Docker deployment details

  • Testing examples

📊 Comparison: Analytic vs Rapier

Feature

Analytic Provider

Rapier Provider

Projectile motion

✅ Exact (kinematic eqs)

✅ Simulated

Simple collisions

✅ Exact (sphere-sphere, elastic)

✅ Simulated

Force/energy/momentum

✅ F=ma, KE, PE, momentum, work/power

✅ Can derive from sim

Fluid dynamics

✅ Drag, buoyancy, terminal velocity

❌ Not supported

Rigid-body dynamics

❌ Not supported

✅ Full 3D/2D physics

Complex shapes

❌ Spheres only

✅ Box, capsule, mesh, etc

Friction/restitution

❌ Not modeled

✅ Full material properties

Multi-body systems

❌ Not supported

✅ Unlimited bodies

Constraints/joints

❌ Not supported

✅ Hinges, sliders, etc

Performance

⚡ Instant

🐇 Fast (Rust)

Setup

📦 Built-in

🦀 Requires Rapier service

Recommendation:

  • Use Analytic for simple calculations, education, quick answers

  • Use Rapier for complex simulations, games, visualizations, multi-body dynamics

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

📚 See Also

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/chrishayuk/chuk-mcp-physics'

If you have feedback or need assistance with the MCP directory API, please join our Discord server