Firewalla MCP Server

# Service Analysis: Firewalla MCP Server **Analysis Date:** 2025-12-27 (Verified) **Analyst:** Explore-Dungeon (87404e50) **Repository:** https://github.com/drewrad8/mcps --- ## 1. Purpose A Model Context Protocol (MCP) server providing programmatic access to Firewalla network security devices. Enables AI assistants and MCP clients to: - Monitor network traffic and flows - Manage network devices - Configure security rules (allow/block/deny) - Analyze traffic patterns and security events - View Firewalla device status --- ## 2. Tech Stack | Component | Technology | Version | |-----------|------------|---------| | Runtime | Node.js | >= 18 | | Language | TypeScript | ES2022, ESNext modules | | MCP SDK | @modelcontextprotocol/sdk | ^1.17.4 | | Testing | Vitest | ^2.1.0 | | Coverage | @vitest/coverage-v8 | ^2.1.9 | | Linting | ESLint 9 (flat config) | ^9.39.2 | | Formatting | Prettier | ^3.7.4 | | Git Hooks | Husky + lint-staged | ^9.1.7 | | CI/CD | GitHub Actions | Node 18/20/22 matrix | --- ## 3. Entry Points | Entry Point | Description | |-------------|-------------| | `dist/server.js` | Compiled server executable | | `npm run start` | Run compiled server | | `npm run dev` | Build and run (development) | | `firewalla-mcp` | CLI binary (global install) | --- ## 4. API/Protocol ### Transport - **Protocol:** Model Context Protocol (MCP) - **Transport:** stdio (stdin/stdout) - **No network port exposed** - runs as subprocess ### Configuration **Option 1: Environment Variables (Recommended)** ```bash export FIREWALLA_URL="https://my.firewalla.com" export FIREWALLA_TOKEN="your-bearer-token" export FIREWALLA_ID="your-firewalla-device-id" export LOG_LEVEL="info" # debug, info, warn, error ``` **Option 2:** Runtime configuration via `configure_firewalla` tool ### MCP Tools (13) | Tool | Description | |------|-------------| | `configure_firewalla` | Set API credentials at runtime | | `get_config_status` | Check configuration state | | `query_network_flows` | Query flows with time filters | | `list_devices` | List all network devices | | `get_device_details` | Get device info by MAC | | `analyze_network_traffic` | Traffic analysis (summary, top talkers, blocked, security) | | `get_device_traffic` | Per-device traffic analysis | | `get_network_overview` | Comprehensive network overview | | `get_cloud_rules` | Active cloud security rules | | `get_traffic_trends` | Traffic trends (24h/7d/30d) | | `get_firewalla_status` | Firewalla device status | | `search_devices` | Search by name/IP/MAC | | `update_device_rules` | Modify device security rules | ### Firewalla API Endpoints | Endpoint | Method | Purpose | |----------|--------|---------| | `/v1/flows/query` | POST | Query network flows | | `/v1/device/list` | GET | List devices | | `/v1/rule/targets` | GET | Network targets | | `/v1/rule/cloud/list` | GET | Cloud rules | | `/v1/rule/batchUpdate` | POST | Update rules | | `/v1/dashboard/trend` | GET | Traffic trends | | `/v1/box/list` | GET | Firewalla status | --- ## 5. Status ### Overall: **Production Ready** ### Runtime Verification (2025-12-27) ``` ✓ server.test.ts (90 tests) 1156ms Test Files 1 passed (1) Tests 90 passed (90) ``` | Aspect | Status | |--------|--------| | Core Implementation | Complete (13 tools) | | TypeScript | Strict mode, ES2022 | | Error Handling | Custom error classes + retry | | Logging | Structured JSON to stderr | | Testing | **90 tests passing**, 70% coverage | | CI/CD | GitHub Actions | | Code Quality | ESLint + Prettier + Husky | | Documentation | README + CLAUDE.md | --- ## 6. Architecture ``` firewalla/ ├── server.ts # Main implementation (~1,800 lines) ├── server.test.ts # Test suite (90 tests) ├── dist/ # Compiled output ├── api_samples/ # Reference API responses ├── package.json # Dependencies & scripts ├── tsconfig.json # TypeScript config ├── vitest.config.ts # Test config ├── eslint.config.js # ESLint config ├── .prettierrc # Prettier config └── CLAUDE.md # Dev guidelines ``` ### Key Classes | Class | Purpose | |-------|---------| | `Logger` | Structured JSON logging to stderr | | `FirewallaAPI` | HTTP client with retry logic | | `FirewallaMCPServer` | MCP server with 13 tools | ### Error Classes | Class | Use Case | |-------|----------| | `FirewallaAPIError` | Base error with status code | | `FirewallaAuthError` | 401/403 failures (non-retryable) | | `FirewallaNetworkError` | Connection errors (retryable) | | `FirewallaRateLimitError` | 429 with Retry-After | --- ## 7. Dependencies ### Production ```json { "@modelcontextprotocol/sdk": "^1.17.4" } ``` ### Development ```json { "@eslint/js": "^9.39.2", "@types/node": "^24.3.0", "@vitest/coverage-v8": "^2.1.9", "eslint": "^9.39.2", "eslint-config-prettier": "^10.1.8", "husky": "^9.1.7", "lint-staged": "^16.2.7", "prettier": "^3.7.4", "typescript": "^5.9.2", "typescript-eslint": "^8.50.1", "vitest": "^2.1.0" } ``` ### External Services - Firewalla Cloud API (`my.firewalla.com`) - Physical Firewalla device on network --- ## 8. Error Handling | Scenario | Behavior | |----------|----------| | 5xx errors | Retry with exponential backoff | | Network failures | Retry up to 3 times | | Rate limiting (429) | Wait for Retry-After header | | Auth errors (401/403) | Fail immediately | | Timeouts | 30s default, retryable | **Retry Configuration:** - Max retries: 3 - Base delay: 1000ms - Max delay: 10000ms - Backoff: Exponential with jitter --- ## 9. Testing | Metric | Value | |--------|-------| | Total Tests | 90 | | Statement Coverage | 70.09% | | Function Coverage | 96.82% | | Branch Coverage | 84.71% | **Test Categories:** - API client (queryFlows, listDevices, getDevice) - Error recovery (retry, rate limits, network errors) - Custom error classes - Logger functionality - MCP tool handlers - Traffic analysis helpers **Commands:** ```bash npm test # Run tests npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` --- ## 10. CI/CD **GitHub Actions** (`.github/workflows/ci.yml`): | Job | Purpose | |-----|---------| | Test | Run tests on Node 18, 20, 22 | | Coverage | Upload to Codecov | | Lint | Type check + ESLint + Prettier | **Badges:** - CI status - Codecov coverage --- ## 11. Code Quality | Tool | Configuration | |------|---------------| | ESLint | Flat config, typescript-eslint | | Prettier | Single quotes, trailing commas, 100 char width | | Husky | Pre-commit hooks | | lint-staged | Run ESLint + Prettier on staged files | **Commands:** ```bash npm run lint # Check issues npm run lint:fix # Auto-fix npm run format # Format all files npm run format:check # Verify formatting ``` --- ## 12. Recommendations ### Ready for Production All core functionality implemented, tested, and documented. ### Future Enhancements 1. **Integration tests** with mock Firewalla API 2. **WebSocket support** for real-time events 3. **Caching layer** for frequent queries 4. **Additional tools** (bandwidth alerts, anomaly detection) ### Remaining Coverage (~30%) - MCP tool schema definitions (static boilerplate) - Shutdown signal handlers (difficult to unit test) --- ## Appendix: Quick Start ```bash # Clone and setup git clone https://github.com/drewrad8/mcps.git cd mcps/firewalla npm install npm run build # Configure export FIREWALLA_URL="https://my.firewalla.com" export FIREWALLA_TOKEN="your-token" export FIREWALLA_ID="your-device-id" # Run npm run start ``` --- ## License MIT