wlanpi-mcp: 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

An MCP (Model Context Protocol) server that exposes WLAN Pi capabilities - device info, service management, Wi-Fi scanning, profiler, Bluetooth, VLANs - to AI assistants. It is a thin bridge to the wlanpi-core REST API on http://localhost:31415: every tool and resource goes through that API, and nothing runs local subprocesses or reads local files. Keep it that way - if a capability has no wlanpi-core endpoint, the endpoint gets added upstream first.

Commands

# Setup (Python >= 3.13)
pip install -e ".[testing]"

# Run all tests / one file / one test
pytest
pytest tests/test_auth.py
pytest tests/test_auth.py::test_passes_token_to_downstream_context

# Run the server locally
python -m wlanpi_mcp --transport stdio   # default; direct MCP client invocation
python -m wlanpi_mcp --transport sse     # HTTP daemon mode (uvicorn), how systemd runs it

# Build the Debian package (dh-virtualenv, installs to /opt/wlanpi-mcp)
dpkg-buildpackage -us -uc

asyncio_mode = auto is set in pyproject.toml, so async tests don't need @pytest.mark.asyncio. Lint and format tooling is configured via tox (tox -e lint, tox -e formatcheck, tox -e format) using flake8/black/isort/autoflake.

Architecture

• wlanpi_mcp/server.py - create_server() builds the FastMCP instance and wires every module in. All tool/resource/prompt modules follow the same pattern: a top-level register(mcp, client) function containing @mcp.tool() / @mcp.resource() decorated closures. Adding a capability = new module in tools/ or resources/ + a register() call in server.py. The "Phase 1/2/3" comments reflect the order features were built, nothing more.
• wlanpi_mcp/client/core_client.py - CoreClient, the single async httpx client for wlanpi-core. Module-level singleton via init_client()/get_client(), created in __main__.py and passed to register() functions.
• wlanpi_mcp/config.py - pydantic-settings Settings, loaded from environment or /etc/wlanpi-mcp/config.env. Also holds ALLOWED_SERVICES, the allowlist that gates start_service/stop_service/restart_service. ALLOW_POWER_CONTROL (default true) gates reboot_device/shutdown_device.