serial-mcp AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

serial-mcp is an MCP (Model Context Protocol) server that enables LLMs to communicate with serial devices (microcontrollers, routers, modems, embedded Linux). Python 3.10+, MIT licensed.

Build & Run Commands

# Install (editable, with dev dependencies)
uv pip install -e ".[dev]"

# Run the MCP server
python3 -m serial_mcp.server

# Test with MCP Inspector
DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector -- python3 -m serial_mcp.server

# Install dependencies only
uv pip install -r requirements.txt

# Run tests
pytest -v

# Lint
ruff check serial_mcp/ tests/
ruff format --check serial_mcp/ tests/

# Build MCPB bundle
./scripts/build-mcpb.sh

Architecture

Three-file architecture in serial_mcp/:

• server.py — FastMCP server exposing 24 async tools (all prefixed serial_* except discovery) and 4 prompts. Maintains a global _sessions dict keyed by port name with atexit cleanup. _resolve_session() auto-selects when only one session is open and surfaces auto-close notifications. All tools include MCP annotations (readOnlyHint, destructiveHint, etc.). Blocking serial I/O is wrapped in asyncio.to_thread(). Tools are grouped: port discovery, port control (serial_force_release), connection management, text read/write, binary/hex read/write, hardware signal control, session utilities, XMODEM file transfer, and logging. Supports elicitation for interactive port and baud selection. Server-level instructions tell the AI to always close explicit sessions. A background _session_reaper task auto-closes idle sessions. Text output is normalized (\r\n → \n, trailing whitespace stripped) at the tool layer via _normalize_output().

• session.py — SerialSession class managing individual serial connections. Runs a daemon background reader thread that stores data in a timestamped ring buffer (10MB default cap). Supports both destructive reads (read_buffer) and non-destructive historical reads (read_since). Thread safety via threading.Lock for history and threading.Event for data availability and shutdown signaling.