Document uvx as the zero-install path for LabLink

[techmanual-ai]

What changed

README.md, Install section. It now starts with a uvx quickstart, placed before the pip install block. With only uv on the machine, a reader goes from plugging in an instrument to a connected session in two commands, without creating a virtualenv:

uvx --python 3.12 --from "lablink-mcp[visa,serial]" lablink scan --write-configs
uvx --python 3.12 --from "lablink-mcp[visa,serial]" lablink connect tektronix_mso44

The section explains:

• how --from "lablink-mcp[extras]" works;
• which of the three entry points in pyproject.toml to name after it (lablink, lablink-mcp, lablink-sim);
• why the quotes are needed;
• why --python 3.12 is there.

It also gives uv tool install for readers who want the bare lablink … commands used in the rest of the README. pip stays as the development path.

README.md, Quick Start step 5 (MCP client config). The existing format and both targeted clients (Claude Code and Claude Desktop) are unchanged. The JSON now uses "command": "uvx" with an args array. A short note covers the pip / uv tool install form ("command": "lablink-mcp") and what to do when the client can't find the command.

docs/ARCHITECTURE.md §9. It said uv "installs and manages Python itself." That isn't true unless you pin a version, so §9 now says what a user actually needs, and it matches the README.

Quoted extras specs. The existing pip install lablink-mcp[visa] lines are now quoted. Unquoted brackets fail with no matches found under zsh, the macOS default shell.

Why the --python 3.12 pin

I found this during verification. On this machine, before any uv-managed Python was installed, uvx --from "lablink-mcp[visa]" lablink --help picked Apple's /usr/bin/python3 (3.9.6). It then failed with "current Python version (3.9.6) does not satisfy Python>=3.10" rather than downloading a compatible Python. With --python 3.12, uv downloaded CPython 3.12.12 and the command ran. A stock Mac is exactly the stranger this page is for, so every documented command carries the pin.

How it was verified (uv 0.10.4)

• lablink --help, from PyPI and the local checkout. Run through uvx --python 3.12 --from "lablink-mcp[visa]" …. Both resolve.
• scan --write-configs from the local checkout. Runs and exits 0. No hardware was attached, so it reported "No devices found"; I couldn't test the case where an instrument actually answers.
• connect against lablink-sim. uvx … lablink connect sim_fgen with the simulator itself started through uvx. Returned Connected: LabLink,FG-100,SIMFG001,0.2.0.
• MCP server with extras. Launched through uvx with the exact JSON args, over stdio. It lists visa_* and serial_* tools.
• MCP server without extras. Lists neither, which is the basis for the "same extras in both places" note. Against the local checkout, connect("sim_fgen") through the server also succeeded.
• uv tool install --python 3.12 "lablink-mcp[visa,serial]". Run into temporary directories; it installs lablink, lablink-mcp and lablink-sim.
• Test suite. .venv/bin/python -m pytest -q: 393 passed before and after the change.

Assumptions and caveats

• The scan step won't work from PyPI until the next release. PyPI's latest is 0.2.0, which predates lablink scan. uvx … lablink scan fails against PyPI today. It works against the code on main. The README already documents scan and visa_read, which are unreleased too, so I followed that practice rather than adding a version note.
• The examples use [visa,serial], not just [visa]. scan covers both VISA and serial ports. With only [visa] it skips the serial ports and says so.
• No CHANGELOG entry. The change is docs-only, as the task specified.
• No agent_development.md update. There was no new general rule worth adding.
• Out of scope, worth a follow-up. The install hints the code prints (for example Run: pip install lablink-mcp[serial] from scan and diagnose) are still pip-style and unquoted. Tests assert on those exact strings, so I left them alone.

---

🤖 Generated with Claude Code