firewalla-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

A local stdio MCP server wrapping the Firewalla MSP API v2 — boxes, devices, people/apps, alarms, rules, flows, target lists, trends, and statistics — as tools for Claude Code and other MCP clients. Public, MIT, published as firewalla-mcp and runnable straight from GitHub with uvx. Requires Python 3.12+ and an active Firewalla MSP subscription.

Small on purpose: ~700 lines across three modules.

Commands

uv sync
uv run pytest -v
uv run pytest tests/test_client_rules.py::test_name    # single test
uv run ruff check . && uv run ruff format --check .    # both enforced in CI

The suite is fully mocked with respx — no Firewalla credentials or network access are needed to run it, and no test should ever require them.

Architecture

Two layers, one file each. Every MSP API operation is implemented in both:

1. src/firewalla_mcp/client.py — a method on FirewallaClient that calls self._request(...) and returns parsed JSON. All HTTP behavior (auth, retries, error shaping) lives here.
2. src/firewalla_mcp/server.py — a thin @mcp.tool() wrapper calling the client method. Its docstring is the MCP tool description the model reads, so write it for that audience.

config.py reads FIREWALLA_MSP_DOMAIN, FIREWALLA_TOKEN, and optional FIREWALLA_TIMEOUT (default 10s) from the environment at startup; a pasted https:// prefix or trailing slash on the domain is tolerated.

To add a tool: follow an existing method as a template, add client tests that mock the HTTP call with respx, and update the expected tool set in tests/test_server.py — that test pins the full inventory and will fail otherwise.

Deliberate design decisions — do not change casually

Retry policy (client.py, MAX_ATTEMPTS/RETRY_BACKOFF_SECONDS/MAX_RETRY_AFTER_SECONDS):

• 4xx fails immediately, raising FirewallaAPIError(status_code, body) with the body truncated to MAX_ERROR_BODY_CHARS so failures stay readable.
• 429 retries once, honoring Retry-After up to 10s.
• 5xx and connection errors retry once with 0.5s backoff — except non-idempotent writes (create_rule, create_target_list, update_device, mute_alarm, archive_alarm), which are never retried so a timed-out request cannot silently duplicate or double-apply a write.
• Non-JSON responses (e.g. an HTML proxy error page) raise a readable error, not a decoder traceback.