pfsense-mcp CLAUDE.md

pfSense MCP Server

Auto-generated MCP server for the pfSense REST API v2. 677 tools generated from openapi-spec.json (OpenAPI 3.0.0, 258 paths, 178 schemas). When pfSense updates their API, pull a new spec and re-run the generator.

Rules

1. Never manually edit generated/server.py. Fix the generator or templates instead.
2. openapi-spec.json is the single source of truth. All type information, parameter names, and endpoint structure come from the spec.
3. Test against the VM, not production. The golden image exists for this purpose.
4. Expect scripts are fragile but working. Do not change timing, patterns, or shortcuts unless something breaks.
5. Always use nix develop -c as the default wrapper for repo commands (including python -m generator, pytest, qemu/expect scripts, and any tooling that touches this project).
6. Testing must be automated. Every feature/fix needs a pytest suite or equivalent that runs without human intervention. No manual-only verification — if it can't be pytest'd, write a script.
7. Add tests with features. When adding new functionality, always write automated tests in the same change. Tests verify the feature works and prevent regressions.
8. Sprint progress lives in CLAUDE.md. When work spans multiple sessions, document sprint plans, progress, and outcomes here so future sessions have full context.

Repository Structure

openapi-spec.json            # OpenAPI 3.0.0 spec (input)
generator/                   # Python generator
  __main__.py                # Entry point: python -m generator
  loader.py                  # Load and parse the OpenAPI spec
  naming.py                  # Convert operationIds to tool names
  schema_parser.py           # Extract parameter types from schemas
  context_builder.py         # Build template context for each tool
  codegen.py                 # Render templates and write output
templates/
  server.py.j2               # FastMCP server template
generated/
  server.py                  # The MCP server (677 tools — never hand-edit)
test_modules.py              # Spec-derived pytest suite for module/read-only gating (85 tests)
test_list_tools.py           # Tests for list tool field selection, row filtering, known-fields (19 tests)
bank-tester/                 # AI-driven integration test suite
  run-bank-test.sh           # Orchestrator: boot VM → run tasks → collect results
  generate-tasks.py          # Auto-generate task files from spec + task-config.yaml
  task-config.yaml           # Per-subsystem test values, deps, endpoint types
  analyze-results.py         # Parse results, compute tool coverage
  TESTER-CLAUDE.md           # System prompt for the tester Claude
  tasks/                     # 53 task files
  results/run-*/             # Per-run results
vm/                          # Test infrastructure
  setup.sh                   # Golden image builder (install + firstboot + upgrade)
  install.exp                # Automated pfSense installer
  firstboot.exp              # First-boot configuration
  upgrade-2.8.exp            # pfSense 2.7.2 → 2.8.1 upgrade
research/                    # Analysis documents and MCP best practices