serial-mcp-server 0.1.0__tar.gz

serial_mcp_server-0.1.0/.github/workflows/cicd.yml

@@ -0,0 +1,157 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write  # trusted publishing to PyPI
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[test]"
+      - run: python -m pytest tests/ -v --cov --cov-report=term-missing --cov-report="markdown:coverage.md"
+      - uses: actions/upload-artifact@v4
+        if: matrix.python-version == '3.13'
+        with:
+          name: coverage-report
+          path: coverage.md
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for hatch-vcs versioning
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: pip install bandit pip-audit
+      - name: Bandit (static security analysis)
+        run: bandit -r serial_mcp_server/ -c pyproject.toml
+      - name: pip-audit (dependency vulnerabilities)
+        continue-on-error: true
+        run: |
+          pip install -e .
+          pip-audit --strict --desc | tee pip-audit-report.txt
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: pip-audit-report
+          path: pip-audit-report.txt
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Security scan results" >> "$GITHUB_STEP_SUMMARY"
+          echo "### Bandit (static analysis)" >> "$GITHUB_STEP_SUMMARY"
+          echo "Passed" >> "$GITHUB_STEP_SUMMARY"
+          echo "### pip-audit (dependency vulnerabilities)" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          if [ -f pip-audit-report.txt ]; then
+            cat pip-audit-report.txt >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "pip-audit did not run" >> "$GITHUB_STEP_SUMMARY"
+          fi
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [lint, test, build, security]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract changelog
+        if: ${{ !contains(github.ref_name, 'rc') }}
+        run: |
+          # Extract the section for this version (e.g. "## 0.1.0" from tag "v0.1.0")
+          VERSION="${GITHUB_REF_NAME#v}"
+          awk "/^## ${VERSION}$/,/^## /" CHANGELOG.md | head -n -1 > release-notes.md
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [[ "${{ github.ref_name }}" == *rc* ]]; then
+            gh release create "${{ github.ref_name }}" \
+              --title "${{ github.ref_name }}" \
+              --generate-notes \
+              --prerelease \
+              dist/*
+          else
+            gh release create "${{ github.ref_name }}" \
+              --title "${{ github.ref_name }}" \
+              --notes-file release-notes.md \
+              dist/*
+          fi
+
+  publish-testpypi:
+    if: startsWith(github.ref, 'refs/tags/v') && contains(github.ref_name, 'rc')
+    needs: release
+    runs-on: ubuntu-latest
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, 'rc')
+    needs: release
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

serial_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.venv/
+serial_mcp_server/_version.py
+.serial_mcp/index.json
+.serial_mcp/traces/
+coverage.md
+.coverage
+.DS_Store
+.mcpregistry_*
+.ble_mcp/

serial_mcp_server-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

serial_mcp_server-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+### Serial Core
+- List available serial ports with device metadata (VID, PID, manufacturer, serial number)
+- Open connections with configurable baud rate, byte size, parity, stop bits, timeout, and encoding
+- Close connections, query connection status
+- Read data with configurable byte count and timeout override
+- Write data in text, hex, or base64 format, with optional newline append
+- Line-oriented I/O: `serial.readline` and `serial.read_until` with custom delimiters
+- Flush input/output buffers (or both)
+- Control lines: set and pulse DTR/RTS (useful for hardware reset and boot mode entry)
+- Duplicate port detection (rejects opening the same port twice)
+- Graceful shutdown (closes all serial ports on exit)
+
+### PTY Mirror
+- Virtual clone ports via pseudo-terminals (`SERIAL_MCP_MIRROR=ro` or `rw`)
+- External tools (screen, picocom, etc.) can attach to the same serial session
+- Default symlink at `/tmp/serial-mcp0`, configurable via `SERIAL_MCP_MIRROR_LINK`
+- macOS and Linux only
+
+### Introspection
+- `serial.connections.list` for recovering connection IDs and inspecting state
+
+### Protocol Specs
+- Markdown specs with YAML front-matter (`kind: serial-protocol`, `name`)
+- Template generation, registration, indexing
+- Attach specs to connections for agent reference
+- Full-text search over spec content
+
+### Tracing
+- JSONL tracing of every tool call (in-memory ring buffer + file sink)
+- Configurable payload logging with truncation
+- `serial.trace.status` and `serial.trace.tail` for inspection
+
+### Plugins
+- User plugins in `.serial_mcp/plugins/` (single files or packages)
+- Plugin contract: `TOOLS`, `HANDLERS`, optional `META` for device matching
+- `SERIAL_MCP_PLUGINS` env var: `all` or comma-separated allowlist
+- `serial.plugin.template` for generating plugin skeletons
+- `serial.plugin.list` with metadata, `serial.plugin.load`, `serial.plugin.reload`
+- Hot-reload without server restart
+
+### Security
+- Plugin path containment: `serial.plugin.load` rejects paths outside `.serial_mcp/plugins/`
+- Spec path containment: `serial.spec.register` rejects paths outside the project directory
+- Trace file always writes to `.serial_mcp/traces/trace.jsonl` (no configurable path)
+- Symlink check on trace file path
+- Input validation for hex/base64 write payloads

serial_mcp_server-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing
+
+## Dev setup
+
+```bash
+# Clone and install in editable mode with test dependencies
+git clone https://github.com/es617/serial-mcp-server.git
+cd serial-mcp-server
+pip install -e ".[test]"
+
+# Run tests (no serial hardware needed)
+python -m pytest tests/ -v
+```
+
+## How tools are registered
+
+Each `handlers_*.py` file exports:
+
+```python
+TOOLS: list[Tool] = [...]          # Tool definitions with names, descriptions, schemas
+HANDLERS: dict[str, Callable] = {  # Maps tool name → async handler function
+    "serial.tool_name": handle_fn,
+}
+```
+
+In `server.py`, these are merged inside `build_server()`:
+
+```python
+tools = handlers_serial.TOOLS + handlers_introspection.TOOLS + handlers_spec.TOOLS + handlers_trace.TOOLS + handlers_plugin.TOOLS
+handlers = {**handlers_serial.HANDLERS, **handlers_introspection.HANDLERS, **handlers_spec.HANDLERS, **handlers_trace.HANDLERS}
+```
+
+Plugin handlers are added via `handlers_plugin.make_handlers()`, which returns closures that capture the `PluginManager` and `Server` instances.
+
+## Handler pattern
+
+Every handler has the same signature:
+
+```python
+async def handle_something(state: SerialState, args: dict[str, Any]) -> dict[str, Any]:
+```
+
+- `state` — shared serial state (connections)
+- `args` — parsed tool arguments from the MCP client
+- Returns `_ok(key=value)` on success or `_err(code, message)` on failure
+
+The dispatcher in `server.py` catches common exceptions (KeyError, SerialException, TimeoutError, etc.) and converts them to error responses automatically.
+
+## Adding a new tool
+
+1. Add the `Tool(...)` definition to the appropriate `handlers_*.py` `TOOLS` list
+2. Write the handler function following the signature above
+3. Add the mapping to the `HANDLERS` dict
+4. Add tests in the corresponding `test_*.py`
+
+Tool names follow the convention `serial.<action>` for core tools (e.g., `serial.read`, `serial.open`) and `serial.<category>.<action>` for subsystems (e.g., `serial.spec.read`, `serial.plugin.reload`).
+
+## Plugin system internals
+
+**Path containment:** `PluginManager.load()` resolves the path and verifies it is inside `plugins_dir` before loading. Paths outside `.serial_mcp/plugins/` are rejected with `ValueError`.
+
+**Loading:** `load_plugin()` uses `importlib` to load a `.py` file or package `__init__.py`. It validates `TOOLS`, `HANDLERS`, and optional `META` exports, and registers the module in `sys.modules` with a unique key (`serial_mcp_plugin__{name}__{hash}`).
+
+**Name collisions:** If a plugin tool name collides with any existing tool (core or other plugin), loading fails with `ValueError`.
+
+**Policy:** `SERIAL_MCP_PLUGINS` env var is parsed into `(enabled, allowlist)`. The `PluginManager` checks this before every `load()` call. `load_all()` skips entirely when disabled.
+
+**Hot reload:** `reload(name)` calls `unload(name)` then `load(path)`. Unload filters the TOOLS list in-place and pops handler keys. The old module is deleted from `sys.modules`.
+
+**Limitation:** MCP clients may not refresh their tool list mid-session. Newly loaded plugins may require a client restart to call their tools. Hot-reload of existing plugins works without restart.
+
+## MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) lets you call tools without an agent:
+
+```bash
+npx @modelcontextprotocol/inspector python -m serial_mcp_server
+```
+
+Open the URL with the auth token printed in the terminal. Use the **Tools** tab to call any tool interactively.
+
+## Tests
+
+All tests run without serial hardware. They use `MagicMock` for pyserial objects, `tmp_path` fixtures for filesystem isolation, and `monkeypatch` for environment variables.
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Run a specific test file
+python -m pytest tests/test_plugins.py -v
+
+# Run a specific test
+python -m pytest tests/test_plugins.py::TestPluginManager::test_load_adds_tools_and_handlers -v
+```

serial_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enrico Santagati and contributors
+
+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_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: serial-mcp-server
+Version: 0.1.0
+Summary: Serial port Model Context Protocol server for AI agents and developer tooling
+Project-URL: Homepage, https://github.com/es617/serial-mcp-server
+Project-URL: Repository, https://github.com/es617/serial-mcp-server
+Project-URL: Issues, https://github.com/es617/serial-mcp-server/issues
+Project-URL: Changelog, https://github.com/es617/serial-mcp-server/blob/main/CHANGELOG.md
+Author: Enrico Santagati
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: pyserial<4,>=3.5
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Serial MCP Server
+
+<!-- mcp-name: io.github.es617/serial-mcp-server -->
+
+![MCP](https://img.shields.io/badge/MCP-compatible-blue)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+![Serial](https://img.shields.io/badge/Serial-RS232%2FUART-green)
+
+A stateful serial port Model Context Protocol (MCP) server for developer tooling and AI agents.
+Works out of the box with Claude Code and any MCP-compatible runtime. Communicates over **stdio** and uses [pyserial](https://github.com/pyserial/pyserial) for cross-platform serial on macOS, Windows, and Linux.
+
+> **Example:** Let Claude Code list available serial ports, connect to your microcontroller, reset it via DTR, and read the boot banner from your hardware.
+
+### Demo
+
+[Video walkthrough](https://www.youtube.com/watch?v=FdFdXjoyyAM) — connecting to a serial device, sending commands, reading responses, and creating plugins.
+
+---
+
+## Why this exists
+If you’ve ever copy-pasted commands into `screen` or `minicom`, guessed baud rates, toggled DTR to kick a bootloader, and re-run the same test sequence 20 times — this is for you.
+
+
+You have a serial device. You want an AI agent to talk to it — open a port, send commands, read responses, debug protocols. This server makes that possible.
+
+It gives any MCP-compatible agent a full set of serial tools: listing ports, opening connections, reading, writing, line-oriented I/O, control line manipulation — plus protocol specs and device plugins, so the agent can reason about higher-level device behavior instead of just raw bytes.
+
+The agent calls these tools, gets structured JSON back, and reasons about what to do next — without you manually typing commands into a terminal for every step.
+
+**What agents can do with it:**
+
+- **Develop and debug** — connect to your device, send commands, read responses, and diagnose issues conversationally (boot banners, prompts, error codes).
+- **Iterate on new firmware** — attach a protocol spec so the agent understands your command set, boot modes, and output format as they evolve.
+- **Automate test flows** — reset device via DTR, wait for prompt, run a command sequence, validate output.
+- **Explore unknown devices** — probe command sets, discover prompts, infer message formats.
+- **Build serial automation** — long-running test rigs, manufacturing bring-up, CI hardware smoke tests.
+
+---
+
+## Who is this for?
+
+- **Embedded engineers** — faster iteration on serial protocols, conversational debugging, automated test sequences
+- **Hobbyists and makers** — interact with serial devices without writing boilerplate; let the agent help reverse-engineer simple protocols
+- **QA and test engineers** — build repeatable serial test suites with plugin tools
+- **Support and field engineers** — diagnose serial device issues interactively without specialized tooling
+- **Researchers** — automate data collection from serial devices, explore device capabilities systematically
+
+---
+
+## Quickstart (Claude Code)
+
+```bash
+pip install serial-mcp-server
+
+# Register the MCP server with Claude Code
+claude mcp add serial -- serial_mcp
+```
+
+Then in Claude Code, try:
+
+> "List available serial ports and connect to the one on /dev/ttyUSB0 at 115200 baud."
+
+<p align="center"><img src="https://raw.githubusercontent.com/es617/serial-mcp-server/main/docs/assets/scan.gif" alt="Scanning serial ports" width="600"></p>
+
+---
+
+## What the agent can do
+
+Once connected, the agent has full serial capabilities:
+
+- **List ports** to find available serial devices
+- **Open and close** connections with configurable baud rate, parity, stop bits, and encoding
+- **Read and write** data in text, hex, or base64 format
+- **Line-oriented I/O** — readline and read-until-delimiter for text protocols
+- **Control lines** — set or pulse DTR and RTS for hardware reset and boot mode entry
+- **Flush** input and output buffers
+- **Attach protocol specs** to understand device-specific commands and data formats
+- **Use plugins** for high-level device operations instead of raw reads/writes
+- **Create specs and plugins** for new devices so future sessions start "knowing" your protocol
+- **PTY mirroring** — attach screen, minicom, or custom scripts to the same serial session the agent is using
+
+The agent can coordinate multi-step flows automatically — e.g., toggle reset, wait for prompt, send init sequence, stream output.
+
+At a high level:
+
+**Raw Serial → Protocol Spec → Plugin**
+
+You can start with raw serial tools, then move up the stack as your device protocol becomes understood and repeatable.
+
+---
+
+## Install (development)
+
+```bash
+# Editable install from repo root
+pip install -e .
+
+# Or with uv
+uv pip install -e .
+```
+
+## Add to Claude Code
+
+```bash
+# Standard setup
+claude mcp add serial -- serial_mcp
+
+# Or run as a module
+claude mcp add serial -- python -m serial_mcp_server
+
+# Enable all plugins
+claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp
+
+# Enable specific plugins only
+claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp
+
+# Debug logging
+claude mcp add serial -e SERIAL_MCP_LOG_LEVEL=DEBUG -- serial_mcp
+```
+
+> MCP is a protocol. Claude Code is one MCP client; other agent runtimes can also connect to this server.
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SERIAL_MCP_MAX_CONNECTIONS` | `10` | Maximum simultaneous open serial connections. |
+| `SERIAL_MCP_PLUGINS` | disabled | Plugin policy: `all` to allow all, or `name1,name2` to allow specific plugins. Unset = disabled. |
+| `SERIAL_MCP_MIRROR` | `off` | PTY mirror mode: `off`, `ro` (read-only), or `rw` (read-write). macOS and Linux only. |
+| `SERIAL_MCP_MIRROR_LINK` | `/tmp/serial-mcp` | Base path for PTY symlinks. Connections get numbered: `/tmp/serial-mcp0`, `/tmp/serial-mcp1`, etc. |
+| `SERIAL_MCP_LOG_LEVEL` | `WARNING` | Python log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`). Logs go to stderr. |
+| `SERIAL_MCP_TRACE` | enabled | JSONL tracing of every tool call. Set to `0`, `false`, or `no` to disable. |
+| `SERIAL_MCP_TRACE_PAYLOADS` | disabled | Include write `data` in traced args (stripped by default). |
+| `SERIAL_MCP_TRACE_MAX_BYTES` | `16384` | Max payload chars before truncation (only applies when `TRACE_PAYLOADS` is on). |
+
+---
+
+## Tools
+
+| Category | Tools |
+|---|---|
+| **Serial Core** | `serial.list_ports`, `serial.open`, `serial.close`, `serial.connection_status`, `serial.read`, `serial.write`, `serial.readline`, `serial.read_until`, `serial.flush`, `serial.set_dtr`, `serial.set_rts`, `serial.pulse_dtr`, `serial.pulse_rts` |
+| **Introspection** | `serial.connections.list` |
+| **Protocol Specs** | `serial.spec.template`, `serial.spec.register`, `serial.spec.list`, `serial.spec.attach`, `serial.spec.get`, `serial.spec.read`, `serial.spec.search` |
+| **Tracing** | `serial.trace.status`, `serial.trace.tail` |
+| **Plugins** | `serial.plugin.template`, `serial.plugin.list`, `serial.plugin.reload`, `serial.plugin.load` |
+
+---
+
+## Protocol Specs
+
+Specs are markdown files that describe a serial device's protocol — connection settings, message format, commands, and multi-step flows. They live in `.serial_mcp/specs/` and teach the agent what the byte stream means.
+
+Without a spec, the agent can still open a port and exchange data. With a spec, it knows what commands to send, what responses to expect, and what the data means.
+
+You can create specs by telling the agent about your device — paste a datasheet, describe the protocol, or just let it explore and document what it finds. The agent generates the spec file, registers it, and references it in future sessions. You can also write specs by hand.
+
+---
+
+## Plugins
+
+Plugins add device-specific shortcut tools to the server. Instead of the agent composing raw read/write sequences, a plugin provides high-level operations like `mydevice.read_temp` or `ota.upload_firmware`.
+
+The agent can also **generate** Python plugins (with your approval). It explores a device, writes a plugin based on what it learns, and future sessions get shortcut tools — no manual coding required.
+
+To enable plugins:
+
+```bash
+# Enable all plugins
+claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp
+
+# Enable specific plugins only
+claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp
+```
+
+Editing an already-loaded plugin only requires `serial.plugin.reload` — no restart needed.
+
+---
+
+## Tracing
+
+Every tool call is traced to `.serial_mcp/traces/trace.jsonl` and an in-memory ring buffer (last 2000 events). Tracing is **on by default** — set `SERIAL_MCP_TRACE=0` to disable.
+
+### Event format
+
+Two events per tool call:
+
+```jsonl
+{"ts":"2025-01-01T00:00:00.000Z","event":"tool_call_start","tool":"serial.read","args":{"connection_id":"s1"},"connection_id":"s1"}
+{"ts":"2025-01-01T00:00:00.050Z","event":"tool_call_end","tool":"serial.read","ok":true,"error_code":null,"duration_ms":50,"connection_id":"s1"}
+```
+
+- `connection_id` is extracted from args when present
+- Write `data` is stripped from traced args by default (enable with `SERIAL_MCP_TRACE_PAYLOADS=1`)
+
+### Inspecting the trace
+
+Use `serial.trace.status` to check config and event count, and `serial.trace.tail` to retrieve recent events — no need to read the file directly.
+
+---
+
+## PTY Mirror
+
+When the MCP server owns a serial port, most OSes prevent any other process from opening it. PTY mirroring creates a virtual clone port that external tools (screen, minicom, logic analyzers, custom scripts) can connect to simultaneously.
+
+```bash
+# Enable read-only mirror
+claude mcp add serial \
+  -e SERIAL_MCP_MIRROR=ro \
+  -- serial_mcp
+
+# After opening a connection, the response includes the mirror path:
+# { "mirror": { "pty_path": "/dev/ttys004", "link": "/tmp/serial-mcp0", "mode": "ro" } }
+
+# In another terminal:
+screen /tmp/serial-mcp0 115200
+```
+
+| Mode | Behavior |
+|---|---|
+| `off` | No mirror (default). Only the MCP server can access the port. |
+| `ro` | External tools see all serial data but cannot write to the device. |
+| `rw` | External tools can both see data and write to the device. |
+
+**Platform:** macOS and Linux only. On Windows, setting `SERIAL_MCP_MIRROR` to `ro`/`rw` logs a warning and is silently ignored.
+
+---
+
+## Try without an agent
+
+You can test the server interactively using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) — no Claude or other agent needed:
+
+```bash
+npx @modelcontextprotocol/inspector python -m serial_mcp_server
+```
+
+Open the URL with the auth token from the terminal output. The Inspector gives you a web UI to call any tool and see responses in real time.
+
+
+---
+
+## Known limitations
+
+- **Single-client only.** The server handles one MCP session at a time (stdio transport). Multi-client transports (HTTP/SSE) may be added later.
+- **Exclusive access.** Without PTY mirroring, the MCP server must own the serial port exclusively.
+
+---
+
+## Safety
+
+This server connects an AI agent to real hardware. That's the point — and it means the stakes are higher than pure-software tools.
+
+**Plugins execute arbitrary code.** When plugins are enabled, the agent can create and run Python code on your machine with full server privileges. Review agent-generated plugins before loading them. Use `SERIAL_MCP_PLUGINS=name1,name2` to allow only specific plugins rather than `all`.
+
+**Writes affect real devices.** A bad command sent to a serial device can trigger unintended behavior, disrupt other connected systems, or cause hardware damage (e.g., wiping flash, entering bootloader mode, triggering actuators). Consider what the agent can reach.
+
+**Use tool approval deliberately.** When your MCP client prompts you to approve a tool call, consider whether you want to allow it once or always. "Always allow" is convenient but means the agent can repeat that action without further confirmation.
+
+This software is provided as-is under the MIT License. You are responsible for what the agent does with your hardware.
+
+---
+
+## License
+
+This project is licensed under the MIT License — see [LICENSE](https://github.com/es617/serial-mcp-server/blob/main/LICENSE) for details.
+
+## Acknowledgements
+
+This project is built on top of the excellent [pyserial](https://github.com/pyserial/pyserial) library for cross-platform serial communication in Python.