From 21f4f0976e6e44a383bdfd0d3d58c6bfd5f68cbb Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Tue, 3 Feb 2026 09:10:37 -0700
Subject: [PATCH] Add README

Covers installation, all 78 tools organized by category, 15 prompts,
web UI setup, and cross-server integration with mcpositioner.
---
 README.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..13041c3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,108 @@
+# mcnanovna
+
+MCP server for controlling NanoVNA-H vector network analyzers over USB serial.
+
+Provides 78 tools for frequency sweeps, S-parameter measurements, calibration, LCD capture, RF analysis, 3D antenna radiation pattern visualization, and pattern import from external files.
+
+## Installation
+
+```bash
+# From PyPI (when published)
+uvx mcnanovna
+
+# From source
+uv run mcnanovna
+
+# With optional web UI for 3D pattern visualization
+uv sync --extra webui
+MCNANOVNA_WEB_PORT=8080 uv run mcnanovna
+```
+
+## Quick Start
+
+Just plug in your NanoVNA-H and start the server. The device auto-connects on first tool call.
+
+```bash
+# Add to Claude Code
+claude mcp add mcnanovna -- uvx mcnanovna
+```
+
+Then ask Claude to scan your antenna, analyze a filter, or measure a crystal.
+
+## Tools
+
+### Measurement
+`info`, `sweep`, `scan`, `data`, `frequencies`, `marker`, `cal`, `save`, `recall`, `pause`, `resume`
+
+### Configuration
+`power`, `bandwidth`, `edelay`, `s21offset`, `vbat`, `capture`, `measure`, `config`, `saveconfig`, `clearconfig`, `color`, `freq`, `tcxo`, `vbat_offset`, `threshold`
+
+### Display
+`trace`, `transform`, `smooth`, `touchcal`, `touchtest`, `refresh`, `touch`, `release`
+
+### Device
+`reset`, `version`, `detect`, `disconnect`, `raw_command`, `cw`, `sd_list`, `sd_read`, `sd_delete`, `time`
+
+### Diagnostics
+`i2c`, `si`, `lcd`, `threads`, `stat`, `sample`, `test`, `gain`, `dump`, `port`, `offset`, `dac`, `usart_cfg`, `usart`, `band`
+
+### Analysis
+`analyze`, `export_touchstone`, `export_csv`, `analyze_filter`, `analyze_xtal`, `analyze_tdr`, `analyze_component`, `analyze_lc_series`, `analyze_lc_shunt`, `analyze_lc_match`, `analyze_s11_resonance`
+
+### Radiation Patterns
+`radiation_pattern`, `radiation_pattern_from_data`, `radiation_pattern_multi`
+
+### Pattern Import
+`import_pattern_csv`, `import_pattern_emcar`, `import_pattern_nec2`, `import_pattern_s1p`, `list_pattern_formats`
+
+## Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `calibrate` | SOLT calibration walkthrough |
+| `export_touchstone` | S-parameter export to .s1p/.s2p |
+| `analyze_antenna` | SWR, impedance, bandwidth analysis |
+| `measure_cable` | TDR and cable characterization |
+| `analyze_crystal` | Crystal motional parameter extraction |
+| `analyze_filter_response` | Filter type classification and cutoffs |
+| `measure_tdr` | Time domain reflectometry |
+| `compare_sweeps` | Before/after comparison |
+| `measure_component` | Unknown L/C/R identification |
+| `measure_lc_series` | Series LC resonator measurement |
+| `measure_lc_shunt` | Shunt LC resonator measurement |
+| `impedance_match` | L-network matching design |
+| `visualize_radiation_pattern` | 3D pattern from S11 scan |
+| `import_pattern` | Load patterns from CSV/EMCAR/NEC2/S1P |
+| `measure_antenna_range` | Automated 3D pattern with positioner |
+
+## Web UI
+
+Enable the optional 3D radiation pattern viewer:
+
+```bash
+uv sync --extra webui
+MCNANOVNA_WEB_PORT=8080 uv run mcnanovna
+```
+
+Open http://localhost:8080 for an interactive Three.js visualization of antenna patterns.
+
+## Antenna Positioner Integration
+
+For automated 3D pattern measurement, use together with [mcpositioner](../mcpositioner/):
+
+```bash
+claude mcp add mcpositioner -- uvx mcpositioner
+claude mcp add mcnanovna -- uvx mcnanovna
+```
+
+The `measure_antenna_range` prompt guides through the cross-server workflow.
+
+## Supported Hardware
+
+- NanoVNA-H (original)
+- NanoVNA-H4
+- Other variants using the same USB serial protocol (VID 0x0483, PID 0x5740)
+
+## License
+
+MIT