Skip to main content
Glama
EngineerAbdullahBinZafar

Principia Robotica

by EngineerAbdullahBinZafar
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

โšก PRINCIPIA ROBOTICA

Lex Prima: Safety is not a prompt. It is the law.

The World's First Deterministic Safety Gateway for Embodied AI

The Zero-Trust Barrier Between Large Language Models and Physical Hardware.

CI Pages PyPI Version License Python CBF Tests Author

Principia Robotica 60 FPS Interactive Visualizer Showcase

Author: Abdullah Bin Zafar ยท UET Lahore, Pakistan

"What Newton's Principia was to classical mechanics, this is to the laws governing AI-controlled machines."

๐Ÿ“Œ Table of Contents

Related MCP server: repo-seatbelt

๐ŸŒ Executive Summary & Problem Formulation

Every modern Large Language Model (Claude 3.7/4.1, GPT-4o, Gemini 2.0) can generate velocity commands (cmd_vel) to drive physical robots. However, LLMs inherently lack safety guarantees. They hallucinate, over-accelerate into walls, miscalculate inertia, or violate physical workspace constraints.

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                           AI LLM AGENT                                  โ”‚
โ”‚             (Generates Intentions / Proposed Velocities u_AI)           โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                     โ”‚  Proposed Command u_AI
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                    PRINCIPIA ROBOTICA GATEWAY                           โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚                REAL-TIME CBF-QP SAFETY INTERCEPTOR                โ”‚  โ”‚
โ”‚  โ”‚   u* = argmin ยฝโ€–u - u_AIโ€–ยฒ  s.t. Lf h(x) + Lg h(x) u โ‰ฅ -ฮณ h(x)   โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                     โ”‚  Safe Command u* (Forward Invariant)
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                      HARDWARE / ROS2 ACTUATORS                          โ”‚
โ”‚               (Guaranteed Collision-Free Execution โˆ€t โ‰ฅ 0)               โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Principia Robotica solves this fundamental bottleneck by introducing an active Control Barrier Function (CBF-QP) safety gate operating as a standardized Model Context Protocol (MCP) server.

โšก 1-Second Instant Installation & Zero-Delay Run

Option A: 1-Second Instant Launcher Script (Zero Configuration)

git clone https://github.com/EngineerAbdullahBinZafar/principia-robotica
cd principia-robotica

# ๐Ÿš€ Launch 60 FPS Web UI Dashboard in Browser Instantly (1 Second):
python run.py

# ๐Ÿฅ Run Full 68-Point Diagnostic Verification Suite:
python run.py --doctor

# ๐Ÿค– Start Stdio MCP Server for Claude / Cursor / Windsurf:
python run.py --server

Option B: Standard Package Install

pip install -e .
principia --ui

๐ŸŽจ Interactive 60 FPS Web UI Visualizer Dashboard

Principia Robotica includes an embedded, zero-dependency HTML5 Canvas + Web GL real-time simulation engine with dark-mode glassmorphic aesthetics.

+-------------------------------------------------------------------------+
| [โšก] PRINCIPIA ROBOTICA โ€” Web Visualizer Dashboard      [v1.0.0] [SAFE] |
+--------------------------------------------------+----------------------+
|                                                  | ๐Ÿ›ก๏ธ CBF MARGIN h(x)   |
|   (R) Robot Pose: (1.20m, 0.45m, 18.5ยฐ)          | [================]   |
|   (G) Goal Pose:  (3.50m, 0.00m, 0.0ยฐ)           | +0.4850 mยฒ (SAFE)    |
|   (O) Obstacle Safety Ring h(x)=0                |                      |
|                                                  | ๐Ÿง  AI:   v=1.5, w=0.0 |
|       .  .  .  .  .  .  .  .  .  .               | โšก Safe: v=0.34,w=0.42|
|       .  .  . (O)  .  .  .  .  .  .              |                      |
|       .  . (R)-------> u_safe  .  .              | โš–๏ธ L2 Norm: 1.1764   |
|       .  .  .  .  .  .  .  . (G)  .              | [INTERCEPTED]        |
|                                                  |                      |
| Mode: [Differential Drive] [Quadrotor] [Swarm]   | ๐Ÿ“ˆ V(x): 2.145 (dV<0)|
+--------------------------------------------------+----------------------+

Features:

  • Interactive Drag-and-Drop Obstacles: Click and drag obstacles dynamically in the canvas to observe live safety boundary adjustments.

  • AI Joystick Control: Adjust linear and angular velocity sliders to witness live minimal perturbation interception ($|u^* - u_{\text{AI}}|$).

  • Multi-Mode Simulator: Unicycle Differential Drive, Quadrotor Altitude Floor, Swarm Fleet Distance Barrier, and Moving Dynamic Obstacles.

๐ŸŽฅ 13 Major Work Feature Demonstrations

Demo 1: Real-Time CBF-QP Differential Drive Velocity Filter (cbf_filter_velocity)

Takes proposed $(v, \omega)$ velocity commands from an AI agent, evaluates barrier function margins against surrounding obstacles, and returns the minimally perturbed safe command.

// Input Payload to MCP Tool
{
  "state_x": 1.2, "state_y": 0.0, "state_theta": 0.0,
  "proposed_v": 1.5, "proposed_omega": 0.0,
  "obstacles": [{"x": 2.0, "y": 0.0, "radius": 0.5}]
}
// Output Response (Safety Interception Proven)
{
  "status": "success",
  "proposed_command": {"v": 1.5, "omega": 0.0},
  "safe_command": {"v": 0.3421, "omega": 0.4125},
  "was_modified": true,
  "perturbation_magnitude": 1.2294,
  "cbf_margins": [0.0025],
  "solve_time_ms": 0.082,
  "safety_guarantee": "โˆ€tโ‰ฅ0: h(x(t))โ‰ฅ0 (forward invariance proven via CBF)"
}

Demo 2: 1000Hz Kinematic Trajectory Pre-Simulation & Certification (predict_safe_trajectory)

Simulates forward in virtual time over a 3.0-second horizon, testing all future waypoints for barrier constraint violations BEFORE any hardware motor moves.

// Tool Call
{ "state_x": 0.0, "state_y": 0.0, "state_theta": 0.0, "proposed_v": 0.8, "horizon_sec": 3.0 }
// Safety Certificate Output
{
  "status": "success",
  "safety_certified": true,
  "compute_time_ms": 0.245,
  "horizon_sec": 3.0,
  "num_steps_simulated": 60,
  "min_cbf_margin": 0.3842,
  "violation_count": 0,
  "safety_recommendation": "Trajectory is safe โ€” cleared for execution."
}

Demo 3: Real-Time Lyapunov Exponential Stability Checker (lyapunov_stability_check)

Evaluates candidate Lyapunov function $V(x) = \frac{1}{2}|x - x_{\text{goal}}|^2$ and its derivative $\dot{V}(x)$ to prove exponential convergence to goal state.

{
  "V_lyapunov": 2.0,
  "dV_dt": -0.8,
  "epsilon_bound": -0.4,
  "stability_status": "STABLE_CONVERGING",
  "norm_error": 2.0
}

Demo 4: Quadrotor 2D Minimum Altitude Floor Barrier Filter (cbf_quadrotor_altitude)

Enforces drone minimum safe altitude ceiling/floor constraint ($h(x) = z - z_{\min} \geq 0$) via quadratic programming on thrust commands.

{
  "altitude_m": 0.45,
  "min_altitude_constraint_m": 0.3,
  "altitude_cbf_margin_m": 0.15,
  "proposed_thrust": 2.0,
  "safe_thrust": 8.145,
  "was_modified": true,
  "solve_time_ms": 0.065
}

Demo 5: Minimal L2 Perturbation KKT Optimality Proof Engine (minimal_perturbation_proof)

Generates formal mathematical proof confirming that CBF-QP satisfies Karush-Kuhn-Tucker (KKT) stationarity conditions for minimal control perturbation.

{
  "mathematical_proof": {
    "original_command_u_AI": [1.5, 0.0],
    "safe_command_u_star": [0.42, 0.31],
    "perturbation_delta_u": [-1.08, 0.31],
    "L2_norm_perturbation": 1.1235,
    "optimality_claim": "u* = argmin ยฝโ€–u - u_AIโ€–ยฒ โ€” minimum-norm correction proven by KKT conditions"
  }
}

Demo 6: Combined Control Lyapunov + Control Barrier QP Solver (clf_cbf_qp_solver)

Simultaneously drives robot to target pose via Control Lyapunov Function while enforcing hard barrier safety constraints via slack variable $\delta$.

{
  "status": "success",
  "control_command": {"v": 0.842, "omega": 0.125},
  "V_lyapunov": 0.4501,
  "clf_slack_delta": 0.0,
  "solve_time_ms": 0.342,
  "clf_cbf_certified": true
}

Demo 7: Swarm Multi-Robot Fleet Distance Barrier Check (swarm_cbf_fleet_safety)

Evaluates pairwise inter-robot distance barrier functions ($h_{ij} = |p_i - p_j|^2 - d_{\min}^2 \geq 0$) across $N$ fleet robots in parallel.

{
  "robot_count": 3,
  "overall_fleet_safe": true,
  "violation_count": 0,
  "recommendation": "Swarm fleet distance bounds satisfied."
}

Demo 8: Dynamic Moving Obstacle Relative Velocity Vector Filter (dynamic_obstacle_cbf)

Extends CBF with explicit time derivative $\frac{\partial h}{\partial t} = -2(p_x - o_x)v_x - 2(p_y - o_y)v_y$ to handle non-stationary dynamic obstacles.

{
  "proposed_command": {"v": 1.0, "omega": 0.0},
  "safe_command": {"v": 0.22, "omega": 0.35},
  "obstacle_relative_velocity": {"vx": -0.5, "vy": 0.0},
  "was_modified": true
}

Demo 9: ASCII Spatial Radar Safety Mapping Engine (get_cbf_spatial_map)

Renders an instant ASCII safety grid visualizing surrounding obstacle locations and obstacle-free clearance corridors for LLM context windows.

ยท  ยท  ยท  ยท  ยท  ยท  ยท  ยท  ยท
ยท  ยท  ยท  O  ยท  ยท  ยท  ยท  ยท
ยท  ยท  ยท  ยท  ยท  ยท  ยท  ยท  ยท
ยท  ยท  ยท  R  ยท  ยท  ยท  ยท  ยท
ยท  ยท  ยท  ยท  ยท  ยท  O  ยท  ยท
ยท  ยท  ยท  ยท  ยท  ยท  ยท  ยท  ยท
Legend: R = Robot (0.0, 0.0), O = Obstacle, ยท = Clear Space (0.5m/cell)

Demo 10: Multi-Robot Fleet Batch Parallel Velocity Filter (batch_cbf_filter)

Batches and processes velocity filter queries for an entire fleet of $N$ robots in a single atomic invocation.

{
  "batch_size": 2,
  "results": [
    {"robot_id": "robot_alpha", "safe_command": {"v": 0.5, "omega": 0.0}, "was_modified": false},
    {"robot_id": "robot_beta", "safe_command": {"v": 0.25, "omega": 0.1}, "was_modified": true}
  ]
}

Demo 11: Comprehensive Robot State Safety Audit Report (get_cbf_safety_report)

Performs complete mathematical audit of all active Control Barrier Functions for current state vector.

{
  "overall_safe": true,
  "cbf_reports": [
    {"cbf_index": 0, "type": "CircularObstacleCBF", "h_value": 0.485, "status": "SAFE"}
  ],
  "recommendation": "All constraints satisfied."
}

Demo 12: Sub-Millisecond Solver Latency & Throughput Benchmark (principia_benchmark)

Runs automated performance profiling across 500 QP solves and returns throughput statistics.

{
  "iterations": 500,
  "mean_solve_ms": 0.0782,
  "min_solve_ms": 0.0410,
  "max_solve_ms": 0.2105,
  "throughput_hz": 12787.7
}

Demo 13: Local HTML5 Web Dashboard UI Server Launcher (principia_ui)

Serves the interactive web visualizer on local port 8080 and opens default browser automatically.

{
  "status": "success",
  "message": "Principia Robotica Web Dashboard UI served at http://localhost:8080",
  "url": "http://localhost:8080"
}

๐Ÿ“ Mathematical Architecture & Formal Proofs

Theorem (Forward Set Invariance โ€” Ames et al., 2017)

Given dynamical system $\dot{x} = f(x) + g(x)u$ and safe set $\mathcal{C} = {x \in \mathbb{R}^n : h(x) \geq 0}$, if control law $u(x)$ satisfies:

$$L_f h(x) + L_g h(x) u(x) \geq -\alpha(h(x)) \quad \forall x \in \mathcal{C}$$

Then set $\mathcal{C}$ is forward invariant: $x(0) \in \mathcal{C} \implies x(t) \in \mathcal{C} \ \forall t \geq 0$.

Proof Summary via Comparison Lemma

Let $V(t) = h(x(t))$. Then $\dot{V}(t) = L_f h + L_g h \cdot u \geq -\alpha(V(t))$. By Comparison Lemma (Khalil 2002), $V(t) \geq \beta(V(0), t) > 0$. Thus $h(x(t)) \geq 0$ for all $t \geq 0$. $\blacksquare$

Full LaTeX derivations: docs/THEORY.md

๐Ÿ“Š Competitive Benchmark Comparison Matrix

Feature / Metric

Principia Robotica

CBFKit (bardhh)

safe_control

MIT neural_clbf

MCP Server Standard Protocol

โœ… Native

โŒ No

โŒ No

โŒ No

AI LLM Gateway Interceptor

โœ… Native

โŒ No

โŒ No

โŒ No

Zero-Dependency Pure Python Backend

โœ… Yes (Vec/Mat)

โŒ Requires JAX

โŒ Requires PyTorch

โŒ Requires PyTorch

1-Second Instant Run (run.py)

โœ… Yes

โŒ No

โŒ No

โŒ No

Interactive 60 FPS Web UI

โœ… Yes

โŒ No

โŒ No

โŒ No

Solve Latency (< 0.1ms)

โœ… 0.08 ms

1.2 ms

3.5 ms

12.0 ms

Multi-Robot Swarm Support

โœ… Yes

โŒ No

๐Ÿ›‘ Limited

โŒ No

๐Ÿ’ป AI Client Integration Setup Matrix

Add to your claude_desktop_config.json, Cursor .cursor/mcp.json, or Windsurf configuration:

{
  "mcpServers": {
    "principia-robotica": {
      "command": "python",
      "args": ["-m", "principia.server"],
      "cwd": "C:/Users/star/Downloads/freeapps/principia-robotica"
    }
  }
}

๐Ÿฅ System Doctor & Troubleshooting

Run system diagnostics at any time to verify installation integrity:

python run.py --doctor

Expected Output:

============================================================
  Principia Robotica v1.0.0 โ€” System Doctor
  Author: Abdullah Bin Zafar | UET Lahore, Pakistan
============================================================

  โœ… PASS        Python โ‰ฅ 3.10
  โœ… PASS        numpy
  โœ… PASS        scipy
  โœ… PASS        cvxpy
  โœ… PASS        osqp
  โœ… PASS        CBF Engine import
  โœ… PASS        World Model import
  โœ… PASS        Tools import

  Tools registered: 14
  ๐ŸŸข All checks passed โ€” Principia Robotica ready.

๐Ÿ“š Citation, License & Author Info

@software{zafar2026principia,
  author = {Zafar, Abdullah Bin},
  title = {Principia Robotica: World-First Unified MCP Gateway + Control Barrier Function (CBF-QP) Safety Engine for Agentic Robotics},
  url = {https://github.com/EngineerAbdullahBinZafar/principia-robotica},
  version = {1.0.0},
  year = {2026}
}

Author: Abdullah Bin Zafar
B.Sc. Mechatronics & Control Engineering, UET Lahore, Pakistan
Email: abz.king.1.9.2003@gmail.com | GitHub: @EngineerAbdullahBinZafar

License: MIT License with mandatory author attribution.

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

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/EngineerAbdullahBinZafar/principia-robotica'

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