serial-console-mcp 0.1.0__tar.gz

serial_console_mcp-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+.pytest_cache/
+*.py[cod]
+.venv/
+venv/
+
+# PyInstaller
+build/
+dist/
+*.spec
+
+# Installer build artifacts
+Output/
+pkgroot/
+*.pkg
+*-component.pkg
+
+# OS
+.DS_Store

serial_console_mcp-0.1.0/BUILD.md

@@ -0,0 +1,116 @@
+# BUILD — making the two installers
+
+Goal: a single file the user double-clicks. No Python, no terminal, no JSON.
+Everything here is wired up; you mostly just run it.
+
+## Why not a `.mcpb`?
+
+A `.mcpb` extension runs in Claude Desktop's sandbox — no LAN, no `/dev/cu.*`, no
+COM ports. So it can't drive serial. The install therefore registers a **host
+stdio subprocess** (the route that works for reaching real hardware), but hides
+every manual step inside a clicker.
+
+## One binary, two jobs
+
+The `serial_console_mcp` package (entry script `packaging/entry.py`) is frozen
+into a single executable:
+- launched with **no args** -> runs the MCP stdio server (what Claude calls);
+- launched as **`serial-console-mcp configure --command <self>`** -> writes the
+  `claude_desktop_config.json` entry and exits (what the installer calls).
+
+The configurator merges into existing servers (won't touch your other MCP
+entries) and backs up the old file first.
+
+## The one non-obvious trap: elevated installer vs. per-user config
+
+Installer postinstall steps run **elevated** (root on macOS, admin on Windows),
+but Claude's config is per-user. Writing it from the elevated context lands in the
+wrong home and silently does nothing. Both installers correct for this:
+- **Windows:** the `[Run]` entry has `Flags: runasoriginaluser`. Inno does not allow
+  that flag in `[UninstallRun]`, so the uninstall-time `configure --remove` runs
+  elevated; it only reaches the right profile when the admin account is the user's
+  own (the usual single-user PC). Otherwise the stale entry is harmless: Claude
+  Desktop shows the server as unavailable until it is removed by hand.
+- **macOS:** `scripts/postinstall` finds the console user and runs the configurator
+  as them via `launchctl asuser <uid> sudo -u <user> ... --config-home <home>`.
+
+## Windows  ->  SerialConsoleMCP-Setup.exe
+
+```
+python -m venv .venv && .venv\Scripts\activate
+pip install ".[freeze]"
+pyinstaller --onefile --name serial-console-mcp --collect-all mcp --collect-all serial_console_mcp packaging/entry.py
+```
+Then compile `installer.iss` with Inno Setup (free). Output:
+`Output\SerialConsoleMCP-Setup.exe`. Edit `AppPublisher` (your name/callsign) and,
+if you have a code-signing cert, add a `SignTool` directive to avoid SmartScreen
+warnings (optional; unsigned works, just warns).
+
+## macOS  ->  SerialConsoleMCP-0.1.0.pkg
+
+Unsigned (testing):
+```
+./build_macos.sh
+```
+Signed + notarized (on your Mac, with your Developer ID):
+```
+SIGN_IDENTITY_APP="Developer ID Application: Your Name (TEAMID)" \
+SIGN_IDENTITY_INSTALLER="Developer ID Installer: Your Name (TEAMID)" \
+NOTARY_PROFILE="AC" \
+./build_macos.sh
+```
+`NOTARY_PROFILE` is a `notarytool store-credentials` keychain profile. The
+package identifier is `org.stefanbrunner.serialconsolemcp` (override with
+`IDENTIFIER=...`). Uninstall: `./uninstall_macos.sh`.
+
+## PyPI
+
+`.github/workflows/release.yml` publishes the sdist and wheel to PyPI with
+Trusted Publishing (OIDC, no API token) whenever a GitHub Release is published.
+The tag must equal `v` + the version in `pyproject.toml`; the workflow checks.
+Release steps:
+
+```
+# bump version in pyproject.toml and src/serial_console_mcp/__init__.py, update CHANGELOG.md
+git tag vX.Y.Z && git push origin vX.Y.Z          # builds the installers
+gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <(sed -n '/^## \[X.Y.Z\]/,/^## \[/p' CHANGELOG.md)
+```
+
+One-time setup on pypi.org: Manage project → Publishing → add a trusted publisher
+for `sbrunner-atx/serial-console-mcp`, workflow `release.yml`, environment `release`.
+
+## CI (both at once)
+
+`.github/workflows/build.yml` runs the pytest suite on Linux/macOS/Windows on
+every push and pull request. On a `v*` tag (or manual dispatch) it additionally
+freezes the binary and builds each installer, uploading them as artifacts. PyInstaller isn't a cross-compiler, so this is the easiest way to get
+both from one `git tag`. The Mac job is **unsigned** in CI — for a notarized pkg,
+run `build_macos.sh` locally with your Developer ID, since exporting certs into CI
+is extra ceremony you don't need for a hobby tool.
+
+## Things to personalize if you fork this
+
+- `installer.iss`: `AppPublisher`, `AppId` (generate a new GUID), optional signing.
+- `build_macos.sh` / `uninstall_macos.sh`: `IDENTIFIER`.
+- The server and configurator need no edits.
+
+## Testing against real hardware
+
+`tests/` is the unit suite (fake serial port, runs in CI). `_hosttest/run_live.py`
+is a developer harness that drives the real tool functions against a real port
+from a JSON list of steps, without the MCP transport in the way. It ships a stub
+`mcp` package so it also runs on a host Python older than 3.10; it sends only
+what the step file lists.
+
+## The config entry produced
+
+```json
+{
+  "mcpServers": {
+    "serial-console": {
+      "command": "/Library/Application Support/SerialConsoleMCP/serial-console-mcp",
+      "args": []
+    }
+  }
+}
+```

serial_console_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-14
+
+First public, experimental release.
+
+### Added
+- Eleven tools: `list_serial_ports`, `connect`, `reconnect_last`, `send_text`,
+  `send_hex`, `read_until_prompt`, `read_available`, `query_text`, `clear_buffer`,
+  `status`, `disconnect`.
+- Interactive-console model: a background reader drains the port into a buffer
+  from the moment it opens; reads match a literal or regex prompt and push
+  leftover bytes back, or return once the line goes idle.
+- Every Quick-Connect setting on `connect`: baud, data bits, parity, stop bits,
+  RTS/CTS and XON/XOFF. Default 9600 8N1, no flow control. Settings are
+  remembered for `reconnect_last`.
+- Console script `serial-console-mcp`; `serial-console-mcp configure` writes the
+  Claude Desktop config entry (merging, with backup) and `--remove` undoes it.
+- Windows (Inno Setup) and macOS (.pkg) installers built by CI on `v*` tags.
+- The serial-console-mcp Field Guide (`docs/`).
+- 37-case test suite on a simulated serial port; CI on Linux, macOS, Windows.
+
+### Notes
+- The MCP SDK is pinned `<2`; the 2.x line removed `mcp.server.fastmcp`.
+- A dead reader (unplugged adapter) is reported by every tool instead of a
+  silent timeout; the receive buffer is capped at 4 MB.
+- Verified with the simulated port and a live MCP stdio handshake. A run against
+  physical hardware is the next milestone.

serial_console_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Brunner (AE5VG)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

serial_console_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: serial-console-mcp
+Version: 0.1.0
+Summary: An MCP server that lets Claude Desktop drive a serial console: network craft ports, CAT radios, Icom CI-V, rotators, microcontrollers.
+Project-URL: Homepage, https://github.com/sbrunner-atx/serial-console-mcp
+Project-URL: Repository, https://github.com/sbrunner-atx/serial-console-mcp
+Project-URL: Issues, https://github.com/sbrunner-atx/serial-console-mcp/issues
+Project-URL: Field Guide, https://github.com/sbrunner-atx/serial-console-mcp/blob/main/docs/serial-console-mcp%20Field%20Guide.pdf
+Author-email: "Stefan Brunner (AE5VG)" <me@stefanbrunner.org>
+License: MIT
+License-File: LICENSE
+Keywords: cat,ci-v,console,craft-port,ham-radio,mcp,model-context-protocol,pyserial,serial,serial-port
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Ham Radio
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Terminals :: Serial
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.2.0
+Requires-Dist: pyserial>=3.5
+Provides-Extra: freeze
+Requires-Dist: mcp[cli]<2,>=1.2.0; extra == 'freeze'
+Requires-Dist: pyinstaller>=6.0; extra == 'freeze'
+Description-Content-Type: text/markdown
+
+# serial-console-mcp
+
+**Let Claude drive your serial console.**
+
+[![build](https://github.com/sbrunner-atx/serial-console-mcp/actions/workflows/build.yml/badge.svg)](https://github.com/sbrunner-atx/serial-console-mcp/actions/workflows/build.yml)
+[![PyPI](https://img.shields.io/pypi/v/serial-console-mcp.svg)](https://pypi.org/project/serial-console-mcp/)
+&nbsp;MIT licensed &nbsp;·&nbsp; Python 3.10+ &nbsp;·&nbsp; **status: experimental (0.1.0)**
+
+This adds a few tools to **Claude Desktop** so you can talk to anything on a serial
+port — a network device's console/craft port (Juniper, Cisco, etc.), a radio,
+rotator, amplifier, antenna switch, or a microcontroller — just by *asking Claude*.
+
+You do **not** need to know any programming. After it's installed you talk to Claude
+normally:
+
+> **You:** What serial ports do you see?
+> **Claude:** I found two. One looks like a Silicon Labs CP210x on COM4 — that's
+> probably your device.
+>
+> **You:** Connect to COM4 at 9600 baud.
+> **Claude:** Connected.
+>
+> **You:** Log in and show me the version.
+
+## How it works (the important part)
+
+A serial console isn't a simple question-and-answer channel. It echoes what you
+type, prints unsolicited messages on its own (logs, interface flaps), and can dump
+pages of output. So the moment a port is open, a background reader keeps draining
+it into a buffer. That means Claude can:
+
+- **send** a command (writes only — doesn't guess when the reply is done), then
+- **read until a prompt** appears (`# `, `> `, `login:` …) to capture the whole
+  reply — even a long one — without cutting it off, or
+- **read whatever's waiting** for streaming/unsolicited output.
+
+This is the same model `minicom` and `expect` use, which is why it handles
+interactive CLIs properly.
+
+### The tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_serial_ports` | Enumerate ports with description and USB hardware id |
+| `connect` / `reconnect_last` / `disconnect` | Open a port. Defaults to 9600 8N1, no flow control; baud, data bits, parity, stop bits, RTS/CTS and XON/XOFF are all settable by asking. Remembers the last one |
+| `send_text` | Write an ASCII command with CR / LF / CRLF / no line ending. Write-only |
+| `send_hex` | Write raw bytes given as hex (Icom CI-V and other binary protocols) |
+| `read_until_prompt` | Return buffered output up to a literal or regex prompt, leaving the rest |
+| `read_available` | Return whatever has arrived, as text and hex |
+| `query_text` | Clear, send, then read until a prompt or until the line goes idle |
+| `clear_buffer` / `status` | Housekeeping |
+
+One port is open at a time. The receive buffer is capped at 4 MB; if a device
+streams for hours unread, the oldest bytes are dropped and `status` says how many.
+
+## The Field Guide
+
+[serial-console-mcp Field Guide (PDF)](docs/serial-console-mcp%20Field%20Guide.pdf) is the
+operator's manual: what each tool does, every connection setting said in plain
+language, the console rules, a per-device playbook (craft ports, text CAT,
+Icom CI-V, rotators and microcontrollers), four worked sessions, and a
+troubleshooting table. Source is `docs/brand/` (HTML + CSS, rendered with
+WeasyPrint).
+
+## Installing
+
+1. Download the installer for your computer from the
+   [Releases page](https://github.com/sbrunner-atx/serial-console-mcp/releases)
+   (the `.exe` on Windows, or the `.pkg` on a Mac) and click through it like any
+   normal program. It sets everything up for you. The installers are unsigned for
+   now, so expect a Gatekeeper / SmartScreen warning.
+2. **Completely quit Claude Desktop** — not just closing the window. On Windows,
+   right-click the Claude icon near the clock and choose Quit. On a Mac, press
+   ⌘Q or choose **Claude → Quit**.
+3. Open Claude Desktop again.
+4. In a new chat, type: **"What serial ports do you see?"** If Claude lists your
+   ports, you're done.
+
+That's the whole thing. There's no separate program to keep open and nothing to
+configure by hand.
+
+## Installing from PyPI
+
+If you already have Python 3.10+ and [uv](https://docs.astral.sh/uv/) or pipx,
+you don't need the installer:
+
+```bash
+uvx serial-console-mcp --version                                   # fetches and runs it
+uvx serial-console-mcp configure --command uvx --arg serial-console-mcp
+```
+
+or
+
+```bash
+pipx install serial-console-mcp
+serial-console-mcp configure --command "$(which serial-console-mcp)"
+```
+
+`configure` writes a `serial-console` entry into `claude_desktop_config.json`
+(merging with whatever is already there and backing the old file up first).
+Quit and reopen Claude Desktop. `serial-console-mcp configure --remove` undoes
+it. Any other MCP client can launch the same command over stdio.
+
+## Installing from source (developers)
+
+```bash
+git clone https://github.com/sbrunner-atx/serial-console-mcp.git
+cd serial-console-mcp
+uv sync                       # or: python3 -m venv .venv && . .venv/bin/activate && pip install -e . pytest
+uv run pytest                 # fake serial port, no hardware needed
+uv run serial-console-mcp configure --command "$PWD/.venv/bin/serial-console-mcp"
+```
+
+The package lives in `src/serial_console_mcp/`: `server.py` is the MCP server,
+`configure.py` the Claude Desktop registrar. See [BUILD.md](BUILD.md) for the
+installers.
+
+## Using it
+
+Plain-English requests work. Some examples:
+
+- "List my serial ports."
+- "Connect to the console on /dev/cu.usbserial-10 at 9600 baud."
+- "Connect to /dev/cu.BLTH at 38400, 8 data bits, no parity, 1 stop bit, XON/XOFF flow control."
+- "Reconnect to the same port as last time." (it remembers)
+- "Send a return, then read until the login prompt."
+- "Log in as admin and run `show interfaces terse`, then show me all of it."
+- "Just read whatever the device is printing right now."
+- "Disconnect when you're done."
+
+For a router/switch console, tell Claude the prompt it should wait for (often `# `
+for enable mode or `> ` for user mode) and it will read until it sees it. For an
+Icom radio (CI-V), tell Claude — it can send the hex commands those radios expect.
+
+## If something doesn't work
+
+**"No serial ports found."**
+- Is the device turned on?
+- Is the USB cable a real *data* cable, not a charge-only one? (A very common gotcha.)
+- On Windows, open Device Manager and look under **Ports (COM & LPT)**. If nothing's
+  there, Windows needs the cable's driver (often FTDI, CP210x, or CH340).
+
+**"Could not open the port" / "access denied."**
+- A serial port can only be used by one program at a time. Close anything else that
+  might be holding it: a terminal (PuTTY/minicom/screen), WSJT-X, your contest
+  logger, the device's own software.
+
+**Claude says it can't access serial ports at all.**
+- Make sure you fully quit and reopened Claude Desktop after installing.
+- Start a brand-new chat and ask "What serial ports do you see?" again.
+
+**It connected but a command gets no reply.**
+- Almost always the **baud rate** is wrong, or the **line ending** is wrong for your
+  gear. Most Unix-style consoles want a plain newline (LF); most rigs want a carriage
+  return (CR). Ask Claude to send a return first to draw a fresh prompt.
+
+## A word on safety
+
+These tools send exactly what you (through Claude) ask them to send, to whatever
+device is on the cable. Claude Desktop asks you to approve each tool call, so you
+see every command before it runs. Read it. A console session on a router or a
+rig can reconfigure, reboot, or transmit, and this server does not try to guess
+which commands are dangerous. If something looks wrong, decline it, and keep a
+real terminal handy for anything you would not want an assistant to type.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+73!

serial_console_mcp-0.1.0/README.md

@@ -0,0 +1,170 @@
+# serial-console-mcp
+
+**Let Claude drive your serial console.**
+
+[![build](https://github.com/sbrunner-atx/serial-console-mcp/actions/workflows/build.yml/badge.svg)](https://github.com/sbrunner-atx/serial-console-mcp/actions/workflows/build.yml)
+[![PyPI](https://img.shields.io/pypi/v/serial-console-mcp.svg)](https://pypi.org/project/serial-console-mcp/)
+ MIT licensed  ·  Python 3.10+  ·  **status: experimental (0.1.0)**
+
+This adds a few tools to **Claude Desktop** so you can talk to anything on a serial
+port — a network device's console/craft port (Juniper, Cisco, etc.), a radio,
+rotator, amplifier, antenna switch, or a microcontroller — just by *asking Claude*.
+
+You do **not** need to know any programming. After it's installed you talk to Claude
+normally:
+
+> **You:** What serial ports do you see?
+> **Claude:** I found two. One looks like a Silicon Labs CP210x on COM4 — that's
+> probably your device.
+>
+> **You:** Connect to COM4 at 9600 baud.
+> **Claude:** Connected.
+>
+> **You:** Log in and show me the version.
+
+## How it works (the important part)
+
+A serial console isn't a simple question-and-answer channel. It echoes what you
+type, prints unsolicited messages on its own (logs, interface flaps), and can dump
+pages of output. So the moment a port is open, a background reader keeps draining
+it into a buffer. That means Claude can:
+
+- **send** a command (writes only — doesn't guess when the reply is done), then
+- **read until a prompt** appears (`# `, `> `, `login:` …) to capture the whole
+  reply — even a long one — without cutting it off, or
+- **read whatever's waiting** for streaming/unsolicited output.
+
+This is the same model `minicom` and `expect` use, which is why it handles
+interactive CLIs properly.
+
+### The tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_serial_ports` | Enumerate ports with description and USB hardware id |
+| `connect` / `reconnect_last` / `disconnect` | Open a port. Defaults to 9600 8N1, no flow control; baud, data bits, parity, stop bits, RTS/CTS and XON/XOFF are all settable by asking. Remembers the last one |
+| `send_text` | Write an ASCII command with CR / LF / CRLF / no line ending. Write-only |
+| `send_hex` | Write raw bytes given as hex (Icom CI-V and other binary protocols) |
+| `read_until_prompt` | Return buffered output up to a literal or regex prompt, leaving the rest |
+| `read_available` | Return whatever has arrived, as text and hex |
+| `query_text` | Clear, send, then read until a prompt or until the line goes idle |
+| `clear_buffer` / `status` | Housekeeping |
+
+One port is open at a time. The receive buffer is capped at 4 MB; if a device
+streams for hours unread, the oldest bytes are dropped and `status` says how many.
+
+## The Field Guide
+
+[serial-console-mcp Field Guide (PDF)](docs/serial-console-mcp%20Field%20Guide.pdf) is the
+operator's manual: what each tool does, every connection setting said in plain
+language, the console rules, a per-device playbook (craft ports, text CAT,
+Icom CI-V, rotators and microcontrollers), four worked sessions, and a
+troubleshooting table. Source is `docs/brand/` (HTML + CSS, rendered with
+WeasyPrint).
+
+## Installing
+
+1. Download the installer for your computer from the
+   [Releases page](https://github.com/sbrunner-atx/serial-console-mcp/releases)
+   (the `.exe` on Windows, or the `.pkg` on a Mac) and click through it like any
+   normal program. It sets everything up for you. The installers are unsigned for
+   now, so expect a Gatekeeper / SmartScreen warning.
+2. **Completely quit Claude Desktop** — not just closing the window. On Windows,
+   right-click the Claude icon near the clock and choose Quit. On a Mac, press
+   ⌘Q or choose **Claude → Quit**.
+3. Open Claude Desktop again.
+4. In a new chat, type: **"What serial ports do you see?"** If Claude lists your
+   ports, you're done.
+
+That's the whole thing. There's no separate program to keep open and nothing to
+configure by hand.
+
+## Installing from PyPI
+
+If you already have Python 3.10+ and [uv](https://docs.astral.sh/uv/) or pipx,
+you don't need the installer:
+
+```bash
+uvx serial-console-mcp --version                                   # fetches and runs it
+uvx serial-console-mcp configure --command uvx --arg serial-console-mcp
+```
+
+or
+
+```bash
+pipx install serial-console-mcp
+serial-console-mcp configure --command "$(which serial-console-mcp)"
+```
+
+`configure` writes a `serial-console` entry into `claude_desktop_config.json`
+(merging with whatever is already there and backing the old file up first).
+Quit and reopen Claude Desktop. `serial-console-mcp configure --remove` undoes
+it. Any other MCP client can launch the same command over stdio.
+
+## Installing from source (developers)
+
+```bash
+git clone https://github.com/sbrunner-atx/serial-console-mcp.git
+cd serial-console-mcp
+uv sync                       # or: python3 -m venv .venv && . .venv/bin/activate && pip install -e . pytest
+uv run pytest                 # fake serial port, no hardware needed
+uv run serial-console-mcp configure --command "$PWD/.venv/bin/serial-console-mcp"
+```
+
+The package lives in `src/serial_console_mcp/`: `server.py` is the MCP server,
+`configure.py` the Claude Desktop registrar. See [BUILD.md](BUILD.md) for the
+installers.
+
+## Using it
+
+Plain-English requests work. Some examples:
+
+- "List my serial ports."
+- "Connect to the console on /dev/cu.usbserial-10 at 9600 baud."
+- "Connect to /dev/cu.BLTH at 38400, 8 data bits, no parity, 1 stop bit, XON/XOFF flow control."
+- "Reconnect to the same port as last time." (it remembers)
+- "Send a return, then read until the login prompt."
+- "Log in as admin and run `show interfaces terse`, then show me all of it."
+- "Just read whatever the device is printing right now."
+- "Disconnect when you're done."
+
+For a router/switch console, tell Claude the prompt it should wait for (often `# `
+for enable mode or `> ` for user mode) and it will read until it sees it. For an
+Icom radio (CI-V), tell Claude — it can send the hex commands those radios expect.
+
+## If something doesn't work
+
+**"No serial ports found."**
+- Is the device turned on?
+- Is the USB cable a real *data* cable, not a charge-only one? (A very common gotcha.)
+- On Windows, open Device Manager and look under **Ports (COM & LPT)**. If nothing's
+  there, Windows needs the cable's driver (often FTDI, CP210x, or CH340).
+
+**"Could not open the port" / "access denied."**
+- A serial port can only be used by one program at a time. Close anything else that
+  might be holding it: a terminal (PuTTY/minicom/screen), WSJT-X, your contest
+  logger, the device's own software.
+
+**Claude says it can't access serial ports at all.**
+- Make sure you fully quit and reopened Claude Desktop after installing.
+- Start a brand-new chat and ask "What serial ports do you see?" again.
+
+**It connected but a command gets no reply.**
+- Almost always the **baud rate** is wrong, or the **line ending** is wrong for your
+  gear. Most Unix-style consoles want a plain newline (LF); most rigs want a carriage
+  return (CR). Ask Claude to send a return first to draw a fresh prompt.
+
+## A word on safety
+
+These tools send exactly what you (through Claude) ask them to send, to whatever
+device is on the cable. Claude Desktop asks you to approve each tool call, so you
+see every command before it runs. Read it. A console session on a router or a
+rig can reconfigure, reboot, or transmit, and this server does not try to guess
+which commands are dangerous. If something looks wrong, decline it, and keep a
+real terminal handy for anything you would not want an assistant to type.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+73!

serial_console_mcp-0.1.0/build_macos.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# Build a (optionally signed + notarized) macOS .pkg.
+#
+# Unsigned local/CI build:   ./build_macos.sh
+# Signed + notarized build (on your Mac with your Developer ID):
+#   SIGN_IDENTITY_APP="Developer ID Application: Your Name (TEAMID)" \
+#   SIGN_IDENTITY_INSTALLER="Developer ID Installer: Your Name (TEAMID)" \
+#   NOTARY_PROFILE="AC"  ./build_macos.sh
+set -euo pipefail
+
+APP_NAME="serial-console-mcp"
+VERSION="${VERSION:-0.1.0}"
+IDENTIFIER="${IDENTIFIER:-org.stefanbrunner.serialconsolemcp}"
+INSTALL_LOCATION="/Library/Application Support/SerialConsoleMCP"
+
+python3 -m venv .venv
+# shellcheck disable=SC1091
+source .venv/bin/activate
+pip install --quiet ".[freeze]"
+pyinstaller --onefile --name "$APP_NAME" --collect-all mcp --collect-all serial_console_mcp packaging/entry.py
+
+# Sign the Mach-O with hardened runtime (required for notarization).
+if [ -n "${SIGN_IDENTITY_APP:-}" ]; then
+  codesign --force --options runtime --timestamp \
+    --sign "$SIGN_IDENTITY_APP" "dist/$APP_NAME"
+else
+  echo "WARN: SIGN_IDENTITY_APP not set -> unsigned binary (fine for testing)."
+fi
+
+rm -rf pkgroot
+mkdir -p "pkgroot${INSTALL_LOCATION}"
+cp "dist/$APP_NAME" "pkgroot${INSTALL_LOCATION}/"
+chmod +x "pkgroot${INSTALL_LOCATION}/$APP_NAME"
+chmod +x scripts/postinstall
+
+pkgbuild --root pkgroot \
+  --identifier "$IDENTIFIER" \
+  --version "$VERSION" \
+  --scripts scripts \
+  --install-location "/" \
+  "SerialConsoleMCP-component.pkg"
+
+productbuild --package "SerialConsoleMCP-component.pkg" "SerialConsoleMCP-$VERSION.pkg"
+rm -f "SerialConsoleMCP-component.pkg"  # intermediate; keep only the product pkg
+
+if [ -n "${SIGN_IDENTITY_INSTALLER:-}" ]; then
+  productsign --sign "$SIGN_IDENTITY_INSTALLER" \
+    "SerialConsoleMCP-$VERSION.pkg" "SerialConsoleMCP-$VERSION-signed.pkg"
+  mv "SerialConsoleMCP-$VERSION-signed.pkg" "SerialConsoleMCP-$VERSION.pkg"
+  if [ -n "${NOTARY_PROFILE:-}" ]; then
+    xcrun notarytool submit "SerialConsoleMCP-$VERSION.pkg" \
+      --keychain-profile "$NOTARY_PROFILE" --wait
+    xcrun stapler staple "SerialConsoleMCP-$VERSION.pkg"
+  fi
+else
+  echo "WARN: SIGN_IDENTITY_INSTALLER not set -> unsigned .pkg (Gatekeeper will warn)."
+fi
+
+echo "Built SerialConsoleMCP-$VERSION.pkg"

serial_console_mcp-0.1.0/installer.iss

@@ -0,0 +1,48 @@
+; Inno Setup script for Serial Console MCP (Windows)
+; Build the binary first:  pip install ".[freeze]" && pyinstaller --onefile --name serial-console-mcp --collect-all mcp --collect-all serial_console_mcp packaging/entry.py
+; Then compile this with Inno Setup -> Output\SerialConsoleMCP-Setup.exe
+
+#define MyAppName "Serial Console MCP"
+#define MyAppVersion "0.1.0"
+#define MyAppPublisher "Stefan Brunner (AE5VG)"
+
+[Setup]
+AppId={{B3F1A2C4-7E5D-4A19-9C2B-1D6E8F0A4C77}
+AppName={#MyAppName}
+AppVersion={#MyAppVersion}
+AppPublisher={#MyAppPublisher}
+DefaultDirName={autopf}\SerialConsoleMCP
+DisableProgramGroupPage=yes
+DisableDirPage=yes
+OutputDir=Output
+OutputBaseFilename=SerialConsoleMCP-Setup
+Compression=lzma2
+SolidCompression=yes
+PrivilegesRequired=admin
+ArchitecturesInstallIn64BitMode=x64compatible
+WizardStyle=modern
+
+[Files]
+Source: "dist\serial-console-mcp.exe"; DestDir: "{app}"; Flags: ignoreversion
+
+[Run]
+; Register with Claude Desktop AS THE REAL USER (runasoriginaluser), so %APPDATA%
+; resolves to the logged-in user's profile rather than the elevated admin's.
+Filename: "{app}\serial-console-mcp.exe"; \
+  Parameters: "configure --command ""{app}\serial-console-mcp.exe"""; \
+  Flags: runhidden runasoriginaluser; \
+  StatusMsg: "Registering with Claude Desktop..."
+
+[UninstallRun]
+; Runs before files are removed, so the exe still exists here. Inno does not
+; allow runasoriginaluser in this section, so this runs in the uninstaller's
+; (elevated) context: it cleans the entry when the admin and the user are the
+; same account, which is the common single-user case. Otherwise Claude Desktop
+; simply shows the server as unavailable until the entry is removed by hand.
+Filename: "{app}\serial-console-mcp.exe"; \
+  Parameters: "configure --remove"; \
+  Flags: runhidden; \
+  RunOnceId: "RemoveClaudeEntry"
+
+[Messages]
+FinishedLabel=Setup is done. Now FULLY QUIT Claude Desktop (right-click the tray icon, Quit) and reopen it. Then ask Claude: "What serial ports do you see?"