OPNSense MCP Server

# Macro Recording System Implementation Summary ## Overview Successfully implemented a comprehensive macro recording system for the OPNsense MCP server that enables users to record API interactions and automatically generate reusable MCP tools. This "clever approach" makes extending the server incredibly easy. ## What Was Implemented ### 1. Core Architecture #### Macro Types (`src/macro/types.ts`) - Complete TypeScript interfaces for the macro system - APICall, MacroRecording, MacroParameter types - Analysis and tool generation interfaces - Storage and playback options #### Macro Recorder (`src/macro/recorder.ts`) - Main recording engine with state management - API call capture and parameter substitution - Playback with dry-run support - Macro comparison and merging capabilities #### API Client Integration (`src/api/client.ts`) - Modified to support recording via callback - Records all HTTP methods (GET, POST, PUT, DELETE) - Captures request/response data and timing - Error state recording ### 2. Intelligent Analysis #### Macro Analyzer (`src/macro/analyzer.ts`) - Pattern detection (CRUD operations) - Automatic parameter discovery - Value type inference - Validation rule generation - Detects: - IP addresses with regex validation - Port numbers with range validation - UUIDs from responses - Domain names - Repeated values that should be parameterized ### 3. Tool Generation #### Tool Generator (`src/macro/generator.ts`) - Generates complete TypeScript implementations - Creates MCP tool definitions - Parameter validation code - Error handling - Return value formatting ### 4. Storage System #### Macro Storage (`src/macro/storage.ts`) - File-based persistence - Index management for fast lookup - Export/import functionality - Search by name, tags, category - Automatic backup of recordings ### 5. MCP Integration Added 9 new tools to the MCP server: - `macro_start_recording` - Begin recording API calls - `macro_stop_recording` - Stop and save recording - `macro_list` - List all saved macros - `macro_play` - Execute a macro with parameters - `macro_delete` - Remove a macro - `macro_analyze` - Analyze patterns and parameters - `macro_generate_tool` - Create MCP tool from macro - `macro_export` - Export macros to file - `macro_import` - Import macros from file ### 6. Resources Added new MCP resource: - `opnsense://macros` - List all recorded macros ## Key Features ### 1. Automatic Parameter Detection The analyzer examines recorded values and identifies: ```javascript // Detects this is an IP that should be parameterized "address": "192.168.1.100" → parameter: "address" with IP validation // Detects VLAN tag pattern "tag": "100" → parameter: "vlanTag" with range 1-4094 // Detects repeated values Multiple uses of "igc3" → parameter: "interfaceName" ``` ### 2. Smart Tool Generation Generates production-ready TypeScript code: ```typescript // Input: Recorded macro // Output: Complete tool implementation with: - Parameter validation - Error handling - Proper typing - API call sequencing - Result formatting ``` ### 3. Flexible Playback ```javascript // Dry run to test await macro_play({ id: "macro-id", dryRun: true, parameters: { vlanTag: "200" } }); // Execute with substitution await macro_play({ id: "macro-id", parameters: { vlanTag: "200", interfaceName: "igc2" } }); ``` ## Usage Workflow 1. **Record**: Start recording → perform actions → stop recording 2. **Analyze**: Review detected patterns and parameters 3. **Generate**: Create reusable tool from recording 4. **Share**: Export/import macros between systems ## Benefits 1. **API Discovery**: Learn OPNsense API by recording UI actions 2. **Rapid Development**: Create tools without writing code 3. **Complex Workflows**: Capture multi-step processes 4. **Team Collaboration**: Share macros via export/import 5. **Self-Extending**: Use the server to build itself ## Example Generated Tool From a simple VLAN creation recording: ```typescript case 'create_vlan_100': { // Full parameter validation if (!args || !args.vlanTag || !args.interfaceName) { throw new McpError(ErrorCode.InvalidRequest, 'Required parameters missing'); } try { // Parameterized API call const result = await this.client.post('/interfaces/vlan/addItem', { vlan: { if: args.interfaceName, tag: args.vlanTag, descr: `VLAN ${args.vlanTag}` } }); return { content: [{ type: 'text', text: `Created VLAN ${args.vlanTag} with UUID: ${result.uuid}` }] }; } catch (error: any) { throw new McpError(ErrorCode.InternalError, error.message); } } ``` ## Technical Achievements 1. **Zero Configuration**: Works out of the box 2. **Type Safety**: Full TypeScript support 3. **Intelligent Detection**: Minimal manual configuration needed 4. **Production Ready**: Generated code follows best practices 5. **Extensible**: Easy to add new detection patterns ## Storage Macros stored at: - Default: `.opnsense-macros/` directory - Custom: Via `MACRO_STORAGE_PATH` environment variable ## Future Enhancements 1. **Dynamic Tool Loading**: Load generated tools without restart 2. **Visual Macro Editor**: Web UI for editing macros 3. **Macro Marketplace**: Share macros publicly 4. **AI Enhancement**: Use LLM to improve parameter detection 5. **Workflow Builder**: Combine multiple macros ## Conclusion The macro recording system transforms the OPNsense MCP server from a static tool into a dynamic, self-extending platform. Users can now create custom tools by simply performing actions while recording, making API integration accessible to non-programmers while accelerating development for experts.