Generate the MCP tools from the Bridge API instead of transcribing them

mcp/tools.py hand-wrote 919 lines that re-declared the signature and
re-worded the docstring of methods that already existed, and still only
covered 85 of the 127 sub-API methods: there were no rmt_*, i2s_*, watch_*
or wifi_link_* tools at all.

Tools are now derived from the API. Every public sub-API method becomes
<subapi>_<method> carrying that method's own signature and docstring, with
bytes travelling as hex in both directions; only the exceptions are written
out (SKIP for callbacks and live objects, plus a handful of composites).
esp.i2c.read(addr, n) IS the i2c_read tool, so the two can no longer drift,
and a new peripheral method is a new tool with nothing to write.

108 -> 136 tools, no name lost. Generated tools return the method's own
value, so gpio_write gives the read-back level (1) rather than
{"level": 1, "ok": true} and i2c_read gives "010203" rather than
{"hex": "010203"}.

Deletions that fell out of it:

- dac.cosine_stop(): the firmware's DAC_DISABLE already calls stop_cosine(),
  and so does dac.write() -- the method could only do a subset of disable().
- BridgeManager.note_i2c/forget_i2c/i2c_buses: esp.i2c.buses records the bus
  configuration where it belongs, and board_status reads it from there.
- BridgeManager.open_uart/uart_port/close_uart: esp.uart already cached its
  ports; it only needed a port() accessor.

PinStatus.pwm becomes a field rather than a property, so it survives
serialisation, and the loose atten/callback parameters on adc.config and
watch.add are annotated.

Verified on two ESP32 DevKits: hw_stress 130/130 over 5 iterations with no
heap drift, plus the generated tools driven over a real link (gpio, adc,
dac, pwm, i2c, nvs, fs, watch, rmt, i2s, radio_off, board_status).

Author: HamzaYslmn

docs/MCP.md

@@ -96,8 +96,9 @@ auto-reconnects on the first tool call if the link drops.
 
 ## Tools
 
-100+ tools, grouped by peripheral. The agent reads the per-tool descriptions; the
-groups are:
+One tool per method of the Python API — `esp.i2c.read(addr, n)` is the `i2c_read`
+tool, with that method's own arguments and docstring, so the two never drift.
+The agent reads the per-tool descriptions; the groups are:
 
 | prefix | what |
 |--------|------|
@@ -111,6 +112,8 @@ groups are:
 | `nvs_*` | persistent key/value store (str/int/bytes) |
 | `fs_*` | LittleFS / SD files (list, read, write, stat, …) |
 | `onewire_*` / `espnow_*` / `can_*` | 1-Wire, ESP-NOW, CAN bus |
+| `rmt_*` / `i2s_*` | pulse trains (NeoPixel/IR/DHT timing) and PCM audio in/out |
+| `watch_*` | on-device rules: the board samples a pin and acts on it by itself |
 | `mcpwm_*` / `eth_*` / `camera_*` / `ota_*` | motor PWM, Ethernet, camera JPEG, firmware update |
 
 Conventions the tools follow:
@@ -127,14 +130,16 @@ Conventions the tools follow:
 `camera_capture` returns the JPEG as an MCP image so vision-capable models can
 see it directly.
 
-> Streaming / session-oriented APIs (raw TCP/UDP sockets, BLE GATT, I2S audio,
-> RMT capture) are intentionally **not** exposed as tools — they don't map onto
-> request/response tool calls. Use the Python `Bridge` API for those.
+> What is intentionally **not** a tool: anything that hands back a live object
+> (raw TCP/UDP sockets, BLE GATT sessions) or takes a host callback (edge
+> interrupts, RX handlers, RMT capture) — neither maps onto request/response
+> tool calls. Use the Python `Bridge` API for those.
 
 ## Live feedback
 
-Every tool reports what it did on the board — e.g. `GPIO2 mode set to output`,
-or `pwm_attach(pin=5, freq=1000, resolution_bits=10)`. Each message goes to two
+Every tool reports what it did on the board — e.g.
+`gpio_mode(pin=2, mode='output')`, or `gpio_write(pin=2, value=1) -> 1`. Each
+message goes to two
 places:
 
 - the **server log** (stderr) — visible to whoever runs `espbridge-mcp`;

python/espbridge/analog.py

@@ -21,7 +21,7 @@ class Adc:
     def __init__(self, bridge):
         self._b = bridge
 
-    def config(self, pin: int, atten=11) -> None:
+    def config(self, pin: int, atten: float = 11) -> None:
         """Set the input attenuation for a pin (0/2.5/6/11 dB; default 11 ≈ 3.3 V)."""
         self._b.request(C.ADC_CONFIG, bytes([pin, ATTEN.get(atten, int(atten))]))
 
@@ -39,8 +39,7 @@ class Dac:
 
         esp.dac.write(25, 128)            # ~1.65 V
         esp.dac.cosine(25, 1000)          # 1 kHz cosine wave
-        esp.dac.cosine_stop(25)
-        esp.dac.disable(25)
+        esp.dac.disable(25)               # stops the wave and releases the pin
     """
 
     def __init__(self, bridge):
@@ -60,12 +59,11 @@ def cosine(self, pin: int, freq_hz: int, *, scale: int = 0, offset: int = 0,
         self._b.request(C.DAC_COSINE, struct.pack(">BIBbB", pin, freq_hz, scale & 3,
                                                   offset, 1 if phase_180 else 0))
 
-    def cosine_stop(self, pin: int) -> None:
-        """Stop the cosine generator on a pin (the pin stays a DAC output)."""
-        self._b.request(C.DAC_COS_STOP, bytes([pin]))
-
     def disable(self, pin: int) -> None:
-        """Turn the DAC off on a pin and release it."""
+        """Stop any cosine generator on the pin, turn the DAC off and release it.
+
+        A plain :meth:`write` also stops the generator, so there is nothing else
+        to call to take the pin back."""
         self._b.request(C.DAC_DISABLE, bytes([pin]))
 
 

python/espbridge/gpio.py

@@ -41,18 +41,14 @@ class PinStatus:
     level: int               # actual pad level (0 or 1) read back from hardware
     mode: str | None         # mode last set via the bridge; None if never configured
     is_output: bool
+    pwm: bool                # a PWM (LEDC) channel is driving this pin
     pwm_freq: int            # LEDC carrier frequency in Hz; 0 means no PWM on this pin
     pwm_duty: int            # LEDC raw duty count; 0 if no PWM
 
-    @property
-    def pwm(self) -> bool:
-        """True when a PWM (LEDC) channel is driving this pin."""
-        return self.pwm_freq > 0
-
 
 def _pin_status(pin: int, level: int, mode: int, freq: int, duty: int) -> PinStatus:
     name = _MODE_NAMES.get(mode)
-    return PinStatus(pin, level, name, name in _OUTPUT_MODES, freq, duty)
+    return PinStatus(pin, level, name, name in _OUTPUT_MODES, freq > 0, freq, duty)
 
 
 class Gpio:

python/espbridge/i2c.py

@@ -18,6 +18,7 @@ class I2c:
     def __init__(self, bridge):
         self._b = bridge
         self._max_write: int | None = None
+        self.buses: dict[int, dict] = {}  # bus -> {sda, scl, freq}, as configured
 
     @property
     def max_write(self) -> int:
@@ -38,6 +39,7 @@ def init(self, *, sda: int = 21, scl: int = 22, freq: int = 400_000, bus: int =
         r = self._b.request(C.I2C_INIT, struct.pack(">BBBI", bus, sda, scl, freq))
         if len(r) >= 2:  # firmware >= 0.3.0 replies with the Wire TX buffer size as a u16
             self._max_write = struct.unpack(">H", r[:2])[0] - 2
+        self.buses[bus] = {"sda": sda, "scl": scl, "freq": freq}
 
     def scan(self, bus: int = 0) -> list[int]:
         """Addresses (7-bit) that ACK on the bus."""
@@ -83,6 +85,7 @@ def write_reg(self, addr: int, reg: int, data: bytes | int, bus: int = 0) -> Non
     def deinit(self, bus: int = 0) -> None:
         """Release the bus and its pins on the firmware."""
         self._b.request(C.I2C_DEINIT, bytes([bus]))
+        self.buses.pop(bus, None)
 
     # House style: begin()/end() work on every peripheral (Arduino-friendly).
     begin = init

python/espbridge/mcp/server.py

@@ -36,10 +36,11 @@
 Control an ESP32 running the python-esp-bridge firmware over USB or Bluetooth.
 
 Tools are grouped by peripheral: system_*, gpio_*, adc_*/dac_*/touch_*, pwm_*,
-i2c_*, spi_*, uart_*, wifi_*, nvs_*, fs_*, onewire_*, espnow_*, can_*, mcpwm_*,
-eth_*, camera_*, ota_*. Connection is managed by bridge_connect / bridge_status
-/ bridge_disconnect; if you call a peripheral tool before connecting, the server
-auto-connects with the settings it was started with.
+i2c_*, spi_*, uart_*, wifi_*, nvs_*, fs_*, onewire_*, espnow_*, can_*, rmt_*,
+i2s_*, watch_*, mcpwm_*, eth_*, camera_*, ota_*. Connection is managed by
+bridge_connect / bridge_status / bridge_disconnect; if you call a peripheral
+tool before connecting, the server auto-connects with the settings it was
+started with.
 
 Conventions:
 - Pins are integers (the chip's GPIO numbers). gpio_mode must be set to
@@ -56,8 +57,8 @@
 
 class BridgeManager(_CoreBridgeManager):
     """The core shared-bridge manager (one thread-safe, auto-reconnecting link)
-    plus the stateful handles the MCP tools layer on top: mounted filesystem
-    volumes, opened UART ports, and noted I2C buses (for board_status).
+    plus the one handle the tools layer adds: the mounted filesystem volumes.
+    I2C buses and UART ports are remembered by ``esp.i2c``/``esp.uart``.
 
     Thread-safe: FastMCP runs each (synchronous) tool in a worker thread, and
     Bridge.request() is itself thread-safe, so concurrent tool calls share one
@@ -67,17 +68,14 @@ class BridgeManager(_CoreBridgeManager):
     def __init__(self, **connect_kwargs):
         super().__init__(**connect_kwargs)
         self._volumes: dict = {}       # fs kind -> Volume
-        self._uart_ports: dict = {}    # port number -> UartPort
-        self._i2c_buses: dict = {}     # bus number -> {sda, scl, freq} (for board_status)
 
     def _close_locked(self) -> None:
-        # Tear down the link, then drop the per-connection handles built on it.
+        # Tear down the link, then drop the volumes mounted on it.
         super()._close_locked()
         self._volumes.clear()
-        self._uart_ports.clear()
-        self._i2c_buses.clear()
 
-    def volume(self, kind: str, *, remount: bool = False, **mount_kwargs):
+    def volume(self, kind: str = "littlefs", *, remount: bool = False,
+               **mount_kwargs):
         """Mount (and cache) a filesystem volume of the given kind.
 
         Lazy callers that just need *a* mount pass no kwargs and get the cached
@@ -92,35 +90,6 @@ def volume(self, kind: str, *, remount: bool = False, **mount_kwargs):
                 self._volumes[kind] = vol
             return vol
 
-    @property
-    def i2c_buses(self) -> dict:
-        with self._lock:
-            return dict(self._i2c_buses)
-
-    def note_i2c(self, bus: int, sda: int, scl: int, freq: int) -> None:
-        with self._lock:
-            self._i2c_buses[bus] = {"sda": sda, "scl": scl, "freq": freq}
-
-    def forget_i2c(self, bus: int) -> None:
-        with self._lock:
-            self._i2c_buses.pop(bus, None)
-
-    def uart_port(self, port: int):
-        with self._lock:
-            return self._uart_ports.get(port)
-
-    def open_uart(self, *, port: int, tx: int, rx: int, baud: int):
-        with self._lock:
-            p = self.bridge().uart.init(port=port, tx=tx, rx=rx, baud=baud)
-            self._uart_ports[port] = p
-            return p
-
-    def close_uart(self, port: int) -> None:
-        with self._lock:
-            p = self._uart_ports.pop(port, None)
-            if p is not None:
-                p.close()
-
 
 def _register_connection(mcp: FastMCP, mgr: BridgeManager) -> None:
     @mcp.tool