mcp-physics-bridge

Table of Contents

• Core Highlights

• Architecture Overview

• Quickstart (Zero Configuration)

  • AI Editor Integration (Claude Desktop & Cursor)

  • CLI Flags & Daemon Mode

• Game Engine Integrations

• Observability & Monitoring

• Production Deployment

  • Environment Variables

  • Docker & Docker Compose

• Development & Verification

• Architecture Roadmap

• Community & Governance

Related MCP server: flash-cast-mcp

Core Highlights

Architecture Overview

+-------------------------------------------------------------+
|                        Game Engine                          |
|         (Unity / Unreal / Godot / Phaser / Custom)          |
+-------------------------------------------------------------+
         |                                           ^
         | [Native: HTTP/2 gRPC Stream]              |
         | [Web: WebSocket (Token Auth)]             | [Blend Weights /
         v                                           |  Playback Scale]
+----------------------------------------------------+--------+
|                 mcp-physics-bridge                 |        |
|                                                    v        |
|  +------------------------+    +-------------------------+  |
|  |  Data Translation Layer|    | AI-to-Rig Synthesizer   |  |
|  |  (SoA <-> Scene Tree)  |    | (Intent / Priority)     |  |
|  +------------------------+    +-------------------------+  |
|              |                             ^                |
|              v                             |                |
|  +------------------------+    +-------------------------+  |
|  |  State Authority Guard |    | In-Memory Wasm Sandbox  |  |
|  |  (Playtest vs Debug)   |--->| (AssemblyScript Engine) |  |
|  +------------------------+    +-------------------------+  |
|              |                             ^                |
|              v                             |                |
|  +------------------------+    +-------------------------+  |
|  |  Keyframe RAG Store    |    | Model Context Protocol  |  |
|  |  (SQLite-Vector)       |    | (BYOK LLM Provider)     |  |
|  +------------------------+    +-------------------------+  |
+-------------------------------------------------------------+

Quickstart (Zero Configuration)

You can run mcp-physics-bridge immediately via npx without cloning or manual builds:

# Run stdio MCP server for Claude Desktop, Cursor, or Antigravity
npx -y mcp-physics-bridge --stdio

# Run full multi-protocol server daemon (gRPC + gRPC-Web + WebSocket + MCP)
npx -y mcp-physics-bridge

AI Editor Integration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "physics-bridge": {
      "command": "npx",
      "args": ["-y", "mcp-physics-bridge", "--stdio"],
      "env": {
        "MCP_PHYSICS_AUTHORITY_MODE": "playtest",
        "MCP_PHYSICS_BYOK_PROVIDER": "mock"
      }
    }
  }
}

Cursor / Antigravity (~/.cursor/mcp.json or .agy/settings.json)

{
  "mcpServers": {
    "physics-bridge": {
      "command": "npx",
      "args": ["-y", "mcp-physics-bridge", "--stdio"]
    }
  }
}

CLI Flags & Daemon Mode

mcp-physics-bridge [OPTIONS]

MODES:
  --stdio                Run in stdio MCP mode (for Claude Desktop / Cursor)
  --all                  Run full multi-protocol daemon [default]

OPTIONS:
  -p, --port <port>      WebSocket physics port (default: 8080)
  --grpc <port>          Native HTTP/2 gRPC streaming port (default: 50051)
  --grpc-web <port>      gRPC-Web proxy / metrics port (default: 50052)
  --env <env>            Environment mode: 'development' | 'production'
  --fps <number>         Target simulation tick rate (default: 60)
  -v, --version          Print version and exit
  -h, --help             Show help screen

Game Engine Integrations

The examples/ directory contains production-ready client scripts and schemas:

Observability & Monitoring

The bridge exposes standard cloud-native health and metrics endpoints on the gRPC-Web port (default 50052):

• Health Probe (GET /healthz):

  curl http://localhost:50052/healthz

  {
    "status": "ok",
    "service": "mcp-physics-bridge",
    "uptimeSeconds": 142.5,
    "requestsProcessed": 42
  }

• Prometheus Metrics (GET /metrics):

  curl http://localhost:50052/metrics

  Exposes mcp_physics_requests_total, mcp_physics_uptime_seconds, mcp_physics_memory_heap_bytes, and mcp_physics_memory_rss_bytes.

Production Deployment

Environment Variables

Copy .env.example to .env or pass variables to your deployment container:

cp .env.example .env

Docker & Docker Compose

Run the production multi-stage container with non-root security and healthcheck probes:

# Build and run with Docker
npm run docker:build
npm run docker:run

# Or launch with Docker Compose (includes persistent storage)
docker compose up -d

Development & Verification

Scripts Reference

# Run unit and integration test suite (27 test suites, 237 tests)
npm test

# Run tests with V8 code coverage report (>92% coverage)
npm run test:coverage

# Perform TypeScript static type check
npm run typecheck

# Compile AssemblyScript WebAssembly modules
npm run build:as

# Build production TypeScript distribution
npm run build

# Run comprehensive 10-phase manual verification
npm run verify

Architecture Roadmap

• Phase 1: Barebones Scaffolding & Build Contracts

  • Scaffold folder structure, configurations (package.json, tsconfig.json, asconfig.json, vitest.config.ts, CI workflow).

  • Define core interfaces and barebones stubs across all subsystems.

• Phase 2: Protobuf Schema Definitions & Code Generation

  • Implement physics_stream.proto (SoA layout, error status bitmasks).

  • Implement ai_hooks.proto (Dual-payload, AST diff, diagnostic traces).

  • Implement animation_stream.proto (Intents, weights, priority tags).

• Phase 3: Network & Protocol-Splitting Layer

  • HTTP/2 gRPC server for native engines (PhysicsStreamingService, AIHookService, AnimationSynthesisService).

  • Token-handshake secured WebSocket server for web engines with CSWSH protection and timing-safe token validation.

  • gRPC-Web gateway for sporadic browser hooks with CORS and JSON fallback.

• Phase 4: Struct of Arrays (SoA) & Data Translation Layer

  • Zero-copy TypedArray views (Float32Array, Uint32Array).

  • Bi-directional SoA $\leftrightarrow$ Hierarchical Scene Tree translator.

• Phase 5: AssemblyScript Math Library & In-Memory Wasm Sandbox

  • Native in-sandbox Vector3 and Quaternion math library.

  • In-memory asc compiler pipeline (<10ms execution).

  • Dual-Payload verification (source checksum vs bytecode).

  • Reflective memory AST diffing and error logging.

• Phase 6: State Authority & Validation Rules

  • Playtest Mode: Soft clamping, micro time-dilation, VFX-masked snaps.

  • Debug Mode: Strict hard rejection, frame-synchronized error status bitmask.

• Phase 7: Context Management & SQLite-Vector RAG

  • SQLite-Vector embedded database initialization with custom vector similarity functions (cosine_similarity, l2_distance, dot_product).

  • Deterministic physics state embedder producing 128D normalized unit vectors from scene trees and flat SoA frames.

  • Selective keyframe event indexer (collision, goal, state_change, failure) with cooldown throttling to prevent context bloat.

  • Event detection helpers (inter-entity bounding sphere collisions, velocity state changes).

  • RAG prompt synthesis with token-efficient compact JSON state pruning (formatRAGPromptContext).

• Phase 8: AI-to-Rig Animation Synthesizer

  • Hybrid Intent-Mapping across 5 standardized genre templates (Generic, Platformer, FPS, Action RPG, Vehicle), semantic synonyms dictionary, and custom dictionary mappings.

  • Bridge-Side Action Priority Arbitration with multi-track skeletal layers (Full Body, Lower Body, Upper Body, Additive), priority tag governance (uninterruptible, hit_reaction, death), and time-based action expiration.

  • Opt-In Weight Streaming Calculator with configurable blend curves (Linear, Smoothstep, S-Curve, Exponential, Instant), transition duration scaling, and strict sum-of-weights invariant $\sum w_i = 1.0$.

  • Root Motion Procedural Playback Scaling with physics authority ($s = v_{\text{actual}} / v_{\text{nominal}}$), 3D/planar velocity decomposition, low-pass EMA smoothing, angular turn scaling, and foot sliding metrics.

  • Unified AnimationSynthesizer orchestrator integrated into native HTTP/2 gRPC streaming.

• Phase 9: Model Context Protocol (MCP) Server Integration

  • Standardized @modelcontextprotocol/sdk integration with full tool, resource, and prompt registrations.

  • BYOK (Bring-Your-Own-Key) LLM router supporting OpenAI-compatible, Anthropic, Gemini, Ollama, custom proxy, and deterministic offline mock providers.

  • Complete MCP tool suite: compile_and_test_physics, validate_physics_frame, deploy_dual_payload_logic, inspect_game_state, query_keyframe_history, inspect_reflective_memory, synthesize_animation, generate_physics_kernel, repair_physics_kernel.

  • Resource endpoints under physics://: physics://config, physics://server/status, physics://heuristics, physics://math/vector3, physics://math/quaternion, physics://animation/templates, physics://memory/failures.

  • Standard prompts: game_heuristics_kernel, debug_physics_failure, synthesize_character_animation.

• Phase 10: Testing Suite & Verification

  • Comprehensive unit and integration test suite with Vitest (27 test files, 237 tests, >92% statement and line coverage).

  • End-to-end service lifecycle integration testing (PhysicsBridgeService) covering multi-protocol bootstrap and graceful shutdown.

  • Subsystem test coverage across MCP resources, prompts, reflective memory, deep hierarchy inspection, and BYOK LLM routers.

  • High-throughput 60 FPS performance benchmark validating sub-16ms latency budgets for 10,000 entities in Struct of Arrays (SoA).

  • Automated CI/CD verification (.github/workflows/ci.yml) covering TypeScript typechecking, AssemblyScript Wasm compilation, full compilation build, and Vitest coverage reporting.

Community & Governance

• Contributing Guide: Setup instructions, architecture standards, and PR guidelines.

• Security Policy: Responsible vulnerability reporting and security architecture.

• Code Examples: Integration guides and starter scripts for Unity, Unreal, Godot, and Web.

• License: Licensed under the Apache License, Version 2.0.