tracegist-mcp-bridge 0.2.0 → 0.2.3

package/README.md

@@ -48,13 +48,13 @@ Set `TRACEGIST_DIR` to change where the bridge looks for packages (defaults to `
 
 Each session ZIP may include:
 
-| Path | Description |
-|---|---|
-| `*-coding-agent-handoff.md` | Structured handoff for the coding agent |
-| `*-manifest.json` | Session metadata and file index |
-| `*-playwright-repro.spec.ts` | Auto-generated Playwright repro script skeleton |
+| Path                         | Description                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
+| `*-coding-agent-handoff.md`  | Structured handoff for the coding agent                                                |
+| `*-manifest.json`            | Session metadata and file index                                                        |
+| `*-playwright-repro.spec.ts` | Auto-generated Playwright repro script skeleton                                        |
 | `network/api-requests.jsonl` | API request/response bodies (opt-in, requires Deep Diagnostics + body capture enabled) |
-| `markers/marker-NN-*/` | Per-marker screenshots, voice notes, highlight captures |
+| `markers/marker-NN-*/`       | Per-marker screenshots, voice notes, highlight captures                                |
 
 ## Prerequisites for transcription
 

package/bin/lib.mjs

@@ -0,0 +1,152 @@
+import path from "node:path";
+
+const PACKAGE_SUFFIX = "-package.zip";
+const HANDOFF_SUFFIXES = ["-coding-agent-handoff.md", "-cursor-handoff.md"];
+
+export function isTraceGistPackageFile(fileName) {
+  return fileName.startsWith("tracegist-") && fileName.endsWith(PACKAGE_SUFFIX);
+}
+
+export function normalizeZipBaseName(entryName) {
+  return path.posix.basename(entryName).toLowerCase();
+}
+
+export function renderPackagesText(packages, directory) {
+  if (packages.length === 0) {
+    return [
+      `No TraceGist package zips found in ${directory}.`,
+      "Expected naming pattern: tracegist-...-package.zip",
+    ].join("\n");
+  }
+  const lines = [`Found ${packages.length} TraceGist package(s) in ${directory}:`, ""];
+  for (const pkg of packages) {
+    lines.push(
+      `- ${pkg.name}`,
+      `  path: ${pkg.path}`,
+      `  size: ${pkg.sizeBytes} bytes`,
+      `  modified: ${pkg.modifiedAt}`,
+      "",
+    );
+  }
+  return lines.join("\n");
+}
+
+export function parseMarkdownSections(markdown) {
+  const sections = [];
+  const lines = markdown.split("\n");
+  let currentName = null;
+  let currentStart = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      if (currentName !== null) {
+        sections.push({
+          name: currentName,
+          content: lines.slice(currentStart, i).join("\n"),
+        });
+      }
+      currentName = lines[i].slice(3).trim();
+      currentStart = i;
+    }
+  }
+
+  if (currentName !== null) {
+    sections.push({
+      name: currentName,
+      content: lines.slice(currentStart).join("\n"),
+    });
+  }
+
+  return sections;
+}
+
+/**
+ * Brief purpose hints for known handoff sections.
+ * Keys are matched case-insensitively against section names.
+ * Unknown sections get a generic hint so the TOC is never incomplete.
+ */
+const SECTION_HINTS = {
+  "session triage": "Tester summary: expected vs actual, severity",
+  "agent guidance": "Suggested investigation focus areas",
+  "session context note": "Starting state before the bug (not a bug itself)",
+  "notable anomalies": "Pre-flagged JS errors, failed requests, warnings",
+  "marker timeline": "Timestamped markers with ±5 s event windows — start here for analysis",
+  "user interaction timeline": "Full click/fill/navigation sequence — key for reproduction",
+  "session context": "Page URL, title, session metadata",
+  "session environment": "Browser, viewport, OS — match for reproduction",
+  "package files": "Paths to Playwright script, manifest, network bodies",
+  "marker-to-file mapping": "Which screenshots/voice files belong to each marker",
+  "backend log correlation": "Absolute timestamps for server-side log alignment",
+  "full session console timeline": "All console output (deep exports only)",
+  "full session network timeline": "All network requests (deep exports only)",
+  "full session network timeline (third-party only)": "Third-party network calls (deep exports only)",
+  "full session timelines": "Placeholder when deep timelines are omitted",
+  "context": "AI-generated analysis context (when available)",
+  "tracegist agent-processed context": "LLM-processed summary of the session",
+  "tester intent": "What the tester was trying to accomplish",
+  "handover tasks for coding agent": "Specific tasks the tester wants the agent to do",
+  "marker visual evidence": "Screenshot references for each marker",
+  "environment at marker time": "Environment snapshot at a specific marker",
+  "marker timeline logs (context window)": "Logs within the ±5 s marker window",
+};
+
+function getSectionHint(sectionName) {
+  return SECTION_HINTS[sectionName.toLowerCase()] || "Additional section";
+}
+
+export function renderSectionToc(sections, zipPath) {
+  const totalChars = sections.reduce((sum, s) => sum + s.content.length, 0);
+  const lines = [
+    `Handoff document for ${path.basename(zipPath)} — ${sections.length} sections, ${totalChars.toLocaleString()} chars total.`,
+    "",
+    "| # | Section | Size | Purpose |",
+    "|---|---------|------|---------|",
+  ];
+  for (let i = 0; i < sections.length; i++) {
+    const hint = getSectionHint(sections[i].name);
+    lines.push(
+      `| ${i + 1} | ${sections[i].name} | ${sections[i].content.length.toLocaleString()} chars | ${hint} |`,
+    );
+  }
+  lines.push(
+    "",
+    "**Reading guide:** For analysis, start with Session Triage → Marker Timeline → Notable Anomalies.",
+    "For reproduction, start with Session Environment → User Interaction Timeline → Package Files (Playwright script path).",
+    "",
+    'Pass `section` with a section name (e.g. "Marker Timeline") to retrieve its full content.',
+  );
+  return lines.join("\n");
+}
+
+export function looksLikeVoiceNote(entryName) {
+  const base = path.posix.basename(entryName).toLowerCase();
+  return /voice/.test(base) && /\.(webm|wav|mp3|m4a|ogg|flac)$/i.test(base);
+}
+
+export async function mapConcurrent(items, fn, concurrency) {
+  const results = new Array(items.length);
+  let i = 0;
+  const worker = async () => {
+    while (i < items.length) {
+      const idx = i++;
+      results[idx] = await fn(items[idx], idx);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+  return results;
+}
+
+export function toolError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true,
+  };
+}
+
+export function formatExecError(err) {
+  if (err instanceof Error && err.message) return err.message;
+  return String(err);
+}
+
+export { HANDOFF_SUFFIXES };

package/bin/tracegist-mcp-bridge.mjs

@@ -9,6 +9,18 @@ import JSZip from "jszip";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  isTraceGistPackageFile,
+  normalizeZipBaseName,
+  renderPackagesText,
+  parseMarkdownSections,
+  renderSectionToc,
+  looksLikeVoiceNote,
+  mapConcurrent,
+  toolError,
+  formatExecError,
+  HANDOFF_SUFFIXES,
+} from "./lib.mjs";
 
 const BRIDGE_NAME = "tracegist-mcp-bridge";
 const { version: BRIDGE_VERSION } = JSON.parse(
@@ -18,18 +30,13 @@ const { version: BRIDGE_VERSION } = JSON.parse(
 function resolveDefaultDirectory() {
   const envDir = process.env.TRACEGIST_DIR;
   if (envDir) {
-    const resolved = envDir.startsWith("~")
-      ? path.join(os.homedir(), envDir.slice(1))
-      : envDir;
+    const resolved = envDir.startsWith("~") ? path.join(os.homedir(), envDir.slice(1)) : envDir;
     return path.resolve(resolved);
   }
   return path.join(os.homedir(), "Downloads");
 }
 
 const DEFAULT_DOWNLOADS_DIR = resolveDefaultDirectory();
-const PACKAGE_SUFFIX = "-package.zip";
-const HANDOFF_SUFFIXES = ["-coding-agent-handoff.md", "-cursor-handoff.md"];
-const MAX_PREVIEW_CHARS = 12_000;
 const ZIP_CACHE_MAX = 5;
 const execFileAsync = promisify(execFile);
 let whisperDependencyWarnings = [];
@@ -37,6 +44,9 @@ let whisperDependencyWarnings = [];
 /** @type {Map<string, { zip: JSZip, entryNames: string[], mtimeMs: number }>} */
 const zipCache = new Map();
 
+/** @type {Map<string, { enrichedMarkdown: string, mtimeMs: number }>} */
+const transcriptCache = new Map();
+
 async function checkWhisperDependencies() {
   const warnings = [];
 
@@ -72,15 +82,6 @@ async function checkWhisperDependencies() {
   return warnings;
 }
 
-function formatExecError(err) {
-  if (err instanceof Error && err.message) return err.message;
-  return String(err);
-}
-
-function isTraceGistPackageFile(fileName) {
-  return fileName.startsWith("tracegist-") && fileName.endsWith(PACKAGE_SUFFIX);
-}
-
 async function listTraceGistPackages(directory, limit) {
   const entries = await fs.readdir(directory, { withFileTypes: true });
   const zipNames = entries
@@ -128,7 +129,9 @@ async function readZipEntries(zipPath) {
 }
 
 async function tryReadManifest(zip) {
-  const manifestEntry = Object.values(zip.files).find((entry) => entry.name.endsWith("-manifest.json"));
+  const manifestEntry = Object.values(zip.files).find((entry) =>
+    entry.name.endsWith("-manifest.json"),
+  );
   if (!manifestEntry) return { manifest: null, manifestEntryName: null };
   const manifestText = await manifestEntry.async("text");
   try {
@@ -144,14 +147,11 @@ async function tryReadManifest(zip) {
   }
 }
 
-function normalizeZipBaseName(entryName) {
-  return path.posix.basename(entryName).toLowerCase();
-}
-
 async function tryReadHandoffMarkdown(zip, entryNames, manifest = null) {
-  const manifestNamedHandoff = typeof manifest?.handoffMarkdownFilename === "string"
-    ? normalizeZipBaseName(manifest.handoffMarkdownFilename)
-    : null;
+  const manifestNamedHandoff =
+    typeof manifest?.handoffMarkdownFilename === "string"
+      ? normalizeZipBaseName(manifest.handoffMarkdownFilename)
+      : null;
   const byBaseName = new Map();
   for (const name of entryNames) {
     byBaseName.set(normalizeZipBaseName(name), name);
@@ -162,11 +162,12 @@ async function tryReadHandoffMarkdown(zip, entryNames, manifest = null) {
     selectedEntryName = byBaseName.get(manifestNamedHandoff) || null;
   }
   if (!selectedEntryName) {
-    selectedEntryName = entryNames.find((name) => {
-      const baseName = normalizeZipBaseName(name);
-      if (HANDOFF_SUFFIXES.some((suffix) => baseName.endsWith(suffix))) return true;
-      return /handoff.*\.md$/i.test(baseName);
-    }) || null;
+    selectedEntryName =
+      entryNames.find((name) => {
+        const baseName = normalizeZipBaseName(name);
+        if (HANDOFF_SUFFIXES.some((suffix) => baseName.endsWith(suffix))) return true;
+        return /handoff.*\.md$/i.test(baseName);
+      }) || null;
   }
   if (!selectedEntryName) {
     return { handoffMarkdown: null, handoffEntryName: null, debugCandidates: [] };
@@ -179,100 +180,8 @@ async function tryReadHandoffMarkdown(zip, entryNames, manifest = null) {
   return { handoffMarkdown, handoffEntryName: selectedEntryName, debugCandidates: [] };
 }
 
-function renderPackagesText(packages, directory) {
-  if (packages.length === 0) {
-    return [
-      `No TraceGist package zips found in ${directory}.`,
-      "Expected naming pattern: tracegist-...-package.zip",
-    ].join("\n");
-  }
-  const lines = [`Found ${packages.length} TraceGist package(s) in ${directory}:`, ""];
-  for (const pkg of packages) {
-    lines.push(
-      `- ${pkg.name}`,
-      `  path: ${pkg.path}`,
-      `  size: ${pkg.sizeBytes} bytes`,
-      `  modified: ${pkg.modifiedAt}`,
-      "",
-    );
-  }
-  return lines.join("\n");
-}
-
-function truncateText(value, maxChars = MAX_PREVIEW_CHARS) {
-  if (value.length <= maxChars) return value;
-  return `${value.slice(0, maxChars)}\n\n... [truncated ${value.length - maxChars} chars]`;
-}
-
-function parseMarkdownSections(markdown) {
-  const sections = [];
-  const lines = markdown.split("\n");
-  let currentName = null;
-  let currentStart = 0;
-
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].startsWith("## ")) {
-      if (currentName !== null) {
-        sections.push({
-          name: currentName,
-          content: lines.slice(currentStart, i).join("\n"),
-        });
-      }
-      currentName = lines[i].slice(3).trim();
-      currentStart = i;
-    }
-  }
-
-  if (currentName !== null) {
-    sections.push({
-      name: currentName,
-      content: lines.slice(currentStart).join("\n"),
-    });
-  }
-
-  return sections;
-}
-
-function renderSectionToc(sections, zipPath) {
-  const totalChars = sections.reduce((sum, s) => sum + s.content.length, 0);
-  const lines = [
-    `Handoff document for ${path.basename(zipPath)} — ${sections.length} sections, ${totalChars.toLocaleString()} chars total.`,
-    "",
-    "| # | Section | Size |",
-    "|---|---------|------|",
-  ];
-  for (let i = 0; i < sections.length; i++) {
-    lines.push(
-      `| ${i + 1} | ${sections[i].name} | ${sections[i].content.length.toLocaleString()} chars |`,
-    );
-  }
-  lines.push(
-    "",
-    'Pass `section` with a section name (e.g. "Marker Timeline") to retrieve its full content.',
-  );
-  return lines.join("\n");
-}
-
-function looksLikeVoiceNote(entryName) {
-  const base = path.posix.basename(entryName).toLowerCase();
-  return /voice/.test(base) && /\.(webm|wav|mp3|m4a|ogg|flac)$/i.test(base);
-}
-
 const WHISPER_CONCURRENCY = 2;
 
-async function mapConcurrent(items, fn, concurrency) {
-  const results = new Array(items.length);
-  let i = 0;
-  const worker = async () => {
-    while (i < items.length) {
-      const idx = i++;
-      results[idx] = await fn(items[idx], idx);
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
-  return results;
-}
-
 async function transcribeWithLocalWhisper(audioPath, model, language) {
   const args = [
     "-m",
@@ -335,7 +244,9 @@ async function injectTranscriptsIntoMarkdown(markdown, zip, entryNames) {
             transcriptByShortId.set(shortId, "[VOICE NOTE NOT FOUND IN ZIP]");
             return;
           }
-          const outputPath = path.join(tmpRoot, path.basename(entryName));
+          const markerDir = path.join(tmpRoot, shortId);
+          await fs.mkdir(markerDir, { recursive: true });
+          const outputPath = path.join(markerDir, path.basename(entryName));
           const data = await entry.async("nodebuffer");
           await fs.writeFile(outputPath, data);
           try {
@@ -356,10 +267,7 @@ async function injectTranscriptsIntoMarkdown(markdown, zip, entryNames) {
   } else {
     const hint = whisperDependencyWarnings.join(" | ");
     for (const shortId of voiceByShortId.keys()) {
-      transcriptByShortId.set(
-        shortId,
-        `[TRANSCRIPTION REQUIRED — Whisper not available: ${hint}]`,
-      );
+      transcriptByShortId.set(shortId, `[TRANSCRIPTION REQUIRED — Whisper not available: ${hint}]`);
     }
   }
 
@@ -412,27 +320,58 @@ server.registerPrompt(
             "Each package contains screenshots, voice notes, network logs, interaction events, and a",
             "pre-generated handoff markdown file.",
             "",
-            "## Recommended workflow",
+            "## Step 1 — Discover & orient",
             "",
             "1. `list_tracegist_packages` — find available packages (searches TRACEGIST_DIR env var, or ~/Downloads by default).",
-            "2. `get_tracegist_handoff_markdown` — call without a `section` parameter to get a table of contents",
-            "   showing all sections and their sizes. Then request specific sections by name (e.g. `section: \"Marker Timeline\"`).",
+            "2. `get_tracegist_handoff_markdown` — call **without** a `section` parameter to get a table of contents (TOC)",
+            "   showing all sections, their sizes, and a brief purpose hint for each section.",
+            '   Then request specific sections by name (e.g. `section: "Marker Timeline"`).',
             '   Use `section: "all"` to load the full document at once (can be large for deep exports).',
             "   **Voice note transcripts are injected automatically** into the marker sections — no separate step needed.",
             "   If Whisper is unavailable, a placeholder is injected with setup instructions.",
-            "3. `read_tracegist_package_file` — read text files directly from the ZIP without writing to disk.",
-            "   - **Playwright repro script**: the manifest's `playwrightScriptPath` field gives the entry name.",
-            "     Call `read_tracegist_package_file({ zipPath, entryName: manifest.playwrightScriptPath })`.",
-            "   - **Network bodies**: `network/api-requests.jsonl` has POST/PUT/PATCH bodies + response statuses.",
-            "   - Also useful for the raw manifest JSON or any other text entry.",
-            "4. `extract_tracegist_package_file` — extract a file to disk.",
-            "   Use for: screenshots (PNG) and other binary files, or when a downstream tool needs a real file path.",
+            "",
+            "## Step 2 — Decide: analyze-only vs. reproduce-first",
+            "",
+            "After reading the TOC, choose one of two paths:",
+            "",
+            "### Path A: Analyze and fix (no reproduction needed)",
+            "",
+            "Best when the bug is clear from logs/screenshots and you can identify the root cause from the trace alone.",
+            "",
+            '1. Read **Session Triage** — the tester\'s summary: what was expected, what happened, severity.',
+            '2. Read **Marker Timeline** — timestamped markers with ±5 s event windows (errors, network, interactions).',
+            '3. Read **Notable Anomalies** — pre-flagged JS errors, failed requests, and console warnings.',
+            '4. If needed: **Full Session Console/Network Timelines** (deep exports only), **Session Environment**.',
+            "5. Diagnose and fix directly in the codebase.",
+            "",
+            "### Path B: Reproduce first, then develop against the reproduction",
+            "",
+            "Best when you need to see the failure live, the bug is intermittent, or you want a test harness to develop against.",
+            "",
+            "1. `get_tracegist_package_overview` — get the manifest. Note `playwrightScriptPath`.",
+            "2. `read_tracegist_package_file({ zipPath, entryName: manifest.playwrightScriptPath })` — read the",
+            "   auto-generated Playwright repro script (click/fill steps derived from the interaction log).",
+            '3. Read **Session Environment** — browser, viewport, URL, OS. Match your local setup.',
+            '4. Read **User Interaction Timeline** — the full sequence of user actions to understand the reproduction flow.',
+            "5. Extract and run the Playwright script:",
+            "   - `extract_tracegist_package_file` to get the script + config to disk.",
+            "   - The script needs authentication handled separately (storageState or global setup).",
+            "   - `npx playwright test <script>.spec.ts` — adapt the script as needed, then develop your fix against it.",
+            "6. Once the bug reproduces, switch to Path A sections for root-cause analysis.",
+            "",
+            "## Additional tools",
+            "",
+            "- `read_tracegist_package_file` — read any text file directly from the ZIP without writing to disk.",
+            "  - **Network bodies**: `network/api-requests.jsonl` has POST/PUT/PATCH bodies + response statuses.",
+            "  - Also useful for the raw manifest JSON or any other text entry.",
+            "- `extract_tracegist_package_file` — extract a file to disk.",
+            "  Use for: screenshots (PNG) and other binary files, or when a downstream tool needs a real file path.",
             "",
             "## Key facts",
             "",
-            "- **Overview vs. full handoff**: `get_tracegist_package_overview` returns a TRUNCATED handoff preview",
-            "  (first 12,000 chars — may cut off mid-section). Do NOT treat it as the complete handoff.",
-            "  Always follow up with `get_tracegist_handoff_markdown` (no section → TOC, then load sections by name).",
+            "- **Overview vs. full handoff**: `get_tracegist_package_overview` returns only metadata (manifest + file list).",
+            "  It does NOT include handoff content. Always use `get_tracegist_handoff_markdown`",
+            "  (no section → TOC, then load sections by name) for the actual handoff document.",
             "- Voice notes answer the triage prompts shown to the tester during recording.",
             "  The first marker within 30 s of session start is a session context note (starting state, not a bug).",
             "- Marker timestamps are relative to session start. Each marker has a ±5 s event window",
@@ -455,32 +394,41 @@ server.registerTool(
   {
     description:
       "Transcribe voice-note files inside a TraceGist package zip using local Python Whisper (no external API).",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
-      model: z.string().optional(),
-      language: z.string().optional(),
+      zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
+      model: z.string().optional().describe('Whisper model size (default: "base"). Options: tiny, base, small, medium, large.'),
+      language: z.string().optional().describe("ISO 639-1 language code (e.g. en, de, ja). Omit for auto-detection."),
     }),
   },
   async ({ zipPath, model = "base", language }) => {
+    try {
     if (whisperDependencyWarnings.length > 0) {
       return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(
-            {
-              zipPath,
-              model,
-              language: language || null,
-              transcriptions: [],
-              failures: [],
-              warning:
-                "Local Whisper dependencies are missing. Fix the dependency warnings and retry transcription.",
-              dependencyWarnings: whisperDependencyWarnings,
-            },
-            null,
-            2,
-          ),
-        }],
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                zipPath,
+                model,
+                language: language || null,
+                transcriptions: [],
+                failures: [],
+                warning:
+                  "Local Whisper dependencies are missing. Fix the dependency warnings and retry transcription.",
+                dependencyWarnings: whisperDependencyWarnings,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
         isError: true,
       };
     }
@@ -489,20 +437,22 @@ server.registerTool(
     const voiceEntries = entryNames.filter((entryName) => looksLikeVoiceNote(entryName));
     if (voiceEntries.length === 0) {
       return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(
-            {
-              zipPath,
-              model,
-              language: language || null,
-              transcriptions: [],
-              warning: "No voice-note files found in package.",
-            },
-            null,
-            2,
-          ),
-        }],
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                zipPath,
+                model,
+                language: language || null,
+                transcriptions: [],
+                warning: "No voice-note files found in package.",
+              },
+              null,
+              2,
+            ),
+          },
+        ],
       };
     }
 
@@ -518,7 +468,9 @@ server.registerTool(
           failures.push({ entryName, error: "Entry missing from zip" });
           continue;
         }
-        const outputPath = path.join(tmpRoot, path.basename(entryName));
+        const entryDir = path.join(tmpRoot, String(extracted.length));
+        await fs.mkdir(entryDir, { recursive: true });
+        const outputPath = path.join(entryDir, path.basename(entryName));
         const data = await entry.async("nodebuffer");
         await fs.writeFile(outputPath, data);
         extracted.push({ entryName, outputPath });
@@ -558,24 +510,34 @@ server.registerTool(
       content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
       ...(transcriptions.length === 0 && failures.length > 0 ? { isError: true } : {}),
     };
+    } catch (err) { return toolError(err); }
   },
 );
 
 server.registerTool(
   "list_tracegist_packages",
   {
-    description: "List TraceGist marker package zip files. Searches TRACEGIST_DIR (env var), falls back to ~/Downloads, or uses the given directory.",
+    description:
+      "List TraceGist marker package zip files. Searches TRACEGIST_DIR (env var), falls back to ~/Downloads, or uses the given directory.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      directory: z.string().optional(),
-      limit: z.number().int().min(1).max(200).optional(),
+      directory: z.string().optional().describe("Directory to search for packages. Defaults to TRACEGIST_DIR or ~/Downloads."),
+      limit: z.number().int().min(1).max(200).optional().describe("Maximum number of packages to return (default: 20)."),
     }),
   },
   async ({ directory, limit = 20 }) => {
+    try {
     const searchDir = directory || DEFAULT_DOWNLOADS_DIR;
     const packages = await listTraceGistPackages(searchDir, limit);
     return {
       content: [{ type: "text", text: renderPackagesText(packages, searchDir) }],
     };
+    } catch (err) { return toolError(err); }
   },
 );
 
@@ -583,17 +545,28 @@ server.registerTool(
   "get_tracegist_package_overview",
   {
     description:
-      "Quick overview of a TraceGist package: manifest, file list, and a TRUNCATED handoff preview (first 12,000 chars only — may cut off mid-section). " +
-      "For the full handoff, call get_tracegist_handoff_markdown (no section param → table of contents, then load sections by name). " +
+      "Quick metadata overview of a TraceGist package: manifest and file list. " +
+      "Does NOT include handoff content — call get_tracegist_handoff_markdown (no section param → table of contents, then load sections by name) for the actual handoff. " +
       "The manifest includes playwrightScriptPath — use read_tracegist_package_file with that path to get the Playwright repro script.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
+      zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
     }),
   },
   async ({ zipPath }) => {
+    try {
     const { zip, entryNames } = await readZipEntries(zipPath);
     const { manifest, manifestEntryName } = await tryReadManifest(zip);
-    const { handoffMarkdown, handoffEntryName } = await tryReadHandoffMarkdown(zip, entryNames, manifest);
+    const { handoffEntryName } = await tryReadHandoffMarkdown(
+      zip,
+      entryNames,
+      manifest,
+    );
 
     const overview = {
       zipPath,
@@ -601,13 +574,14 @@ server.registerTool(
       manifestEntryName,
       handoffEntryName,
       manifest,
-      handoffPreview: handoffMarkdown ? truncateText(handoffMarkdown, MAX_PREVIEW_CHARS) : null,
       entries: entryNames,
+      hint: "Use get_tracegist_handoff_markdown (no section param) for a table of contents, then load sections by name.",
     };
 
     return {
       content: [{ type: "text", text: JSON.stringify(overview, null, 2) }],
     };
+    } catch (err) { return toolError(err); }
   },
 );
 
@@ -621,12 +595,19 @@ server.registerTool(
       "Without a `section` parameter, returns a table of contents with section names and sizes. " +
       "With a `section` parameter, returns just that section's content. " +
       'Use section name "all" to retrieve the full document.',
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
-      section: z.string().optional(),
+      zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
+      section: z.string().optional().describe('Section name from the TOC (e.g. "Marker Timeline"), or "all" for the full document. Omit to get table of contents.'),
     }),
   },
   async ({ zipPath, section }) => {
+    try {
     const { zip, entryNames } = await readZipEntries(zipPath);
     const { manifest } = await tryReadManifest(zip);
     const { handoffMarkdown, handoffEntryName, debugCandidates } = await tryReadHandoffMarkdown(
@@ -639,30 +620,44 @@ server.registerTool(
         .filter((name) => /handoff|coding-agent/i.test(path.posix.basename(name)))
         .slice(0, 5);
       return {
-        content: [{
-          type: "text",
-          text: [
-            `No handoff markdown entry found in ${zipPath}.`,
-            manifest?.handoffMarkdownFilename
-              ? `Manifest handoff filename: ${manifest.handoffMarkdownFilename}`
-              : "Manifest handoff filename: (missing)",
-            `Matching entry candidates: ${hintedEntries.length > 0 ? hintedEntries.join(", ") : "(none)"}`,
-            `Debug candidates: ${debugCandidates.length > 0 ? debugCandidates.join(", ") : "(none)"}`,
-          ].join("\n"),
-        }],
+        content: [
+          {
+            type: "text",
+            text: [
+              `No handoff markdown entry found in ${zipPath}.`,
+              manifest?.handoffMarkdownFilename
+                ? `Manifest handoff filename: ${manifest.handoffMarkdownFilename}`
+                : "Manifest handoff filename: (missing)",
+              `Matching entry candidates: ${hintedEntries.length > 0 ? hintedEntries.join(", ") : "(none)"}`,
+              `Debug candidates: ${debugCandidates.length > 0 ? debugCandidates.join(", ") : "(none)"}`,
+            ].join("\n"),
+          },
+        ],
         isError: true,
       };
     }
 
-    const enrichedMarkdown = await injectTranscriptsIntoMarkdown(handoffMarkdown, zip, entryNames);
+    // Cache transcription results to avoid re-running Whisper on repeated calls
+    const cachedZip = zipCache.get(zipPath);
+    const currentMtime = cachedZip?.mtimeMs ?? 0;
+    const cached = transcriptCache.get(zipPath);
+    let enrichedMarkdown;
+    if (cached && cached.mtimeMs === currentMtime) {
+      enrichedMarkdown = cached.enrichedMarkdown;
+    } else {
+      enrichedMarkdown = await injectTranscriptsIntoMarkdown(handoffMarkdown, zip, entryNames);
+      transcriptCache.set(zipPath, { enrichedMarkdown, mtimeMs: currentMtime });
+    }
 
     // Full document retrieval
     if (section && section.toLowerCase() === "all") {
       return {
-        content: [{
-          type: "text",
-          text: `# Source: ${handoffEntryName}\n\n${enrichedMarkdown}`,
-        }],
+        content: [
+          {
+            type: "text",
+            text: `# Source: ${handoffEntryName}\n\n${enrichedMarkdown}`,
+          },
+        ],
       };
     }
 
@@ -671,10 +666,12 @@ server.registerTool(
     // No section requested — return table of contents
     if (!section) {
       return {
-        content: [{
-          type: "text",
-          text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath)}`,
-        }],
+        content: [
+          {
+            type: "text",
+            text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath)}`,
+          },
+        ],
       };
     }
 
@@ -684,19 +681,24 @@ server.registerTool(
     if (!match) {
       const available = sections.map((s) => s.name).join(", ");
       return {
-        content: [{
-          type: "text",
-          text: `Section "${section}" not found. Available sections: ${available}`,
-        }],
+        content: [
+          {
+            type: "text",
+            text: `Section "${section}" not found. Available sections: ${available}`,
+          },
+        ],
         isError: true,
       };
     }
     return {
-      content: [{
-        type: "text",
-        text: match.content,
-      }],
+      content: [
+        {
+          type: "text",
+          text: match.content,
+        },
+      ],
     };
+    } catch (err) { return toolError(err); }
   },
 );
 
@@ -707,12 +709,19 @@ server.registerTool(
       "Read a text file directly from inside a TraceGist package zip and return its content without writing to disk. " +
       "Common uses: `network/api-requests.jsonl` for request/response bodies, or the Playwright repro script " +
       "(its path is in the manifest's `playwrightScriptPath` field, returned by get_tracegist_package_overview).",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
-      entryName: z.string(),
+      zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
+      entryName: z.string().describe("Path of the file inside the zip (e.g. network/api-requests.jsonl)."),
     }),
   },
   async ({ zipPath, entryName }) => {
+    try {
     const { zip } = await readZipEntries(zipPath);
     const entry = zip.file(entryName);
     if (!entry) {
@@ -725,6 +734,7 @@ server.registerTool(
     return {
       content: [{ type: "text", text }],
     };
+    } catch (err) { return toolError(err); }
   },
 );
 
@@ -732,13 +742,20 @@ server.registerTool(
   "extract_tracegist_package_file",
   {
     description: "Extract one file from a TraceGist package zip to a local directory.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
-      entryName: z.string(),
-      outputDirectory: z.string().optional(),
+      zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
+      entryName: z.string().describe("Path of the file inside the zip to extract."),
+      outputDirectory: z.string().optional().describe("Directory to write the file to. Defaults to the zip file's directory."),
     }),
   },
   async ({ zipPath, entryName, outputDirectory }) => {
+    try {
     const { zip } = await readZipEntries(zipPath);
     const entry = zip.file(entryName);
     if (!entry) {
@@ -751,7 +768,9 @@ server.registerTool(
     const outputPath = path.resolve(outDir, path.basename(entryName));
     if (!outputPath.startsWith(outDir + path.sep) && outputPath !== outDir) {
       return {
-        content: [{ type: "text", text: `Refusing to write outside output directory: ${outputPath}` }],
+        content: [
+          { type: "text", text: `Refusing to write outside output directory: ${outputPath}` },
+        ],
         isError: true,
       };
     }
@@ -761,11 +780,14 @@ server.registerTool(
     return {
       content: [{ type: "text", text: `Extracted ${entryName} -> ${outputPath}` }],
     };
+    } catch (err) { return toolError(err); }
   },
 );
 
 whisperDependencyWarnings = await checkWhisperDependencies();
-console.error(`[${BRIDGE_NAME}] Default package directory: ${DEFAULT_DOWNLOADS_DIR}${process.env.TRACEGIST_DIR ? " (from TRACEGIST_DIR)" : ""}`);
+console.error(
+  `[${BRIDGE_NAME}] Default package directory: ${DEFAULT_DOWNLOADS_DIR}${process.env.TRACEGIST_DIR ? " (from TRACEGIST_DIR)" : ""}`,
+);
 if (whisperDependencyWarnings.length > 0) {
   for (const warning of whisperDependencyWarnings) {
     console.error(`[${BRIDGE_NAME}] WARNING: ${warning}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracegist-mcp-bridge",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Local-first MCP bridge for reading and transcribing TraceGist package zips.",
   "type": "module",
   "bin": {