Physbound

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

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

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

Returns thermal noise in dBm and watts, cascaded noise figure, effective input noise temperature T_e = 290 K * (F - 1), 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 that doubling power doubles range.

antenna_gain

Analyses a single antenna from its diameter or physical area: gain limits, beamwidth, and far-field distance, with optional validation of a claimed gain.

Example: "Can a 0.5 m dish at 12 GHz really give 50 dBi? What beamwidth should I expect?"

Returns the physical gain limit (aperture or Harrington bound, and which one governs), typical gain at the given efficiency (default 0.55), effective aperture, half-power beamwidth estimates, far-field distance 2D^2/lambda, and — for a claimed gain — the implied aperture efficiency and validity.

radar_ambiguity

Computes pulse-Doppler ambiguity limits for a given carrier frequency and PRF.

Example: "Can a 10 GHz radar at 10 kHz PRF unambiguously measure a 500 m/s target out to 150 km?"

Returns unambiguous range R_ua = c / (2 PRF), unambiguous velocity v_ua = lambda PRF / 4, blind speed, Doppler shift and apparent (aliased) velocity, range resolution (c tau / 2, or c / 2B with pulse compression), minimum range, duty cycle, and the range-Doppler dilemma invariant R_ua v_ua = c lambda / 8. Rejects range, velocity, or resolution claims the PRF or pulse cannot support.

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 290 K — the IEEE standard reference
• Shannon limit: C = B log2(1 + SNR) — no throughput claim exceeds this
• Antenna gain limit: G_max = max((pi D / lambda)^2, (ka)^2 + 2ka) — the eta = 1 aperture value for planar apertures and Harrington's bound for any antenna in a sphere of diameter D; eta = 0.55 is a warning threshold, not a limit
• Radar range equation: R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min)]^(1/4) — range obeys the fourth-root law
• Receiver sensitivity: S_min = k (T_A + T_0 (F - 1)) B * SNR with T_e = T_0 (F - 1) referenced to 290 K
• Unambiguous range: R_ua = c / (2 PRF) — echoes beyond it fold into a later pulse interval
• Unambiguous velocity: v_ua = lambda PRF / 4 — Doppler is sampled at the PRF, so |f_d| <= PRF/2
• Range-Doppler dilemma: R_ua * v_ua = c lambda / 8 — no PRF choice beats it for a given carrier

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

Examples and Documentation

• Catching Hallucinations — walkthrough of five real LLM failure modes with full JSON responses
• Interactive Demo Notebook — Jupyter notebook calling the physics engines directly
• Formula Reference — every formula, constant, and validation guard with sources
• Changelog — release history

Development

Requires uv and Python 3.12+ (CI covers 3.12–3.14):

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

# Run checks
uv run pytest tests/ -v
uv run ruff check src/ tests/
uv run mypy src/physbound/

# Regenerate the hallucination table above
uv run pytest tests/test_marketing.py -s

# Start the MCP server locally
uv run physbound

Contributions that expand the set of validated physics domains are welcome — see CONTRIBUTING.md for the architecture guide and the step-by-step recipe for adding a new validator.

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
• Radar system sizing — sanity-check detection range, PRF selection, and ambiguity trade-offs
• 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