Skip to main content
Glama
EngineerAbdullahBinZafar

Principia Robotica

by EngineerAbdullahBinZafar
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

⚡ PRINCIPIA ROBOTICA

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

World-first unified MCP gateway + Control Barrier Function (CBF-QP) safety engine for agentic robotics.

Give Claude, GPT-4o, Gemini, and any LLM mathematically proven safe control over physical robots via ROS2.

Version License Python CBF Author

Created: July 29, 2026 · Author: Abdullah Bin Zafar · UET Lahore, Pakistan

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

🌍 Why This Exists (The Problem)

Every AI agent — Claude, GPT-4o, Gemini — can be told to drive a robot. But none of them can mathematically guarantee safety. They can crash, over-accelerate, collide, or violate physical limits. There was no open-source bridge between LLM intelligence and control-theoretic safety.

Until now.

Related MCP server: Nonead Universal-Robots MCP Server

🔬 What This Is (The World-First Innovation)

Existing World

After Principia Robotica

AI sends cmd_vel. Robot may crash.

AI's command is intercepted by CBF-QP solver. Safe command issued.

No formal safety guarantee

∀t≥0: h(x(t)) ≥ 0 — mathematically proven forward invariance

Safety = hope + testing

Safety = formal theorem (Ames et al., proven 2017)

MCP server = passive sensor reader

MCP server = active safety enforcer

Pre-simulation not available

Certify trajectory BEFORE hardware moves

📐 The Mathematics (The Core Law)

The CBF-QP Safety Filter solves this problem in real-time (< 1ms in Python):

$$u^* = \arg\min_{u \in \mathcal{U}} \frac{1}{2}|u - u_{\text{AI}}|^2$$

$$\text{subject to:} \quad L_f h(x) + L_g h(x) u \geq -\alpha(h(x))$$

Where:

  • $u_{\text{AI}}$ = command from AI agent (Claude, GPT-4o, Gemini...)

  • $h(x)$ = Control Barrier Function (encodes obstacle avoidance)

  • $L_f h$, $L_g h$ = Lie derivatives along robot dynamics

  • $\alpha: \mathbb{R} \to \mathbb{R}$ = class-K function (typically $\alpha(h) = \gamma h$)

Result: The robot receives the closest safe command to what the AI wanted. Formally proven optimal by KKT conditions.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    AI Agent (Claude / GPT-4o / Gemini)          │
│                    Tools: cbf_filter_velocity,                   │
│                           predict_safe_trajectory,              │
│                           lyapunov_stability_check, ...         │
└──────────────────────────┬──────────────────────────────────────┘
                           │  MCP stdio (JSON-RPC 2.0)
┌──────────────────────────▼──────────────────────────────────────┐
│               PRINCIPIA ROBOTICA MCP SERVER                     │
│  ┌──────────────────┐   ┌──────────────────┐   ┌────────────┐  │
│  │  CBF-QP Solver   │   │ Kinematic World  │   │ Lyapunov   │  │
│  │  (CVXPY + OSQP)  │   │ Model (1000Hz)   │   │ Stability  │  │
│  │  < 1ms Python    │   │ Trajectory Sim   │   │ Analyzer   │  │
│  └────────┬─────────┘   └────────┬─────────┘   └─────┬──────┘  │
│           └────────────────────┬─┘                   │         │
└────────────────────────────────┼─────────────────────┘─────────┘
                                 │  ROS2 Bridge (optional)
┌────────────────────────────────▼─────────────────────────────────┐
│         ROS2 Middleware — /cmd_vel_raw → [CBF] → /cmd_vel        │
│                        ↑ /odom (live state)                      │
└──────────────────────────────────────────────────────────────────┘
                                 │
┌────────────────────────────────▼─────────────────────────────────┐
│              PHYSICAL ROBOT (TurtleBot4 / Spot / Custom)         │
└──────────────────────────────────────────────────────────────────┘

🎨 Interactive Web Visualizer Dashboard (1-Second Demo)

Launch the 60 FPS live HTML5 Canvas + Web GL simulator in your browser with a single command:

python -m principia.server --ui

  • Live Obstacle Field: Drag and drop circular obstacles in real-time.

  • AI Command Interceptor: Adjust AI linear/angular velocity sliders to observe real-time CBF-QP minimal perturbation filtering.

  • Multi-Mode Support: Unicycle differential drive, Quadrotor 2D altitude floor, Swarm fleet inter-robot collision check, and Dynamic moving obstacles.

  • Visual Telemetry: Real-time $h(x)$ safety gauge, Lyapunov energy $V(x)$ plot, and predicted trajectory path.

🛠️ 1-Second Installation & Setup

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

Verify everything works instantly:

python -m principia.server --doctor

⚡ Quickstart (3 Commands)

1. Run the MCP server:

python -m principia.server

2. Test the CBF filter directly in Python:

import numpy as np
from principia.cbf_engine import (
    DifferentialDriveModel, CircularObstacleCBF, CBFQPSafetyFilter
)

robot = DifferentialDriveModel()
obstacle = CircularObstacleCBF(obstacle_x=2.0, obstacle_y=0.0, obstacle_radius=0.5)
safety_filter = CBFQPSafetyFilter(
    robot=robot,
    cbfs=[obstacle],
    u_min=np.array([-0.5, -2.5]),
    u_max=np.array([1.5, 2.5]),
)

# Robot at (1.2, 0) heading toward obstacle at (2.0, 0)
x = np.array([1.2, 0.0, 0.0])
u_ai = np.array([1.5, 0.0])  # AI wants full speed ahead

result = safety_filter.solve(x, u_ai)

print(f"AI proposed:  v={u_ai[0]:.2f} m/s")
print(f"Safe command: v={result['u_safe'][0]:.2f} m/s")
print(f"Was modified: {result['was_modified']}")
print(f"Solve time:   {result['solve_time_ms']:.2f} ms")

3. Add to your AI client (Claude Desktop / Cursor):

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "principia-robotica": {
      "command": "python",
      "args": ["-m", "principia.server"],
      "cwd": "/path/to/principia-robotica"
    }
  }
}

🔧 MCP Tools (13 Total)

Tool

Type

Description

cbf_filter_velocity

🔴 WORLD-FIRST

Real-time CBF-QP safety filter for velocity commands

predict_safe_trajectory

🔴 WORLD-FIRST

Pre-simulate + certify trajectory before hardware moves

lyapunov_stability_check

🔴 WORLD-FIRST

Real-time Lyapunov stability verification

cbf_quadrotor_altitude

🔴 WORLD-FIRST

CBF altitude safety for quadrotors

minimal_perturbation_proof

🔴 WORLD-FIRST

Formal KKT proof of minimum-norm safety correction

clf_cbf_qp_solver

🔴 WORLD-FIRST

Unified Control Lyapunov + Control Barrier QP solver

swarm_cbf_fleet_safety

🔴 WORLD-FIRST

Multi-robot swarm inter-agent collision & barrier check

dynamic_obstacle_cbf

🔴 WORLD-FIRST

CBF safety filter for dynamic moving obstacles

get_cbf_spatial_map

🔴 WORLD-FIRST

ASCII radar safety map of surrounding obstacle space

batch_cbf_filter

🔴 WORLD-FIRST

Parallel batch CBF velocity filter for multi-robot fleets

get_cbf_safety_report

✅

Full safety audit of current robot state

principia_status

✅

Server status and capability report

principia_benchmark

✅

QP solver performance benchmark

🧬 File Structure

principia-robotica/
├── principia/
│   ├── __init__.py           # Package metadata
│   ├── server.py             # MCP JSON-RPC 2.0 server (entry point)
│   ├── cbf_engine.py         # CBF-QP solver + robot models
│   ├── world_model.py        # Kinematic trajectory predictor + Lyapunov
│   ├── tools.py              # MCP tool handler functions
│   ├── ros2_bridge.py        # ROS2 live integration (optional)
│   └── theory_and_proofs.py  # Complete mathematical derivations
├── tests/
│   └── test_principia.py     # Full test suite
├── docs/
│   └── THEORY.md             # LaTeX-formatted mathematical proofs
├── mcp_config.json           # MCP client configuration template
├── pyproject.toml            # Package metadata + build config
├── LICENSE                   # MIT + attribution clause
└── README.md                 # This file

📊 Performance Benchmarks

Operation

Time

Frequency

CBF margin evaluation

< 0.01 ms

> 100,000 Hz

Early exit (safe command)

< 0.05 ms

> 20,000 Hz

CBF-QP solve (CVXPY/OSQP)

< 2 ms

> 500 Hz

Trajectory pre-simulation (3s horizon)

< 5 ms

> 200 Hz

Lyapunov check

< 0.1 ms

> 10,000 Hz

Real-time control loops run at 50–200 Hz. This engine operates at > 500 Hz. ✅

📚 Mathematical References

  1. Ames, A.D., Xu, X., Grizzle, J.W., Tabuada, P. (2017). Control barrier function based quadratic programs for safety critical systems. IEEE Transactions on Automatic Control, 62(8), 3861–3876.

  2. Ames, A.D., Coogan, S., Egerstedt, M., et al. (2019). Control barrier functions: Theory and applications. European Control Conference.

  3. Zafar, A.B. (2026). Principia Robotica: World-first unified MCP+CBF-QP agentic safety engine. GitHub. https://github.com/EngineerAbdullahBinZafar/principia-robotica

👤 Author

Abdullah Bin Zafar
UET Lahore, Pakistan
GitHub: @EngineerAbdullahBinZafar

If this helped you, please ⭐ the repo. It costs you nothing and means everything.

© 2026 Abdullah Bin Zafar — MIT License
All derivative works must attribute the original author.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

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

  • PlanWright

    Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.

  • llm-bus

    Coordinate multiple AI agents over MCP: atomic claims, leases, shared ledger, handoffs, tasks.

  • Hail

    Phone, SMS & email for AI agents — one remote MCP endpoint, OAuth login, zero install.

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