dwf-mcp-server: Instructions file for Claude Code

CLAUDE.md

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

What This Is

MCP server for Digilent WaveForms instruments (oscilloscope, AWG, logic analyzer). Built with Python, fastmcp v3, and dwfpy. Deployed as a Docker image; the proprietary Digilent libraries (Adept 2 Runtime, libdwf.so) are added by users via a derived Dockerfile layer.

Commands

# GitHub milestone operations (no `gh milestone` command exists)
gh api repos/{owner}/{repo}/milestones                                       # list
gh api repos/{owner}/{repo}/milestones -f title="..." -f description="..."   # create

# Install for development (creates .venv from uv.lock)
uv sync --frozen --extra dev

# Refresh uv.lock when pyproject.toml dependencies change
uv lock

# Run all tests (no hardware required)
uv run pytest tests/ -v

# Run a single test class or method
uv run pytest tests/test_server.py::TestComputeMeasurement -v
uv run pytest tests/test_server.py::TestListDevices::test_returns_device_list -v

# Lint & format
ruff format --check .
ruff check .
ruff format .          # auto-fix formatting
ruff check --fix .     # auto-fix lint issues

# Run server locally (requires libdwf on host)
uv run dwf-mcp-server

Architecture

Tool registration pattern

Each tool module in src/dwf_mcp_server/tools/ follows the same pattern:

1. Module-level functions with full type annotations — these are the actual MCP tools.
2. A register(mcp: FastMCP) function at the bottom that calls mcp.tool(fn) for each tool.
3. server.py imports each module and calls module.register(mcp).

This design keeps tool functions callable directly (for testing) while letting server.py be the single registration point.

Device session lifecycle

session.py contains a DeviceManager singleton that manages persistent device connections:

• Auto-connect: acquire(device_index) opens the device on first use, returns the cached handle on subsequent calls.
• Explicit close: release(device_index) closes the device and stops all outputs.
• Idle timeout: A 5-minute threading.Timer auto-closes idle devices.
• Thread safety: All operations are protected by threading.Lock.