io.github.JonesRobM/physbound

Physical Layer Linter — An MCP server that validates RF and physics calculations against hard physical limits. Catches AI hallucinations in engineering workflows.

What LLMs Get Wrong

LLMs routinely hallucinate physics. PhysBound catches it:

Generated automatically by pytest tests/test_marketing.py -s

Quick Start

Install

pip install physbound

MCP Client Configuration

Add PhysBound to any MCP-compatible client. For example, in Claude Desktop (claude_desktop_config.json), Cursor, or Windsurf:

{
  "mcpServers": {
    "physbound": {
      "command": "uvx",
      "args": ["physbound"]
    }
  }
}

First run: uvx downloads ~60 MB of dependencies (scipy, numpy) on first launch. Run uvx physbound once in your terminal to pre-cache them — subsequent starts will be instant.

Your AI assistant now has access to physics-validated RF calculations.

Tools

rf_link_budget

Computes a full RF link budget using the Friis transmission equation. Validates antenna gains against aperture limits.

Example: "What's the received power for a 2.4 GHz link at 100 m with 20 dBm TX, 10 dBi TX gain, 3 dBi RX gain?"

Returns: FSPL, received power, wavelength, and optional aperture limit checks. Rejects antenna gains that violate G_max = eta * (pi * D / lambda)^2.

shannon_hartley

Computes Shannon-Hartley channel capacity C = B * log2(1 + SNR) and validates throughput claims.

Example: "Can a 20 MHz channel with 15 dB SNR support 500 Mbps?"

Returns: Theoretical capacity, spectral efficiency, and whether the claim is physically possible. Flags violations with the exact percentage by which the claim exceeds the Shannon limit.

noise_floor

Computes thermal noise power N = k_B * T * B, cascades noise figures through multi-stage receivers using the Friis noise formula, and calculates receiver sensitivity.

Example: "What's the noise floor for a 1 MHz receiver at 290K with a two-stage LNA chain?"

Returns: Thermal noise in dBm and watts, cascaded noise figure, system noise temperature, and receiver sensitivity.

radar_range

Computes the monostatic radar range equation R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min L)]^(1/4) and validates detection range claims.

Example: "Can a 1 kW X-band radar with 30 dBi gain detect a 0.01 m^2 drone at 200 km?"

Returns: Maximum detection range, minimum detectable signal, wavelength, and intermediate values. Catches the common fourth-root fallacy where doubling power is incorrectly assumed to double range.

Physics Guarantees

Every calculation is validated against hard physical limits:

• Speed of light: c = 299,792,458 m/s — no exceptions
• Thermal noise floor: N = -174 dBm/Hz at 290K — the IEEE standard reference
• Shannon limit: C = B * log2(1 + SNR) — no throughput claim exceeds this
• Aperture limit: G_max = eta * (pi * D / lambda)^2 — antenna gain is bounded by physics
• Radar range equation: R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min)]^(1/4) — range obeys the fourth-root law

Violations return structured PhysicalViolationError responses with LaTeX explanations, not silent failures.

Examples

See PhysBound catching hallucinations in real time:

• Catching Hallucinations — walkthrough of four real LLM failure modes with full JSON responses
• Interactive Demo Notebook — hands-on Jupyter notebook calling the physics engines directly

Development

# Clone and install
git clone https://github.com/JonesRobM/physbound.git
cd physbound
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Print hallucination delta table
uv run pytest tests/test_marketing.py -s

# Start MCP server locally
uv run physbound

Why PhysBound?

AI coding assistants are increasingly used in RF engineering, telecommunications, and signal processing workflows. But LLMs have no intrinsic understanding of physics. They generate plausible-sounding numbers that can violate fundamental laws like Shannon-Hartley, thermodynamic noise limits, and antenna aperture bounds.

PhysBound acts as a physics guardrail for any MCP-compatible AI assistant. Every calculation is checked against CODATA physical constants via SciPy, with dimensional analysis enforced through Pint. Violations return structured errors with LaTeX explanations, not silent failures.

Use cases

• RF system design review — validate link budgets, receiver sensitivity, and noise cascades
• Telecom proposal vetting — catch impossible throughput claims before they reach a customer
• Educational tools — teach Shannon-Hartley, Friis transmission, and thermal noise with verified calculations
• CI/CD for physics — integrate as a validation step in engineering pipelines

Support

If PhysBound is useful in your work, consider buying me a coffee.

License

MIT License. See LICENSE.

Related

• Model Context Protocol — the open standard for AI tool integration
• MCP Server Registry — official directory of MCP servers
• FastMCP — Python framework for building MCP servers