PhysBound

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

LLMs generate plausible-sounding RF numbers that violate fundamental physics — throughput above the Shannon limit, antenna gains no aperture can produce, radar ranges the range equation forbids. PhysBound gives any MCP-compatible AI assistant six validated calculation tools, backed by CODATA constants (via SciPy) and dimensional analysis (via Pint). Impossible claims return structured PhysicalViolationError responses with the violated law, the computed limit, and a LaTeX explanation — not silent failures.

Installation

PhysBound is a standard stdio MCP server published on PyPI. The recommended launch command is uvx physbound, which fetches and runs the latest release in an isolated environment — no manual install step.

First run: uvx downloads ~60 MB of dependencies (SciPy, NumPy) the first time. Run uvx physbound once in a terminal to pre-cache them (Ctrl-C to exit); subsequent starts are instant.

Claude Code

claude mcp add physbound -- uvx physbound

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

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

Cursor, Windsurf, and other MCP clients

Use the same JSON server entry as above in your client's MCP configuration file (Cursor: ~/.cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json).

Without uv

If you prefer a plain Python install (requires Python 3.12+):

pip install physbound

then set "command": "physbound" (with no args) in the client configuration.

Once configured, ask your assistant an RF question — "Can a 20 MHz channel with 15 dB SNR support 500 Mbps?" — and it will answer with physics-validated numbers.

Command-Line Usage

The same validators are available directly from the terminal — useful in scripts and CI pipelines, since a physics violation exits with code 1:

$ physbound check shannon --bandwidth-hz 20e6 --snr-db 15 --claimed-throughput-bps 500e6
PHYSICS VIOLATION [Shannon-Hartley Theorem]
  Claimed throughput 500000000.0 bps exceeds Shannon limit of 100556153.5 bps by 397.2%
  Computed limit: 1.00556e+08 bps
  Claimed value:  5e+08 bps
$ echo $?
1

$ physbound check shannon --bandwidth-hz 20e6 --snr-db 15 --claimed-throughput-bps 100e6
Shannon-Hartley Capacity: ...   # exit code 0

Available subcommands: check {link-budget, shannon, noise, radar-range, antenna, radar-ambiguity} (flags mirror the MCP tool parameters; add --json for the full structured result) and serve --transport {stdio,http} for running the MCP server over HTTP. See physbound check --help for details.

What LLMs Get Wrong

Sixteen real hallucination patterns, each caught by PhysBound's test suite:

Generated automatically by pytest tests/test_marketing.py -s

Tools

Full derivations, sources, and worked examples for every formula are in docs/formulas.md.

rf_link_budget

Computes a complete RF link budget using the Friis transmission equation and validates antenna gains against physical 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 — when antenna diameters are supplied — gain limit checks. Gains above the hard bound G_max = max((pi D / lambda)^2, (ka)^2 + 2ka) (the eta = 1 aperture value, or Harrington's bound for electrically small antennas) are rejected; gains above the typical dish value (eta = 0.55) are accepted with a warning. Also warns inside the far-field distance 2D^2/lambda and rejects negative losses.

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, including the exact percentage by which a violating claim exceeds the Shannon limit.

noise_floor