bdcom_mcp CLAUDE.md

CLAUDE.md

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

Project

A Python / FastMCP server ("device-mcp") that lets AI assistants manage network devices (Cisco IOS, BDCOM, any netmiko platform) over SSH/Telnet. Transport is netmiko; BDCOM gets a small custom driver. Requires Python >= 3.10; the repo has a venv at .venv (use .venv/bin/python / .venv/bin/pytest if not activated).

Commands

pip install -e ".[dev]"        # install + pytest/pytest-timeout

python -m device_mcp.server    # run the MCP server over stdio (also: device-mcp script)

python smoke_test.py           # offline smoke suite: pure helpers + fakes, no sockets, <1s
pytest                         # emulator integration tests in tests/ (real telnet over loopback)
pytest tests/test_emulator_integration.py::test_connect_enable_password_flow   # single test

python my_tester.py            # manual eyeball harness (NOT pytest) against the emulator

Run both suites (python smoke_test.py and pytest) before considering a change done. Each pytest test performs a real netmiko telnet login (~9s); pyproject.toml sets a 30s per-test timeout so a hang fails one test instead of stalling the run.

Architecture

Three layers, plus a test emulator:

• device_mcp/server.py — thin FastMCP tool layer. Each @mcp.tool wraps a method on a module-level DeviceConnectionManager and returns a string; exceptions are caught and returned as "Error: ..." text (AI-friendly, never raised to the client). Three file-transfer/firmware tools (transfer_file, upgrade_firmware, recover_firmware) are commented out here but their manager methods still exist and are tested — re-enabling means uncommenting the wrapper (enter_monitor_mode is live).
• device_mcp/connection.py — the core (~1800 lines). DeviceConnectionManager holds long-lived connections keyed by target = host:port (several devices behind one console-server IP on different ports are independent connections; port may be omitted in tool calls only when a host has exactly one connection — see _resolve). One RLock guards the connection map and the non-reentrant netmiko channels; a per-connection daemon thread polls idle channels (non-blocking lock acquire) so unsolicited output reaches the audit log.
• device_mcp/bdcom.py — custom netmiko driver: _BdcomMixin over the Cisco IOS classes. BDCOM enters config with config (prompt Switch_config#, no parens), exits config with Ctrl-Z (not echoed, so exit_config_mode can't delegate to netmiko's echo-wait), has no terminal width, and accepts terminal length 0 only in enable mode — so session_preparation elevates to enable before disabling paging (stock Cisco prep would leave paging on and desync later big show output). To add another vendor netmiko lacks: write a similar driver module and register it in _CUSTOM_DRIVERS in connection.py.
• tests/switch_emulator.py — in-process, stdlib-only Telnet switch emulator speaking bdcom and cisco dialects (login, enable password, paging/--More--, config sub-modes, ? help, (y/n) confirmations, the hidden Ctrl-] boot menu and Ctrl-P monitor interrupt). Tests script it via a responses map (exact string, compiled regex, or callable → output).