opnsense_diag_traceroute
Run a traceroute diagnostic from your OPNsense firewall to any IP address or hostname to trace the network path.
Instructions
Run a traceroute from the OPNsense firewall to a destination
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | IP address or hostname to traceroute |
Implementation Reference
- src/tools/diagnostics.ts:19-21 (schema)Zod schema for traceroute input validation — requires a non-empty 'address' string.
const TracerouteSchema = z.object({ address: z.string().min(1, "Address is required"), }); - src/tools/diagnostics.ts:78-91 (registration)Tool definition registered in diagnosticsToolDefinitions array — defines name, description, and input schema for the MCP ListTools response.
{ name: "opnsense_diag_traceroute", description: "Run a traceroute from the OPNsense firewall to a destination", inputSchema: { type: "object" as const, properties: { address: { type: "string", description: "IP address or hostname to traceroute", }, }, required: ["address"], }, }, - src/tools/diagnostics.ts:357-370 (handler)Handler for the traceroute tool — validates args with TracerouteSchema, then calls POST /diagnostics/traceroute/set on the OPNsense API (synchronous in 24.7+).
case "opnsense_diag_traceroute": { const parsed = TracerouteSchema.parse(args); // OPNsense 24.7+: set is synchronous — executes traceroute and returns results const result = await client.post("/diagnostics/traceroute/set", { traceroute: { settings: { hostname: parsed.address, }, }, }); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } - src/tools/diagnostics.ts:267-271 (helper)Main dispatch function that routes tool calls by name to the correct case block — the traceroute case is handled at line 357.
export async function handleDiagnosticsTool( name: string, args: Record<string, unknown>, client: OPNsenseClient, ): Promise<{ content: Array<{ type: "text"; text: string }> }> { - src/index.ts:83-95 (registration)MCP CallTool handler dispatches to the handler function retrieved from toolHandlers map — the diagnostics tools (including traceroute) are registered at line 61.
server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; const handler = toolHandlers.get(name); if (!handler) { return { content: [{ type: 'text' as const, text: `Unknown tool: ${name}` }], isError: true, }; } return handler(name, (args ?? {}) as Record<string, unknown>, client); });