From 07d6ee6ff19c0040bde73008fe423f6953e7077c Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Sat, 31 Jan 2026 09:47:35 -0700 Subject: [PATCH] Update README for full API coverage and safety tiers Tool table split by safety tier (none/normal/strict), new part-number support matrix, updated project structure. --- README.md | 113 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 75 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index f941402..0803bf2 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# mcp210x +# mcp210x-uart It's MCP. It's CP210x. It was right there the whole time. -An MCP server for customizing Silicon Labs CP210x USB-UART bridge devices — product strings, serial numbers, power config, udev rules, and device locking — through natural language in Claude Code. +An MCP server for customizing Silicon Labs CP210x USB-UART bridge devices — product strings, serial numbers, power config, GPIO port config, baud rate tables, udev rules, and device locking — through natural language in Claude Code. -Built on [FastMCP](https://gofastmcp.com/) with Python ctypes bindings to Silicon Labs' native `libcp210xmanufacturing` library. +Built on [FastMCP](https://gofastmcp.com/) with Python ctypes bindings to all 45 functions in Silicon Labs' native `libcp210xmanufacturing` library. Covers the full CP210x family: CP2101, CP2102, CP2102N, CP2103, CP2104, CP2105, CP2108, and CP2109. ## The problem @@ -32,26 +32,78 @@ Two devices found: Each device gets a unique product string baked into its USB descriptor EPROM. Udev rules match on that string to create stable symlinks. Devices survive reboots, port reordering, and hub changes. -## Features +## Tools -- **List and inspect** connected CP210x devices (part number, VID/PID, strings, power, lock state) -- **Write USB descriptors** — product string, manufacturer, serial number -- **Configure power** — max current draw, self-powered vs bus-powered -- **Generate udev rules** — stable `/dev/` symlinks based on product string -- **Reset device** — trigger USB re-enumeration after changes -- **Lock device** — permanently freeze configuration (with strict confirmation gate) +### Read-only (no confirmation) + +| Tool | Description | +|------|-------------| +| `list_devices` | List all connected CP210x devices | +| `get_device_info` | Full device details — part number, VID/PID, strings, power, lock state, firmware version (CP2102N), flush config, device mode | +| `get_firmware_version` | Firmware version (CP2102N only) | +| `get_flush_buffer_config` | Flush buffer configuration (CP2104/CP2105/CP2108) | +| `get_device_mode` | Device mode — ECI/SCI assignment (CP2105 only) | +| `get_interface_string` | USB interface string (CP2105/CP2108 only) | +| `get_baud_rate_config` | Baud rate alias table (32 entries) | +| `get_port_config` | GPIO port configuration (auto-detects CP2103/4/5/8) | +| `get_raw_config` | Raw EPROM configuration blob (hex string) | +| `create_hex_file` | Dump device config to Intel HEX file | +| `reset_device` | USB disconnect/reconnect to apply changes | + +### Normal writes (elicitation → fallback to proceed) + +| Tool | Description | +|------|-------------| +| `set_product_string` | Write USB product string (max 126 chars) | +| `set_manufacturer_string` | Write USB manufacturer string (max 45 chars) | +| `set_serial_number` | Write USB serial number (max 63 chars) | +| `set_max_power` | Set max USB power draw in mA (0–500, rounded to nearest 2) | +| `set_self_powered` | Toggle self-powered vs bus-powered reporting | +| `set_device_version` | Set device version (bcdDevice field) | +| `set_interface_string` | Set USB interface string (CP2105/CP2108 only) | +| `set_flush_buffer_config` | Set flush buffer configuration (CP2104/CP2105/CP2108) | +| `set_device_mode` | Set device mode (CP2105 only) | +| `set_baud_rate_config` | Set full 32-entry baud rate alias table | +| `set_baud_rate_alias` | Modify a single baud rate alias entry (read-modify-write) | +| `set_port_config` | Set GPIO port configuration (auto-detects CP2103/4/5/8) | +| `setup_udev_rule` | Generate and install a udev rule for a stable `/dev/` symlink | + +### Strict writes (elicitation required — hard-refuses without it) + +| Tool | Description | +|------|-------------| +| `set_vid` | Set USB Vendor ID (can break driver matching) | +| `set_pid` | Set USB Product ID (can break driver matching) | +| `set_raw_config` | Write raw configuration blob to EPROM | +| `update_firmware` | Update device firmware (CP2102N only) | +| `lock_device` | Permanently freeze device configuration | ## Safety model CP210x descriptor EPROM is one-time-programmable with limited write cycles. Writes can't be undone. Locks are permanent. The server enforces a tiered confirmation model: -| Operation | Confirmation | -|-----------|-------------| -| Reads | None | -| Writes (strings, power) | MCP elicitation if client supports it; proceeds otherwise | -| Lock | Elicitation **required**; hard-refuses without it | +| Tier | Behavior | Tools | +|------|----------|-------| +| **None** | No confirmation | All `get_*`, `list_devices`, `reset_device`, `create_hex_file` | +| **Normal** | Elicitation if client supports it; proceeds otherwise | String setters, power, baud config, port config, `setup_udev_rule` | +| **Strict** | Elicitation **required**; returns error without it | `set_vid`, `set_pid`, `set_raw_config`, `update_firmware`, `lock_device` | -The lock gate isn't just a warning — it returns an error and does not proceed if the MCP client can't present a confirmation dialog. +The strict gate isn't a warning — it returns an error and does not proceed if the MCP client can't present a confirmation dialog. + +## Part-number support + +Different CP210x parts expose different features. The server auto-gates tools to supported parts: + +| Feature | Supported parts | +|---------|----------------| +| Core (strings, power, baud) | All CP210x | +| Flush buffer config | CP2104, CP2105, CP2108 | +| Device mode | CP2105 | +| Interface strings | CP2105, CP2108 | +| Port config | CP2103, CP2104 | +| Dual port config | CP2105 | +| Quad port config | CP2108 | +| Firmware version/update | CP2102N | ## Requirements @@ -93,30 +145,15 @@ uv tool install . ### 3. Claude Code ```bash -claude mcp add cp210x -- uvx mcp210x +claude mcp add cp210x -- uvx mcp210x-uart ``` For development (runs from source): ```bash -claude mcp add cp210x-local -- uv run --directory /path/to/this-repo mcp210x +claude mcp add cp210x-local -- uv run --directory /path/to/this-repo mcp210x-uart ``` -## Tools - -| Tool | Description | -|------|-------------| -| `list_devices` | List connected CP210x devices with description and serial | -| `get_device_info` | Full device details — part number, VID/PID, strings, power, lock state | -| `set_product_string` | Write USB product string (max 126 chars) | -| `set_manufacturer_string` | Write USB manufacturer string (max 45 chars) | -| `set_serial_number` | Write USB serial number (max 63 chars) | -| `set_max_power` | Set max USB power draw in mA (0-500, rounded to nearest 2) | -| `set_self_powered` | Toggle self-powered vs bus-powered reporting | -| `reset_device` | USB disconnect/reconnect to apply changes | -| `lock_device` | Permanently freeze device configuration | -| `setup_udev_rule` | Generate and install a udev rule for a stable `/dev/` symlink | - ## Architecture ``` @@ -137,10 +174,10 @@ The native library uses **libusb** for device access, separate from the kernel's ## Project structure ``` -mcp210x/ -├── src/mcp210x/ -│ ├── server.py # FastMCP tool definitions and elicitation logic -│ ├── bindings.py # ctypes wrapper for libcp210xmanufacturing.so +mcp210x-uart/ +├── src/mcp210x_uart/ +│ ├── server.py # FastMCP tool definitions, elicitation, part-number dispatch +│ ├── bindings.py # ctypes: structs, prototypes, bitmask helpers, device wrapper │ └── __init__.py ├── aur/cp210xmanufacturing/ │ ├── PKGBUILD # Arch Linux package for the native library @@ -152,7 +189,7 @@ mcp210x/ ## Complementary tools -This server handles **device customization** (USB descriptors, power config). For **serial communication** (sending/receiving data over UART), use [mcserial](https://git.supported.systems/MCP/mcserial). +This server handles **device customization** (USB descriptors, power config, GPIO, baud tables). For **serial communication** (sending/receiving data over UART), use [mcserial](https://git.supported.systems/MCP/mcserial). ## Reference