tracegist-mcp-bridge 0.2.11 → 0.2.14

package/README.md

@@ -37,16 +37,19 @@ Set `TRACEGIST_DIR` to change where the bridge looks for packages (defaults to `
 
 ## MCP tools
 
-- `list_tracegist_packages` — list TraceGist package zips in `TRACEGIST_DIR` (or `~/Downloads`)
-- `get_tracegist_package_overview` — manifest + truncated handoff preview + file list (preview capped at 12K chars)
-- `get_tracegist_handoff_markdown` — full handoff markdown (use this for complete content)
-- `read_tracegist_package_file` — read any text file from inside the ZIP without writing to disk (e.g. `network/api-requests.jsonl`, the Playwright repro script)
-- `extract_tracegist_package_file` — write a binary or text file from the ZIP to a local directory
-- `transcribe_tracegist_package_voice_notes` — transcribe voice notes using local Python Whisper
-- `watch_live_session` — poll real-time session events while recording is active
-- `get_live_screenshot` — request and retrieve a screenshot of the current tab
-- `ask_tester_question` — send a question to the tester (shown as a browser toast, max 200 chars)
-- `get_tester_response` — retrieve the tester's voice + screenshot answer
+| Tool                                       | Description                                                     |
+| ------------------------------------------ | --------------------------------------------------------------- |
+| `list_tracegist_packages`                  | List package ZIPs in Downloads                                  |
+| `get_tracegist_package_overview`           | Manifest + truncated handoff preview                            |
+| `get_tracegist_handoff_markdown`           | Full handoff markdown                                           |
+| `read_tracegist_package_file`              | Read any file from the ZIP (e.g. `network/api-requests.jsonl`)  |
+| `extract_tracegist_package_file`           | Extract a file to disk                                          |
+| `transcribe_tracegist_package_voice_notes` | Local Whisper transcription                                     |
+| `watch_live_session`                       | Poll real-time session events while recording is active         |
+| `get_live_screenshot`                      | Request and retrieve a screenshot of the current tab            |
+| `ask_tester_question`                      | Send a question to the tester (shown as a browser toast)        |
+| `get_tester_response`                      | Retrieve the tester's voice + screenshot answer                 |
+| `get_live_session_summary`                 | Complete interaction log and voice transcriptions after session |
 
 ## Package contents
 

package/bin/lib.mjs

@@ -11,14 +11,24 @@ export function normalizeZipBaseName(entryName) {
   return path.posix.basename(entryName).toLowerCase();
 }
 
-export function renderPackagesText(packages, directory) {
+export function renderPackagesText(
+  packages,
+  directory,
+  totalCount = null,
+  hasMore = false,
+  offset = 0,
+) {
   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}:`, ""];
+  const countLabel =
+    totalCount != null
+      ? `Showing ${packages.length} of ${totalCount} TraceGist package(s) in ${directory}:`
+      : `Found ${packages.length} TraceGist package(s) in ${directory}:`;
+  const lines = [countLabel, ""];
   for (const pkg of packages) {
     lines.push(
       `- ${pkg.name}`,
@@ -28,6 +38,16 @@ export function renderPackagesText(packages, directory) {
       "",
     );
   }
+  if (hasMore) {
+    lines.push(
+      `More packages available. Use offset: ${offset + packages.length} to see the next page.`,
+      "",
+    );
+  }
+  lines.push(
+    "Each package includes a ready-to-run Playwright repro script.",
+    "Call get_tracegist_handoff_markdown (no section param) on a package to see the TOC with repro script paths.",
+  );
   return lines.join("\n");
 }
 
@@ -74,7 +94,8 @@ const SECTION_HINTS = {
   "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",
+  "package files":
+    "ACTION: Read the Python repro script path here — use read_tracegist_package_file before writing any automation",
   "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)",
@@ -90,7 +111,7 @@ const SECTION_HINTS = {
   "environment at marker time": "Environment snapshot at a specific marker",
   "marker timeline logs (context window)": "Logs within the ±5 s marker window",
   "webapp testing reproduction":
-    "Server setup, Python repro script, verification points, key selectors",
+    "ACTION: Ready-to-run Python repro script path + key selectors — read before writing any automation",
   "tester intent summary": "Classified intent: specifications, issues found, observations",
   "iterative context": "Previous session reference, verification checklist for build-test cycle",
   "tier 0: quick summary": "Session overview, intent, reproduction command (~200 tokens)",
@@ -103,14 +124,40 @@ function getSectionHint(sectionName) {
   return SECTION_HINTS[sectionName.toLowerCase()] || "Additional section";
 }
 
-export function renderSectionToc(sections, zipPath) {
+export function renderSectionToc(sections, zipPath, manifest = null) {
   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.`,
     "",
+  ];
+
+  // Prominent callout BEFORE the table — shown before any section is read
+  const pythonScript = manifest?.pythonPlaywrightScriptPath;
+  const tsScript = manifest?.playwrightScriptPath;
+  if (pythonScript || tsScript) {
+    lines.push(
+      "**Playwright repro script is ready — read it before writing any automation code:**",
+    );
+    if (pythonScript) {
+      lines.push(
+        `- Python (webapp-testing skill): \`read_tracegist_package_file(zipPath, "${pythonScript}")\``,
+      );
+    }
+    if (tsScript) {
+      lines.push(
+        `- TypeScript (Playwright Test): \`read_tracegist_package_file(zipPath, "${tsScript}")\``,
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "**Reading guide:** For analysis, start with Session Triage → Marker Timeline → Notable Anomalies.",
+    "For reproduction, start with the Playwright repro script above → Session Environment → User Interaction Timeline.",
+    "",
     "| # | Section | Size | Purpose |",
     "|---|---------|------|---------|",
-  ];
+  );
   for (let i = 0; i < sections.length; i++) {
     const hint = getSectionHint(sections[i].name);
     lines.push(
@@ -118,9 +165,6 @@ export function renderSectionToc(sections, zipPath) {
     );
   }
   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.',
   );

package/bin/tracegist-mcp-bridge.mjs

@@ -85,7 +85,7 @@ async function checkWhisperDependencies() {
   return warnings;
 }
 
-async function listTraceGistPackages(directory, limit) {
+async function listTraceGistPackages(directory, limit, offset = 0) {
   const entries = await fs.readdir(directory, { withFileTypes: true });
   const zipNames = entries
     .filter((entry) => entry.isFile() && isTraceGistPackageFile(entry.name))
@@ -105,7 +105,9 @@ async function listTraceGistPackages(directory, limit) {
   );
 
   packages.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
-  return packages.slice(0, limit);
+  const totalCount = packages.length;
+  const sliced = packages.slice(offset, offset + limit);
+  return { packages: sliced, totalCount, hasMore: offset + limit < totalCount };
 }
 
 async function readZipEntries(zipPath) {
@@ -414,6 +416,7 @@ server.registerPrompt(
 server.registerTool(
   "transcribe_tracegist_package_voice_notes",
   {
+    title: "Transcribe Voice Notes",
     description:
       "Transcribe voice-note files inside a TraceGist package zip using local Python Whisper (no external API).",
     annotations: {
@@ -435,6 +438,16 @@ server.registerTool(
         .optional()
         .describe("ISO 639-1 language code (e.g. en, de, ja). Omit for auto-detection."),
     }),
+    outputSchema: {
+      zipPath: z.string(),
+      model: z.string(),
+      language: z.string().nullable(),
+      voiceFileCount: z.number().optional(),
+      transcribedCount: z.number().optional(),
+      transcriptions: z.array(z.object({ entryName: z.string(), transcript: z.string() })),
+      failures: z.array(z.object({ entryName: z.string(), error: z.string() })).optional(),
+      warning: z.string().optional(),
+    },
   },
   async ({ zipPath, model = "base", language }) => {
     try {
@@ -536,9 +549,10 @@ server.registerTool(
         failures,
       };
 
+      const hasError = transcriptions.length === 0 && failures.length > 0;
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        ...(transcriptions.length === 0 && failures.length > 0 ? { isError: true } : {}),
+        ...(hasError ? { isError: true } : { structuredContent: result }),
       };
     } catch (err) {
       return toolError(err);
@@ -549,6 +563,7 @@ server.registerTool(
 server.registerTool(
   "list_tracegist_packages",
   {
+    title: "List Packages",
     description:
       "List TraceGist marker package zip files. Searches TRACEGIST_DIR (env var), falls back to ~/Downloads, or uses the given directory.",
     annotations: {
@@ -569,14 +584,51 @@ server.registerTool(
         .max(200)
         .optional()
         .describe("Maximum number of packages to return (default: 20)."),
+      offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Number of packages to skip for pagination (default: 0)."),
     }),
+    outputSchema: {
+      totalCount: z.number(),
+      count: z.number(),
+      offset: z.number(),
+      hasMore: z.boolean(),
+      packages: z.array(
+        z.object({
+          name: z.string(),
+          path: z.string(),
+          sizeBytes: z.number(),
+          modifiedAt: z.string(),
+        }),
+      ),
+    },
   },
-  async ({ directory, limit = 20 }) => {
+  async ({ directory, limit = 20, offset = 0 }) => {
     try {
       const searchDir = directory || DEFAULT_DOWNLOADS_DIR;
-      const packages = await listTraceGistPackages(searchDir, limit);
+      const { packages, totalCount, hasMore } = await listTraceGistPackages(
+        searchDir,
+        limit,
+        offset,
+      );
+      const structured = {
+        totalCount,
+        count: packages.length,
+        offset,
+        hasMore,
+        packages,
+      };
       return {
-        content: [{ type: "text", text: renderPackagesText(packages, searchDir) }],
+        content: [
+          {
+            type: "text",
+            text: renderPackagesText(packages, searchDir, totalCount, hasMore, offset),
+          },
+        ],
+        structuredContent: structured,
       };
     } catch (err) {
       return toolError(err);
@@ -587,6 +639,7 @@ server.registerTool(
 server.registerTool(
   "get_tracegist_package_overview",
   {
+    title: "Package Overview",
     description:
       "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. " +
@@ -600,6 +653,15 @@ server.registerTool(
     inputSchema: z.object({
       zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
     }),
+    outputSchema: {
+      zipPath: z.string(),
+      entryCount: z.number(),
+      manifestEntryName: z.string().nullable(),
+      handoffEntryName: z.string().nullable(),
+      manifest: z.any().nullable(),
+      entries: z.array(z.string()),
+      hint: z.string(),
+    },
   },
   async ({ zipPath }) => {
     try {
@@ -619,6 +681,7 @@ server.registerTool(
 
       return {
         content: [{ type: "text", text: JSON.stringify(overview, null, 2) }],
+        structuredContent: overview,
       };
     } catch (err) {
       return toolError(err);
@@ -629,6 +692,7 @@ server.registerTool(
 server.registerTool(
   "get_tracegist_handoff_markdown",
   {
+    title: "Handoff Markdown",
     description:
       "Extract coding agent handoff markdown from a TraceGist package zip. " +
       "Voice note transcripts are automatically generated (via local Whisper) and injected inline " +
@@ -715,7 +779,7 @@ server.registerTool(
           content: [
             {
               type: "text",
-              text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath)}`,
+              text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath, manifest)}`,
             },
           ],
         };
@@ -753,6 +817,7 @@ server.registerTool(
 server.registerTool(
   "read_tracegist_package_file",
   {
+    title: "Read Package File",
     description:
       "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 " +
@@ -793,6 +858,7 @@ server.registerTool(
 server.registerTool(
   "extract_tracegist_package_file",
   {
+    title: "Extract Package File",
     description: "Extract one file from a TraceGist package zip to a local directory.",
     annotations: {
       readOnlyHint: false,
@@ -1237,24 +1303,34 @@ server.resource(
 );
 
 // Tool: watch_live_session
-server.tool(
+server.registerTool(
   "watch_live_session",
-  "Watch a live TraceGist shadowing session in real-time. Returns buffered events since the given sequence number.\n\n" +
-    "IMPORTANT POLLING BEHAVIOR:\n" +
-    "- You MUST keep calling this tool every 2-4 seconds in a loop until sessionActive becomes false.\n" +
-    "- Do NOT stop polling just because there are no new events — the tester is still active.\n" +
-    "- When you see 'voice-transcription' events, the tester recorded a voice marker — read the transcription and react to it.\n" +
-    "- When you see 'question-response-received' events, use get_tester_response to retrieve the full answer with images.\n" +
-    "- When you see 'question-response-transcribed' events, the tester's voice response has been transcribed — read it for context.\n" +
-    "- Marker events with hasPendingVoice=true will have their voiceTranscription field populated once transcription completes.\n" +
-    "- The tester may set voice markers at any time to communicate with you — keep watching for them.\n" +
-    "- If you need clarification, use ask_tester_question to show a toast notification to the tester.\n" +
-    "- Only stop polling when sessionActive is false (the recording ended).",
   {
-    since_seq: z
-      .number()
-      .optional()
-      .describe("Return events after this sequence number. Omit for all buffered events."),
+    title: "Watch Live Session",
+    description:
+      "Watch a live TraceGist shadowing session in real-time. Returns buffered events since the given sequence number.\n\n" +
+      "IMPORTANT POLLING BEHAVIOR:\n" +
+      "- You MUST keep calling this tool every 2-4 seconds in a loop until sessionActive becomes false.\n" +
+      "- Do NOT stop polling just because there are no new events — the tester is still active.\n" +
+      "- When you see 'voice-transcription' events, the tester recorded a voice marker — read the transcription and react to it.\n" +
+      "- When you see 'question-response-received' events, use get_tester_response to retrieve the full answer with images.\n" +
+      "- When you see 'question-response-transcribed' events, the tester's voice response has been transcribed — read it for context.\n" +
+      "- Marker events with hasPendingVoice=true will have their voiceTranscription field populated once transcription completes.\n" +
+      "- The tester may set voice markers at any time to communicate with you — keep watching for them.\n" +
+      "- If you need clarification, use ask_tester_question to show a toast notification to the tester.\n" +
+      "- Only stop polling when sessionActive is false (the recording ended).",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({
+      since_seq: z
+        .number()
+        .optional()
+        .describe("Return events after this sequence number. Omit for all buffered events."),
+    }),
   },
   async ({ since_seq }) => {
     if (!liveSessionActive && liveEvents.length === 0) {
@@ -1363,20 +1439,30 @@ server.tool(
 );
 
 // Tool: ask_tester_question
-server.tool(
+server.registerTool(
   "ask_tester_question",
-  "Ask the tester a short, concise question during a live shadowing session. " +
-    "The question appears as a toast notification in their browser. " +
-    "The tester responds with a voice marker (Alt+Shift+M) and optional highlight captures (Alt+Shift+S). " +
-    "Use get_tester_response to check for their answer.",
   {
-    question: z
-      .string()
-      .max(200)
-      .describe(
-        "Short, concise question for the tester (max 200 chars). " +
-          "Example: 'Can you click the Save button again?' or 'Does the error appear with a different email?'",
-      ),
+    title: "Ask Tester Question",
+    description:
+      "Ask the tester a short, concise question during a live shadowing session. " +
+      "The question appears as a toast notification in their browser. " +
+      "The tester responds with a voice marker (Alt+Shift+M) and optional highlight captures (Alt+Shift+S). " +
+      "Use get_tester_response to check for their answer.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
+    inputSchema: z.object({
+      question: z
+        .string()
+        .max(200)
+        .describe(
+          "Short, concise question for the tester (max 200 chars). " +
+            "Example: 'Can you click the Save button again?' or 'Does the error appear with a different email?'",
+        ),
+    }),
   },
   async ({ question }) => {
     if (!liveSessionActive || !activeConnection) {
@@ -1435,16 +1521,26 @@ server.tool(
 );
 
 // Tool: get_tester_response
-server.tool(
+server.registerTool(
   "get_tester_response",
-  "Check for the tester's response to a question asked during live shadowing. " +
-    "Returns the tester's screenshot, highlight captures, and transcribed voice note.\n\n" +
-    "IMPORTANT: The tester needs time to record their answer (10-60 seconds). " +
-    "Instead of calling this tool repeatedly, prefer polling watch_live_session — " +
-    "you will see a 'question-response-received' event when the response arrives. " +
-    "Then call this tool once to get the full response with transcription and images.",
   {
-    question_id: z.string().describe("The question ID returned by ask_tester_question."),
+    title: "Get Tester Response",
+    description:
+      "Check for the tester's response to a question asked during live shadowing. " +
+      "Returns the tester's screenshot, highlight captures, and transcribed voice note.\n\n" +
+      "IMPORTANT: The tester needs time to record their answer (10-60 seconds). " +
+      "Instead of calling this tool repeatedly, prefer polling watch_live_session — " +
+      "you will see a 'question-response-received' event when the response arrives. " +
+      "Then call this tool once to get the full response with transcription and images.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({
+      question_id: z.string().describe("The question ID returned by ask_tester_question."),
+    }),
   },
   async ({ question_id }) => {
     const response = questionResponses.get(question_id);
@@ -1561,10 +1657,20 @@ server.tool(
 );
 
 // Tool: get_live_screenshot
-server.tool(
+server.registerTool(
   "get_live_screenshot",
-  "Capture a screenshot of the tester's current browser tab during a live shadowing session.",
-  {},
+  {
+    title: "Live Screenshot",
+    description:
+      "Capture a screenshot of the tester's current browser tab during a live shadowing session.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({}),
+  },
   async () => {
     if (!liveSessionActive || !activeConnection) {
       return toolError("No active live shadowing session or extension not connected.");
@@ -1615,13 +1721,23 @@ server.tool(
 );
 
 // Tool: get_live_session_summary
-server.tool(
+server.registerTool(
   "get_live_session_summary",
-  "Get a summary of the live shadowing session including all agent-tester interactions. " +
-    "Call this after the session ends (sessionActive becomes false) to get the complete interaction log " +
-    "for incorporating into your analysis. This includes all questions asked, tester responses, " +
-    "voice transcriptions, and voice marker transcriptions from the session.",
-  {},
+  {
+    title: "Live Session Summary",
+    description:
+      "Get a summary of the live shadowing session including all agent-tester interactions. " +
+      "Call this after the session ends (sessionActive becomes false) to get the complete interaction log " +
+      "for incorporating into your analysis. This includes all questions asked, tester responses, " +
+      "voice transcriptions, and voice marker transcriptions from the session.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({}),
+  },
   async () => {
     if (!liveSessionMeta && liveInteractions.length === 0) {
       return toolError("No live session data available. Start a live shadowing session first.");

package/package.json

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