har-mcp 0.1.0

package/src/tools/read-har/index.ts

@@ -0,0 +1,393 @@
+/**
+ * Read HAR Tool
+ *
+ * Reads and analyzes HAR (HTTP Archive) files with multiple output modes
+ * and filtering capabilities. Returns LLM-friendly markdown output.
+ */
+
+import * as fs from "node:fs/promises"
+import * as path from "node:path"
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { z } from "zod"
+import { HarFileSchema } from "../../types/har.ts"
+import { getDetailedJsonError, repairTruncatedHar } from "./repair.ts"
+
+// Re-export schema and types
+export { readHarSchema, type ReadHarInput, type ReadHarInputRaw } from "./schema.ts"
+import type { ReadHarInput } from "./schema.ts"
+
+// Re-export helper functions
+export {
+  formatBytes,
+  formatDuration,
+  matchUrl,
+  matchStatus,
+  getContentTypeCategory,
+  truncateUrl,
+  getUrlPath,
+  isError,
+  getResponseSize,
+  getTotalTiming,
+  identifyUrlPatterns,
+  getCodeFenceLanguage,
+  formatContentForDisplay,
+} from "./helpers.ts"
+import { getResponseSize } from "./helpers.ts"
+
+// Re-export filter types and functions
+export { type IndexedEntry, filterEntries, sortEntries } from "./filters.ts"
+import { type IndexedEntry, filterEntries, sortEntries } from "./filters.ts"
+
+// Re-export formatters
+export {
+  formatSummary,
+  formatList,
+  formatEntryDetail,
+  formatEntryContent,
+  formatTimeline,
+  formatStats,
+  formatSizeAnalysis,
+  formatCookiesAnalysis,
+} from "./formatters/index.ts"
+import {
+  formatCookiesAnalysis,
+  formatEntryContent,
+  formatEntryDetail,
+  formatList,
+  formatSizeAnalysis,
+  formatStats,
+  formatSummary,
+  formatTimeline,
+} from "./formatters/index.ts"
+
+// ============================================================================
+// Main Handler
+// ============================================================================
+
+/**
+ * Handler function for the read_har tool.
+ */
+export async function readHarHandler(input: ReadHarInput): Promise<string> {
+  // Read and parse the HAR file
+  const filePath = input.path
+  let fileContent: string
+
+  try {
+    fileContent = await fs.readFile(filePath, "utf-8")
+  } catch (err) {
+    const error = err as { code?: string; message: string }
+    if (error.code === "ENOENT") {
+      throw new Error(`HAR file not found: ${filePath}`)
+    }
+    if (error.code === "EACCES") {
+      throw new Error(`Permission denied reading HAR file: ${filePath}`)
+    }
+    throw new Error(`Failed to read HAR file: ${error.message}`)
+  }
+
+  let harData: unknown
+  let repairWarning = ""
+  try {
+    harData = JSON.parse(fileContent)
+  } catch (jsonError) {
+    // Try to repair truncated HAR files
+    const errorDetails = getDetailedJsonError(jsonError, fileContent)
+    const repairResult = repairTruncatedHar(fileContent, errorDetails)
+
+    if (repairResult.success && repairResult.repairedJson) {
+      harData = JSON.parse(repairResult.repairedJson)
+      repairWarning = `\n\n> **Warning**: HAR file was truncated. Recovered ${repairResult.entriesRecovered} entries using ${repairResult.repairMethod} repair method. Some entries may be missing.\n`
+    } else {
+      throw new Error(`Invalid JSON in HAR file: ${errorDetails}`)
+    }
+  }
+
+  // Validate HAR structure
+  const parseResult = HarFileSchema.safeParse(harData)
+  if (!parseResult.success) {
+    const issues = parseResult.error.issues
+      .slice(0, 3)
+      .map(i => i.message)
+      .join("; ")
+    throw new Error(`Invalid HAR file format: ${issues}`)
+  }
+
+  const harFile = parseResult.data
+  const filename = path.basename(filePath)
+
+  // Create indexed entries
+  let indexedEntries: IndexedEntry[] = harFile.log.entries.map((entry, index) => ({
+    index,
+    entry,
+  }))
+
+  // Apply filters
+  indexedEntries = filterEntries(indexedEntries, input.filter)
+
+  // Apply sorting
+  indexedEntries = sortEntries(indexedEntries, input.sort)
+
+  // Mode-specific handling
+  const mode = input.mode
+  const format = input.format ?? "markdown"
+
+  // Helper to add repair warning to output
+  const addWarning = (output: string): string => {
+    if (repairWarning && format === "markdown") {
+      return repairWarning + output
+    }
+    return output
+  }
+
+  if (mode === "summary") {
+    // Summary doesn't use pagination, operates on all entries
+    if (format === "json") {
+      const methodCounts: Record<string, number> = {}
+      const statusCounts: Record<string, number> = {}
+      for (const entry of harFile.log.entries) {
+        methodCounts[entry.request.method] = (methodCounts[entry.request.method] || 0) + 1
+        const statusClass = `${Math.floor(entry.response.status / 100)}xx`
+        statusCounts[statusClass] = (statusCounts[statusClass] || 0) + 1
+      }
+      const jsonData = {
+        file: filename,
+        mode: "summary",
+        version: harFile.log.version,
+        creator: harFile.log.creator,
+        totalEntries: harFile.log.entries.length,
+        pages: harFile.log.pages?.length || 0,
+        methods: methodCounts,
+        statuses: statusCounts,
+      }
+      return JSON.stringify(jsonData, null, 2)
+    }
+    return addWarning(formatSummary(harFile, filename))
+  }
+
+  if (mode === "list") {
+    // Apply pagination
+    const page = input.page
+    const pageSize = input.pageSize
+    const totalCount = indexedEntries.length
+    const start = (page - 1) * pageSize
+    const paginatedEntries = indexedEntries.slice(start, start + pageSize)
+
+    if (format === "json") {
+      const jsonData = {
+        file: filename,
+        mode: "list",
+        pagination: { page, pageSize, total: totalCount },
+        entries: paginatedEntries.map(({ index, entry }) => ({
+          index,
+          method: entry.request.method,
+          url: entry.request.url,
+          status: entry.response.status,
+          size: getResponseSize(entry),
+          time: entry.time,
+        })),
+      }
+      return JSON.stringify(jsonData, null, 2)
+    }
+
+    return addWarning(formatList(paginatedEntries, filename, page, pageSize, totalCount, input.filter))
+  }
+
+  if (mode === "detail") {
+    // Detail mode - show specific entries or paginated list
+    const include = {
+      headers: input.include?.headers ?? false,
+      cookies: input.include?.cookies ?? false,
+      timing: input.include?.timing ?? true,
+      queryParams: input.include?.queryParams ?? true,
+    }
+
+    if (input.entries && input.entries.length > 0) {
+      // Show specific entries
+      const results: string[] = []
+
+      for (const idx of input.entries) {
+        const found = indexedEntries.find(ie => ie.index === idx)
+        if (found) {
+          results.push(formatEntryDetail(found.index, found.entry, include))
+        } else {
+          results.push(`# Entry #${idx}\n\n> Entry not found or filtered out`)
+        }
+      }
+
+      return addWarning(results.join("\n\n---\n\n"))
+    }
+    // Paginate and show first entry on page
+    const page = input.page
+    const pageSize = input.pageSize
+    const start = (page - 1) * pageSize
+    const paginatedEntries = indexedEntries.slice(start, start + pageSize)
+
+    if (paginatedEntries.length === 0) {
+      return addWarning("# No entries found\n\nNo entries match the current filter criteria.")
+    }
+
+    const results: string[] = []
+    for (const ie of paginatedEntries) {
+      results.push(formatEntryDetail(ie.index, ie.entry, include))
+    }
+
+    const header = `**Showing entries ${start + 1}-${start + paginatedEntries.length} of ${indexedEntries.length}**\n\n`
+    return addWarning(header + results.join("\n\n---\n\n"))
+  }
+
+  if (mode === "content") {
+    // Content mode - requires entries parameter
+    if (!input.entries || input.entries.length === 0) {
+      throw new Error('Content mode requires the "entries" parameter with at least one entry index')
+    }
+
+    const options = {
+      includeRequestBody: input.contentOptions?.includeRequestBody ?? false,
+      includeResponseBody: input.contentOptions?.includeResponseBody ?? true,
+      maxContentLength: input.contentOptions?.maxContentLength ?? 50000,
+    }
+
+    const results: string[] = []
+
+    for (const idx of input.entries) {
+      const found = harFile.log.entries[idx]
+      if (found) {
+        results.push(formatEntryContent(idx, found, options))
+      } else {
+        results.push(`# Entry #${idx}\n\n> Entry index out of range (0-${harFile.log.entries.length - 1})`)
+      }
+    }
+
+    return addWarning(results.join("\n\n---\n\n"))
+  }
+
+  if (mode === "timeline") {
+    return addWarning(formatTimeline(harFile, filename, input.pageSize, input.page))
+  }
+
+  if (mode === "cookies") {
+    return addWarning(formatCookiesAnalysis(harFile, filename))
+  }
+
+  if (mode === "size") {
+    return addWarning(formatSizeAnalysis(harFile, filename))
+  }
+
+  if (mode === "stats") {
+    return addWarning(formatStats(harFile, filename))
+  }
+
+  throw new Error(`Unknown mode: ${mode}`)
+}
+
+// ============================================================================
+// Tool Registration
+// ============================================================================
+
+/**
+ * Registers the read_har tool with the MCP server.
+ */
+export function registerReadHarTool(server: McpServer): void {
+  server.tool(
+    "read_har",
+    "Reads and analyzes HAR (HTTP Archive) files. Supports multiple output modes: summary (overview stats), list (paginated entries), detail (full metadata), and content (with response bodies). Includes filtering, sorting, and pagination.",
+    {
+      path: z.string().describe("Path to the HAR file"),
+
+      mode: z
+        .enum(["summary", "list", "detail", "content", "timeline", "cookies", "size", "stats"])
+        .default("summary")
+        .describe(
+          "Output mode: summary (overview), list (entries), detail (full metadata), content (with body), timeline (waterfall visualization), cookies (cookie propagation tracking), size (payload size analysis), stats (aggregate by endpoint)",
+        ),
+
+      page: z.number().int().min(1).default(1).describe("Page number for pagination"),
+      pageSize: z.number().int().min(1).max(100).default(20).describe("Number of entries per page"),
+
+      entries: z
+        .array(z.number().int().min(0))
+        .max(10)
+        .optional()
+        .describe("Specific entry indexes to return (required for content mode)"),
+
+      filter: z
+        .object({
+          url: z.string().optional().describe("URL pattern (substring, glob with *, or ~regex)"),
+          method: z
+            .union([z.string(), z.array(z.string())])
+            .optional()
+            .describe("HTTP method(s) to filter"),
+          status: z
+            .union([
+              z.number(),
+              z.string().regex(/^\d{1}xx$/i),
+              z.object({ min: z.number().optional(), max: z.number().optional() }),
+            ])
+            .optional()
+            .describe("Status code, pattern (e.g., 4xx), or range"),
+          contentType: z.string().optional().describe("Response content type filter"),
+          minDuration: z.number().optional().describe("Minimum request duration in ms"),
+          hasError: z.boolean().optional().describe("Filter to only errors (4xx/5xx)"),
+          bodyContains: z.string().optional().describe("Filter entries whose response body contains this string"),
+        })
+        .optional()
+        .describe("Filter criteria for entries"),
+
+      include: z
+        .object({
+          headers: z.boolean().default(false).describe("Include headers in detail mode"),
+          cookies: z.boolean().default(false).describe("Include cookies in detail mode"),
+          timing: z.boolean().default(true).describe("Include timing breakdown in detail mode"),
+          queryParams: z.boolean().default(true).describe("Include query params in detail mode"),
+        })
+        .optional()
+        .describe("Options for detail mode"),
+
+      contentOptions: z
+        .object({
+          includeRequestBody: z.boolean().default(false).describe("Include request body in content mode"),
+          includeResponseBody: z.boolean().default(true).describe("Include response body in content mode"),
+          maxContentLength: z.number().default(50000).describe("Max content length before truncation"),
+        })
+        .optional()
+        .describe("Options for content mode"),
+
+      sort: z
+        .object({
+          by: z.enum(["index", "time", "duration", "size", "status"]).default("index").describe("Field to sort by"),
+          order: z.enum(["asc", "desc"]).default("asc").describe("Sort order"),
+        })
+        .optional()
+        .describe("Sorting options"),
+
+      format: z
+        .enum(["markdown", "json"])
+        .default("markdown")
+        .describe("Output format: markdown (default) or json for programmatic use"),
+    },
+    async args => {
+      try {
+        const result = await readHarHandler(args as ReadHarInput)
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: result,
+            },
+          ],
+        }
+      } catch (err) {
+        const error = err as Error
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error: ${error.message}`,
+            },
+          ],
+          isError: true,
+        }
+      }
+    },
+  )
+}

package/src/tools/read-har/repair.ts

@@ -0,0 +1,277 @@
+/**
+ * HAR File Repair Utilities
+ *
+ * Handles truncated or malformed HAR files from browser exports.
+ * Chrome and other browsers sometimes export incomplete HAR files,
+ * especially with large response bodies (like base64-encoded content).
+ */
+
+export interface RepairResult {
+  success: boolean
+  repairedJson?: string
+  entriesRecovered?: number
+  originalError: string
+  repairMethod?: string
+}
+
+/**
+ * Attempts to repair a truncated HAR JSON string.
+ *
+ * HAR files exported from Chrome can be truncated mid-content, especially
+ * when dealing with large base64-encoded response bodies. This function
+ * attempts to find the last complete entry and close the JSON structure.
+ *
+ * @param jsonStr - The potentially truncated JSON string
+ * @param originalError - The original JSON parse error message
+ * @returns RepairResult with success status and repaired JSON if successful
+ */
+export function repairTruncatedHar(jsonStr: string, originalError: string): RepairResult {
+  // First, try to parse as-is (maybe it's valid)
+  try {
+    JSON.parse(jsonStr)
+    return { success: true, repairedJson: jsonStr, originalError }
+  } catch {
+    // Continue with repair attempts
+  }
+
+  // Strategy 1: Chrome-specific - find entries by _workerRespondWithSettled field
+  // Chrome DevTools HAR always ends timings with this field
+  const result1 = tryRepairByChromeTimings(jsonStr, originalError)
+  if (result1.success) {
+    return result1
+  }
+
+  // Strategy 2: Find the last complete entry by looking for "timings" object endings
+  // HAR entries end with a "timings" object, so we can find complete entries this way
+  const result2 = tryRepairByTimings(jsonStr, originalError)
+  if (result2.success) {
+    return result2
+  }
+
+  // Strategy 3: Find last complete entry boundary (},{ pattern between entries)
+  const result3 = tryRepairByEntryBoundary(jsonStr, originalError)
+  if (result3.success) {
+    return result3
+  }
+
+  // Strategy 4: Binary search for a valid truncation point
+  const result4 = tryRepairByBinarySearch(jsonStr, originalError)
+  if (result4.success) {
+    return result4
+  }
+
+  return {
+    success: false,
+    originalError,
+  }
+}
+
+/**
+ * Chrome DevTools specific repair - looks for _workerRespondWithSettled field.
+ * Chrome's HAR format always ends timings with this field.
+ */
+function tryRepairByChromeTimings(jsonStr: string, originalError: string): RepairResult {
+  // Chrome's timings end with _workerRespondWithSettled, followed by } (timings) and } (entry)
+  const entryEndPattern = /"_workerRespondWithSettled"\s*:\s*[\d.-]+\s*\}\s*\}/g
+  const matches = [...jsonStr.matchAll(entryEndPattern)]
+
+  if (matches.length === 0) {
+    return { success: false, originalError }
+  }
+
+  // Try from the last match backwards
+  for (let i = matches.length - 1; i >= Math.max(0, matches.length - 20); i--) {
+    const match = matches[i]
+    if (!match || match.index === undefined) continue
+
+    const pos = match.index + match[0].length
+    // HAR structure: { log: { entries: [...] } }
+    // After entry }, we close: entries ], log }, root }
+    const testStr = `${jsonStr.substring(0, pos)}]}}`
+
+    try {
+      const parsed = JSON.parse(testStr)
+      return {
+        success: true,
+        repairedJson: testStr,
+        entriesRecovered: parsed.log?.entries?.length ?? 0,
+        originalError,
+        repairMethod: "chrome-timings",
+      }
+    } catch {
+      // Continue to next candidate
+    }
+  }
+
+  return { success: false, originalError }
+}
+
+/**
+ * Try to repair by finding the last complete "timings" object.
+ * Entries in HAR format end with a "timings" object containing timing data.
+ */
+function tryRepairByTimings(jsonStr: string, originalError: string): RepairResult {
+  // Find all complete timings objects
+  // Pattern matches "timings":{...} where the inner content has no nested braces
+  const timingsPattern = /"timings"\s*:\s*\{[^{}]*\}/g
+  const matches = [...jsonStr.matchAll(timingsPattern)]
+
+  if (matches.length === 0) {
+    return { success: false, originalError }
+  }
+
+  // Try from the last match backwards
+  for (let i = matches.length - 1; i >= Math.max(0, matches.length - 20); i--) {
+    const match = matches[i]
+    if (!match || match.index === undefined) continue
+
+    let pos = match.index + match[0].length
+
+    // Skip whitespace after timings
+    while (pos < jsonStr.length && /\s/.test(jsonStr[pos] ?? "")) {
+      pos++
+    }
+
+    // After timings should come } to close the entry
+    if (jsonStr[pos] === "}") {
+      // Try closing the structure: entry } + entries ] + log } + root }
+      const testStr = `${jsonStr.substring(0, pos + 1)}]}}`
+      try {
+        const parsed = JSON.parse(testStr)
+        return {
+          success: true,
+          repairedJson: testStr,
+          entriesRecovered: parsed.log?.entries?.length ?? 0,
+          originalError,
+          repairMethod: "timings-boundary",
+        }
+      } catch {
+        // Continue to next candidate
+      }
+    }
+  }
+
+  return { success: false, originalError }
+}
+
+/**
+ * Try to repair by finding entry boundaries (the pattern between entries).
+ */
+function tryRepairByEntryBoundary(jsonStr: string, originalError: string): RepairResult {
+  // Look for patterns that indicate entry boundaries
+  // Entries are separated by },{ or },"startedDateTime"
+  const boundaryPattern = /\}\s*,\s*\{/g
+  const boundaries: number[] = []
+
+  let match: RegExpExecArray | null = boundaryPattern.exec(jsonStr)
+  while (match !== null) {
+    // Position after the closing brace of the completed entry
+    boundaries.push(match.index + 1)
+    match = boundaryPattern.exec(jsonStr)
+  }
+
+  if (boundaries.length === 0) {
+    return { success: false, originalError }
+  }
+
+  // Try from the end backwards
+  for (let i = boundaries.length - 1; i >= Math.max(0, boundaries.length - 50); i--) {
+    const pos = boundaries[i]
+    if (pos === undefined) continue
+    const testStr = `${jsonStr.substring(0, pos)}]}}` // ] closes entries, }} closes log and root
+    try {
+      const parsed = JSON.parse(testStr)
+      return {
+        success: true,
+        repairedJson: testStr,
+        entriesRecovered: parsed.log?.entries?.length ?? 0,
+        originalError,
+        repairMethod: "entry-boundary",
+      }
+    } catch {
+      // Continue to next candidate
+    }
+  }
+
+  return { success: false, originalError }
+}
+
+/**
+ * Binary search for a valid truncation point.
+ * This is slower but more thorough.
+ */
+function tryRepairByBinarySearch(jsonStr: string, originalError: string): RepairResult {
+  // Find all positions where we have a closing brace
+  const closingBraces: number[] = []
+  for (let i = 0; i < jsonStr.length; i++) {
+    if (jsonStr[i] === "}") {
+      closingBraces.push(i)
+    }
+  }
+
+  if (closingBraces.length === 0) {
+    return { success: false, originalError }
+  }
+
+  // Binary search for the rightmost valid truncation point
+  let lo = 0
+  let hi = closingBraces.length - 1
+  let lastValid: { pos: number; entries: number } | null = null
+
+  while (lo <= hi) {
+    const mid = Math.floor((lo + hi) / 2)
+    const pos = closingBraces[mid]
+    if (pos === undefined) {
+      hi = mid - 1
+      continue
+    }
+    const testStr = `${jsonStr.substring(0, pos + 1)}]}}`
+
+    try {
+      const parsed = JSON.parse(testStr)
+      lastValid = { pos, entries: parsed.log?.entries?.length ?? 0 }
+      lo = mid + 1 // Try to find a later valid point
+    } catch {
+      hi = mid - 1 // This point is invalid, try earlier
+    }
+  }
+
+  if (lastValid) {
+    return {
+      success: true,
+      repairedJson: `${jsonStr.substring(0, lastValid.pos + 1)}]}}`,
+      entriesRecovered: lastValid.entries,
+      originalError,
+      repairMethod: "binary-search",
+    }
+  }
+
+  return { success: false, originalError }
+}
+
+/**
+ * Extract a more descriptive error message from JSON parse errors.
+ */
+export function getDetailedJsonError(error: unknown, fileContent: string): string {
+  const err = error as Error
+  const message = err.message || "Unknown error"
+
+  // Try to extract position information
+  const posMatch = message.match(/position (\d+)/i)
+  if (posMatch?.[1]) {
+    const pos = Number.parseInt(posMatch[1], 10)
+    const lines = fileContent.substring(0, pos).split("\n")
+    const line = lines.length
+    const lastLine = lines[lines.length - 1]
+    const column = lastLine ? lastLine.length : 0
+
+    // Get context around the error
+    const start = Math.max(0, pos - 50)
+    const end = Math.min(fileContent.length, pos + 50)
+    const context = fileContent.substring(start, end)
+
+    return `JSON parse error at line ${line}, column ${column}: ${message}\nContext: ...${context}...`
+  }
+
+  return `JSON parse error: ${message}`
+}