har-mcp 0.1.0

package/README.md

@@ -0,0 +1,261 @@
+# HAR MCP Server
+
+An MCP (Model Context Protocol) server for analyzing HAR (HTTP Archive) files with LLM-friendly output.
+
+**Runtime Requirement:** This server requires **Bun >= 1.0.0**.
+
+## Features
+
+- **Multiple analysis modes**: summary, list, detail, content, stats, timeline, size, cookies
+- **Powerful filtering**: URL patterns, HTTP methods, status codes, content types, duration, body content
+- **Sorting & pagination**: Sort by various fields, paginate large result sets
+- **Export capabilities**: Export entries as cURL commands
+- **JSON output**: Programmatic JSON output for integration
+- **Chrome DevTools support**: Full support for Chrome-exported HAR files with extension fields
+- **Truncated HAR repair**: Automatic recovery of truncated HAR files (common with large exports)
+
+## Installation
+
+```bash
+bun install
+```
+
+**This server only supports Bun runtime.**
+
+## Usage
+
+### With Claude Desktop
+
+After installing from npm, use `bunx`:
+
+```json
+{
+  "mcpServers": {
+    "har": {
+      "command": "bunx",
+      "args": ["har-mcp"]
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "har": {
+      "command": "bun",
+      "args": ["run", "/path/to/har-mcp/src/index.ts"]
+    }
+  }
+}
+```
+
+### With OpenCode
+
+After installing from npm, use `bunx`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "har": {
+        "type": "local",
+        "command": ["bunx", "har-mcp"]
+      }
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "har": {
+        "type": "local",
+        "command": ["bun", "run", "/path/to/har-mcp/src/index.ts"]
+      }
+    }
+  }
+}
+```
+
+### With MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector bun run src/index.ts
+```
+
+## Tools
+
+### read_har
+
+Reads and analyzes HAR files with multiple output modes.
+
+**Parameters:**
+
+| Parameter  | Type     | Description                                                |
+| ---------- | -------- | ---------------------------------------------------------- |
+| `path`     | string   | **Required.** Path to the HAR file                         |
+| `mode`     | string   | Output mode (default: "summary")                           |
+| `filter`   | object   | Filter criteria                                            |
+| `sort`     | object   | Sorting options                                            |
+| `page`     | number   | Page number for pagination (default: 1)                    |
+| `pageSize` | number   | Entries per page (default: 20, max: 100)                   |
+| `entries`  | number[] | Specific entry indexes (required for content/detail modes) |
+| `format`   | string   | Output format: "markdown" or "json"                        |
+
+**Output Modes:**
+
+| Mode       | Description                                                        |
+| ---------- | ------------------------------------------------------------------ |
+| `summary`  | Overview statistics (total entries, methods, status codes, timing) |
+| `list`     | Paginated entry list with basic info                               |
+| `detail`   | Full metadata for specific entries (headers, timing, query params) |
+| `content`  | Response/request bodies for specific entries                       |
+| `stats`    | Aggregate statistics grouped by endpoint                           |
+| `timeline` | Text-based waterfall visualization                                 |
+| `size`     | Payload size analysis                                              |
+| `cookies`  | Cookie propagation tracking                                        |
+
+**Filter Options:**
+
+| Filter         | Type                       | Description                                               |
+| -------------- | -------------------------- | --------------------------------------------------------- |
+| `url`          | string                     | URL pattern (substring, glob with `*`, or `~regex`)       |
+| `method`       | string \| string[]         | HTTP method(s) to filter                                  |
+| `status`       | number \| string \| object | Status code, pattern (e.g., "4xx"), or range `{min, max}` |
+| `contentType`  | string                     | Response content type filter                              |
+| `minDuration`  | number                     | Minimum request duration in ms                            |
+| `hasError`     | boolean                    | Filter to errors only (4xx/5xx)                           |
+| `bodyContains` | string                     | Filter by response body content                           |
+
+**Sort Options:**
+
+| Field      | Description                |
+| ---------- | -------------------------- |
+| `index`    | Original order in HAR file |
+| `time`     | Request start time         |
+| `duration` | Request duration           |
+| `size`     | Response size              |
+| `status`   | HTTP status code           |
+
+**Examples:**
+
+```javascript
+// Get summary of a HAR file
+read_har(path: "/path/to/file.har")
+
+// List all POST requests
+read_har(path: "...", mode: "list", filter: { method: "POST" })
+
+// Find slow requests (over 1 second)
+read_har(path: "...", mode: "list", filter: { minDuration: 1000 }, sort: { by: "duration", order: "desc" })
+
+// Get response body for first two entries
+read_har(path: "...", mode: "content", entries: [0, 1])
+
+// Find requests matching URL pattern
+read_har(path: "...", mode: "list", filter: { url: "*/api/*" })
+
+// Filter by regex
+read_har(path: "...", mode: "list", filter: { url: "~\\.json$" })
+
+// Find errors
+read_har(path: "...", mode: "list", filter: { hasError: true })
+
+// Filter by status range
+read_har(path: "...", mode: "list", filter: { status: { min: 400, max: 499 } })
+
+// Analyze request sizes
+read_har(path: "...", mode: "size")
+
+// View timeline waterfall
+read_har(path: "...", mode: "timeline")
+
+// Track cookies
+read_har(path: "...", mode: "cookies")
+
+// Get JSON output
+read_har(path: "...", mode: "summary", format: "json")
+```
+
+### export_har_curl
+
+Export HAR entries as cURL commands for replay or debugging.
+
+**Parameters:**
+
+| Parameter        | Type     | Description                             |
+| ---------------- | -------- | --------------------------------------- |
+| `path`           | string   | **Required.** Path to the HAR file      |
+| `entries`        | number[] | **Required.** Entry indexes to export   |
+| `includeHeaders` | boolean  | Include request headers (default: true) |
+| `includeCookies` | boolean  | Include cookies (default: false)        |
+| `compressed`     | boolean  | Add `--compressed` flag                 |
+| `verbose`        | boolean  | Add `-v` flag                           |
+
+**Example:**
+
+```javascript
+// Export first request as cURL
+export_har_curl(path: "/path/to/file.har", entries: [0])
+
+// Export with cookies and verbose output
+export_har_curl(path: "...", entries: [0, 1], includeCookies: true, verbose: true)
+```
+
+## Browser Compatibility
+
+This MCP server fully supports HAR files exported from:
+
+- **Chrome DevTools** - Including all Chrome-specific extension fields (`_initiator`, `_priority`, `_resourceType`, `_transferSize`, `_workerRespondWithSettled`, etc.)
+- **Firefox DevTools** - Standard HAR 1.2 format
+- **Safari Web Inspector** - Standard HAR format
+- **Other tools** - Any HAR 1.2 compliant export
+
+### Truncated HAR Repair
+
+Large HAR files exported from browsers can sometimes be truncated (incomplete JSON). This server automatically detects and repairs truncated HAR files by:
+
+1. Finding the last complete HTTP entry
+2. Reconstructing valid JSON structure
+3. Displaying a warning with the number of recovered entries
+
+When a truncated file is repaired, you'll see a warning like:
+
+```
+⚠️ **Warning**: HAR file was truncated and has been repaired.
+Recovered 182 entries using chrome-timings repair method.
+Some entries at the end of the file may be missing.
+```
+
+## Development
+
+```bash
+bun start        # Run the server
+bun test         # Run tests
+bun lint         # Check code style
+bun format       # Format code
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts          # Entry point - stdio transport setup
+├── server.ts         # MCP server configuration and tool registration
+└── tools/
+    └── har/
+        ├── index.ts  # Tool exports and registration
+        ├── schema.ts # Zod schemas for input validation
+        └── modes/    # Output mode implementations
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "har-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for analyzing HAR (HTTP Archive) files with LLM-friendly output",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "har-mcp": "./src/index.ts"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": ["src", "package.json", "README.md", "LICENSE"],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch src/index.ts",
+    "test": "bun test",
+    "lint": "bunx @biomejs/biome check .",
+    "lint:fix": "bunx @biomejs/biome check --write .",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format .",
+    "check": "bunx @biomejs/biome check --write . && bunx @biomejs/biome format --write .",
+    "check:ci": "bunx @biomejs/biome check . && bunx @biomejs/biome format .",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "har-to-curl": "^0.5.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "^1.1.15",
+    "typescript": "^5.9.3"
+  },
+  "keywords": ["mcp", "model-context-protocol", "ai", "llm", "har", "http-archive", "network-analysis"],
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * MCP Server Entry Point
+ *
+ * This is the main entry point that sets up the stdio transport
+ * and connects it to the MCP server.
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { createServer } from "./server.ts"
+
+async function main(): Promise<void> {
+  const server = createServer()
+  const transport = new StdioServerTransport()
+
+  await server.connect(transport)
+
+  // Handle graceful shutdown
+  process.on("SIGINT", async () => {
+    await server.close()
+    process.exit(0)
+  })
+
+  process.on("SIGTERM", async () => {
+    await server.close()
+    process.exit(0)
+  })
+}
+
+main().catch(error => {
+  console.error("Fatal error:", error)
+  process.exit(1)
+})

package/src/server.ts

@@ -0,0 +1,28 @@
+/**
+ * MCP Server Configuration
+ *
+ * This file contains the server setup and tool registration.
+ * Add your tools by importing them and registering with the server.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { registerTools } from "./tools/index.ts"
+
+// Server metadata
+export const SERVER_NAME = "har-mcp"
+export const SERVER_VERSION = "0.1.0"
+
+/**
+ * Creates and configures the MCP server with all tools registered.
+ */
+export function createServer(): McpServer {
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+  })
+
+  // Register all tools
+  registerTools(server)
+
+  return server
+}

package/src/tools/export-curl.ts

@@ -0,0 +1,134 @@
+/**
+ * Export HAR entries as cURL commands
+ */
+
+import * as fs from "node:fs/promises"
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import harToCurl from "har-to-curl"
+import { z } from "zod"
+import { type HarEntry, HarFileSchema } from "../types/har.ts"
+
+export const exportCurlSchema = z.object({
+  path: z.string().describe("Path to the HAR file"),
+  entries: z.array(z.number().int().min(0)).describe("Entry indexes to export"),
+  includeHeaders: z.boolean().default(true).describe("Include request headers"),
+  includeCookies: z.boolean().default(false).describe("Include cookies"),
+  compressed: z.boolean().default(false).describe("Add --compressed flag"),
+  verbose: z.boolean().default(false).describe("Add -v flag for verbose output"),
+})
+
+export type ExportCurlInput = z.infer<typeof exportCurlSchema>
+
+// Headers that contain sensitive information and should be redacted
+const SENSITIVE_HEADERS = /^(authorization|x-api-key|x-auth-token|api-key|bearer)/i
+
+/**
+ * Prepares a HAR entry for conversion by applying options like header filtering,
+ * cookie removal, and sensitive header redaction
+ */
+function prepareEntryForConversion(entry: HarEntry, options: ExportCurlInput): HarEntry {
+  // Deep clone the entry to avoid mutating the original
+  const preparedEntry = JSON.parse(JSON.stringify(entry)) as HarEntry
+
+  // Filter headers if not including all headers
+  if (!options.includeHeaders) {
+    preparedEntry.request.headers = []
+  } else {
+    // Redact sensitive headers
+    preparedEntry.request.headers = preparedEntry.request.headers.map(header => {
+      if (SENSITIVE_HEADERS.test(header.name)) {
+        return { ...header, value: "[REDACTED]" }
+      }
+      return header
+    })
+  }
+
+  // Remove cookies if not included
+  if (!options.includeCookies) {
+    preparedEntry.request.cookies = []
+    // Also remove Cookie header if present
+    preparedEntry.request.headers = preparedEntry.request.headers.filter(h => h.name.toLowerCase() !== "cookie")
+  }
+
+  return preparedEntry
+}
+
+/**
+ * Appends additional curl flags based on options
+ */
+function appendFlags(curlCommand: string, options: ExportCurlInput): string {
+  const flags: string[] = []
+
+  if (options.compressed) {
+    flags.push("--compressed")
+  }
+  if (options.verbose) {
+    flags.push("-v")
+  }
+
+  if (flags.length > 0) {
+    return `${curlCommand} ${flags.join(" ")}`
+  }
+
+  return curlCommand
+}
+
+export async function exportCurlHandler(input: ExportCurlInput): Promise<string> {
+  const fileContent = await fs.readFile(input.path, "utf-8")
+  const harData = JSON.parse(fileContent)
+  const parseResult = HarFileSchema.safeParse(harData)
+
+  if (!parseResult.success) {
+    throw new Error("Invalid HAR file format")
+  }
+
+  const harFile = parseResult.data
+  const results: string[] = []
+
+  for (const idx of input.entries) {
+    const entry = harFile.log.entries[idx]
+    if (!entry) {
+      results.push(`# Entry ${idx}: Not found`)
+      continue
+    }
+
+    results.push(`# Entry ${idx}: ${entry.request.method} ${entry.request.url}`)
+
+    // Prepare entry with options applied
+    const preparedEntry = prepareEntryForConversion(entry, input)
+
+    // Use har-to-curl library for conversion
+    const curlCommand = harToCurl(preparedEntry)
+
+    // Append additional flags
+    const finalCommand = appendFlags(curlCommand, input)
+
+    results.push(finalCommand)
+    results.push("")
+  }
+
+  return results.join("\n")
+}
+
+export function registerExportCurlTool(server: McpServer): void {
+  server.tool(
+    "export_har_curl",
+    "Export HAR entries as cURL commands for replay or debugging",
+    {
+      path: z.string().describe("Path to the HAR file"),
+      entries: z.array(z.number().int().min(0)).describe("Entry indexes to export"),
+      includeHeaders: z.boolean().default(true).describe("Include request headers"),
+      includeCookies: z.boolean().default(false).describe("Include cookies"),
+      compressed: z.boolean().default(false).describe("Add --compressed flag"),
+      verbose: z.boolean().default(false).describe("Add -v flag"),
+    },
+    async args => {
+      try {
+        const result = await exportCurlHandler(args as ExportCurlInput)
+        return { content: [{ type: "text" as const, text: result }] }
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Error: ${(err as Error).message}` }], isError: true }
+      }
+    },
+  )
+}

package/src/tools/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Tool Registration
+ *
+ * This file exports a function to register all tools with the MCP server.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { registerExportCurlTool } from "./export-curl.ts"
+import { registerReadHarTool } from "./read-har.ts"
+
+/**
+ * Registers all tools with the MCP server.
+ */
+export function registerTools(server: McpServer): void {
+  registerReadHarTool(server)
+  registerExportCurlTool(server)
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Filter and Sort Functions for Read HAR Tool
+ */
+
+import type { HarEntry } from "../../types/har.ts"
+import { getResponseSize, isError, matchStatus, matchUrl } from "./helpers.ts"
+import type { ReadHarInput } from "./schema.ts"
+
+/**
+ * Entry with its original index
+ */
+export interface IndexedEntry {
+  index: number
+  entry: HarEntry
+}
+
+/**
+ * Filters entries based on filter criteria
+ */
+export function filterEntries(entries: IndexedEntry[], filter: ReadHarInput["filter"]): IndexedEntry[] {
+  if (!filter) return entries
+
+  return entries.filter(({ entry }) => {
+    // URL filter
+    if (filter.url && !matchUrl(entry.request.url, filter.url)) {
+      return false
+    }
+
+    // Method filter
+    if (filter.method) {
+      const methods = Array.isArray(filter.method) ? filter.method : [filter.method]
+      if (!methods.some(m => m.toUpperCase() === entry.request.method.toUpperCase())) {
+        return false
+      }
+    }
+
+    // Status filter
+    if (filter.status !== undefined && !matchStatus(entry.response.status, filter.status)) {
+      return false
+    }
+
+    // Content type filter
+    if (filter.contentType) {
+      const responseType = entry.response.content.mimeType.toLowerCase()
+      if (!responseType.includes(filter.contentType.toLowerCase())) {
+        return false
+      }
+    }
+
+    // Min duration filter
+    if (filter.minDuration !== undefined && entry.time < filter.minDuration) {
+      return false
+    }
+
+    // Has error filter
+    if (filter.hasError !== undefined) {
+      const entryHasError = isError(entry)
+      if (filter.hasError !== entryHasError) {
+        return false
+      }
+    }
+
+    // Body contains filter
+    if (filter.bodyContains) {
+      const responseText = entry.response.content.text || ""
+      if (!responseText.toLowerCase().includes(filter.bodyContains.toLowerCase())) {
+        return false
+      }
+    }
+
+    return true
+  })
+}
+
+/**
+ * Sorts entries based on sort criteria
+ */
+export function sortEntries(entries: IndexedEntry[], sort: ReadHarInput["sort"]): IndexedEntry[] {
+  if (!sort) return entries
+
+  const sorted = [...entries]
+  const multiplier = sort.order === "desc" ? -1 : 1
+
+  sorted.sort((a, b) => {
+    let comparison = 0
+
+    switch (sort.by) {
+      case "index":
+        comparison = a.index - b.index
+        break
+      case "time":
+        comparison = new Date(a.entry.startedDateTime).getTime() - new Date(b.entry.startedDateTime).getTime()
+        break
+      case "duration":
+        comparison = a.entry.time - b.entry.time
+        break
+      case "size":
+        comparison = getResponseSize(a.entry) - getResponseSize(b.entry)
+        break
+      case "status":
+        comparison = a.entry.response.status - b.entry.response.status
+        break
+    }
+
+    return comparison * multiplier
+  })
+
+  return sorted
+}