proxy-mcp

Instructions

Implementation Reference

• src/tools/sessions.ts:140-176 (handler)

  Implementation of the `proxy_query_session` MCP tool handler, which calls `proxyManager.querySession` to fetch filtered/paginated session exchange data.

    "proxy_query_session",
    "Query indexed session exchanges with filters and pagination.",
    {
      session_id: z.string().describe("Session ID"),
      limit: z.number().optional().default(50),
      offset: z.number().optional().default(0),
      sort: z.enum(["asc", "desc"]).optional().default("desc"),
      method: z.string().optional().describe("HTTP method filter"),
      hostname_contains: z.string().optional().describe("Filter by hostname substring"),
      url_contains: z.string().optional().describe("Filter by URL substring"),
      status_code: z.number().optional().describe("HTTP response status code filter"),
      from_ts: z.number().optional().describe("Unix ms lower-bound timestamp"),
      to_ts: z.number().optional().describe("Unix ms upper-bound timestamp"),
      text: z.string().optional().describe("Generic text filter"),
    },
    async ({ session_id, limit, offset, sort, method, hostname_contains, url_contains, status_code, from_ts, to_ts, text }) => {
      try {
        const result = await proxyManager.querySession(session_id, {
          limit,
          offset,
          sort,
          method,
          hostnameContains: hostname_contains,
          urlContains: url_contains,
          statusCode: status_code,
          fromTs: from_ts,
          toTs: to_ts,
          text,
        });
        return {
          content: [{ type: "text", text: truncateResult({ status: "success", ...result }) }],
        };
      } catch (e) {
        return { content: [{ type: "text", text: JSON.stringify({ status: "error", error: toError(e) }) }] };
      }
    },
  );

• src/state.ts:657-659 (handler)

  The `querySession` method in `ProxyManager`, which delegates the request to the `sessionStore`'s `querySession` method.

  async querySession(sessionId: string, query: SessionQuery): Promise<SessionQueryResult> {
    return await this.sessionStore.querySession(sessionId, query);
  }

• src/session-store.ts:541-577 (handler)

  The `querySession` method in `SessionStore`, which implements the logic for searching, filtering, sorting, and paginating session exchange records from the session's `index.ndjson` file.

  async querySession(sessionId: string, query: SessionQuery = {}): Promise<SessionQueryResult> {
    const entries = await this.readSessionIndex(sessionId);
    const method = query.method?.toUpperCase();
    const hostnameContains = query.hostnameContains?.toLowerCase();
    const urlContains = query.urlContains?.toLowerCase();
    const text = query.text?.toLowerCase();
  
    const filtered = entries.filter((e) => {
      if (method && e.method !== method) return false;
      if (hostnameContains && !e.hostname.toLowerCase().includes(hostnameContains)) return false;
      if (urlContains && !e.url.toLowerCase().includes(urlContains)) return false;
      if (query.statusCode !== undefined && e.statusCode !== query.statusCode) return false;
      if (query.fromTs !== undefined && e.timestamp < query.fromTs) return false;
      if (query.toTs !== undefined && e.timestamp > query.toTs) return false;
      if (text) {
        const hay = `${e.url}\n${e.hostname}\n${e.path}\n${e.exchangeId}\n${e.matchedRuleId ?? ""}`.toLowerCase();
        if (!hay.includes(text)) return false;
      }
      return true;
    });
  
    const sorted = filtered.sort((a, b) => {
      if (query.sort === "asc") return a.timestamp - b.timestamp;
      return b.timestamp - a.timestamp;
    });
  
    const offset = Math.max(0, query.offset ?? 0);
    const limit = Math.max(1, Math.min(5000, query.limit ?? 50));
    const items = sorted.slice(offset, offset + limit);
  
    return {
      total: sorted.length,
      limit,
      offset,
      items,
    };
  }