proxy_clear_traffic

Instructions

Implementation Reference

• src/tools/traffic.ts:136-149 (handler)

  The handler for the proxy_clear_traffic tool. Calls proxyManager.clearTraffic() and returns JSON with 'cleared' count.

  server.tool(
    "proxy_clear_traffic",
    "Clear all captured traffic from the buffer.",
    {},
    async () => {
      const count = proxyManager.clearTraffic();
      return {
        content: [{
          type: "text",
          text: JSON.stringify({ status: "success", cleared: count }),
        }],
      };
    },
  );

• src/index.ts:65-65 (registration)

  The proxy_clear_traffic tool is registered when registerTrafficTools(server) is called during server setup.

  registerTrafficTools(server);

• src/tools/traffic.ts:10-150 (registration)

  The registerTrafficTools function registers proxy_clear_traffic (and the other 3 traffic tools) on the MCP server.

  export function registerTrafficTools(server: McpServer): void {
    server.tool(
      "proxy_list_traffic",
      "List captured HTTP exchanges with optional filters. Returns paginated results.",
      {
        limit: z.number().optional().default(50).describe("Max entries to return (default: 50)"),
        offset: z.number().optional().default(0).describe("Skip first N entries (default: 0)"),
        method_filter: z.string().optional().describe("Filter by HTTP method (e.g., GET, POST)"),
        url_filter: z.string().optional().describe("Filter by URL substring"),
        status_filter: z.number().optional().describe("Filter by response status code"),
        hostname_filter: z.string().optional().describe("Filter by hostname substring"),
        source_filter: z.enum(["explicit", "transparent"]).optional().describe("Filter by traffic source: 'explicit' (proxy-configured) or 'transparent' (iptables-redirected)"),
      },
      async ({ limit, offset, method_filter, url_filter, status_filter, hostname_filter, source_filter }) => {
        let traffic = proxyManager.getTraffic();
  
        if (method_filter) {
          const m = method_filter.toUpperCase();
          traffic = traffic.filter((t) => t.request.method === m);
        }
        if (url_filter) {
          const u = url_filter.toLowerCase();
          traffic = traffic.filter((t) => t.request.url.toLowerCase().includes(u));
        }
        if (status_filter !== undefined) {
          traffic = traffic.filter((t) => t.response?.statusCode === status_filter);
        }
        if (hostname_filter) {
          const h = hostname_filter.toLowerCase();
          traffic = traffic.filter((t) => t.request.hostname.toLowerCase().includes(h));
        }
        if (source_filter) {
          traffic = traffic.filter((t) => t.source === source_filter);
        }
  
        const total = traffic.length;
        const page = traffic.slice(offset, offset + limit);
  
        // Create summary view (no body previews to save space)
        const summaries = page.map((t) => ({
          id: t.id,
          timestamp: t.timestamp,
          source: t.source ?? "explicit",
          method: t.request.method,
          url: t.request.url,
          hostname: t.request.hostname,
          status: t.response?.statusCode ?? null,
          duration: t.duration ?? null,
          requestSize: t.request.bodySize,
          responseSize: t.response?.bodySize ?? null,
          ...(t.tls?.client?.ja3Fingerprint ? { ja3: t.tls.client.ja3Fingerprint } : {}),
          ...(t.tls?.client?.ja4Fingerprint ? { ja4: t.tls.client.ja4Fingerprint } : {}),
        }));
  
        return {
          content: [{
            type: "text",
            text: truncateResult({
              status: "success",
              total,
              // `count` is the historical alias kept for callers (and the
              // integration test) that read the post-filter total under that
              // name. Same value as `total`; do not diverge.
              count: total,
              offset,
              limit,
              showing: summaries.length,
              exchanges: summaries,
            }),
          }],
        };
      },
    );
  
    server.tool(
      "proxy_get_exchange",
      "Get full details of a captured HTTP exchange including headers and body previews.",
      {
        exchange_id: z.string().describe("Exchange ID from proxy_list_traffic"),
      },
      async ({ exchange_id }) => {
        const exchange = proxyManager.getExchange(exchange_id);
        if (!exchange) {
          return { content: [{ type: "text", text: JSON.stringify({ status: "error", error: `Exchange '${exchange_id}' not found` }) }] };
        }
        return {
          content: [{
            type: "text",
            text: truncateResult({ status: "success", exchange }),
          }],
        };
      },
    );
  
    server.tool(
      "proxy_search_traffic",
      "Full-text search across URLs, headers, and body previews of captured traffic.",
      {
        query: z.string().describe("Search string"),
        limit: z.number().optional().default(20).describe("Max results (default: 20)"),
      },
      async ({ query, limit }) => {
        const results = proxyManager.searchTraffic(query).slice(0, limit);
        const summaries = results.map((t) => ({
          id: t.id,
          timestamp: t.timestamp,
          method: t.request.method,
          url: t.request.url,
          status: t.response?.statusCode ?? null,
          duration: t.duration ?? null,
        }));
  
        return {
          content: [{
            type: "text",
            text: truncateResult({
              status: "success",
              query,
              matches: summaries.length,
              results: summaries,
            }),
          }],
        };
      },
    );
  
    server.tool(
      "proxy_clear_traffic",
      "Clear all captured traffic from the buffer.",
      {},
      async () => {
        const count = proxyManager.clearTraffic();
        return {
          content: [{
            type: "text",
            text: JSON.stringify({ status: "success", cleared: count }),
          }],
        };
      },
    );
  }

• src/tools/traffic.ts:139-139 (schema)

  The schema for proxy_clear_traffic is an empty object (no input parameters).

  {},

• src/state.ts:689-695 (helper)

  The ProxyManager.clearTraffic() helper method called by the handler. Clears the in-memory traffic ring buffer, pending requests, and pending raw bodies, returning the count of cleared items.

  clearTraffic(): number {
    const count = this.traffic.length;
    this.traffic.length = 0;
    this.pendingRequests.clear();
    this.pendingRawBodies.clear();
    return count;
  }