tracegist-mcp-bridge 0.2.11 → 0.2.12

package/bin/lib.mjs

@@ -11,14 +11,17 @@ 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 +31,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 +87,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 +104,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 +117,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 +158,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) {
@@ -569,14 +571,26 @@ 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)."),
     }),
   },
-  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,
+      );
       return {
-        content: [{ type: "text", text: renderPackagesText(packages, searchDir) }],
+        content: [
+          { type: "text", text: renderPackagesText(packages, searchDir, totalCount, hasMore, offset) },
+        ],
       };
     } catch (err) {
       return toolError(err);
@@ -715,7 +729,7 @@ server.registerTool(
           content: [
             {
               type: "text",
-              text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath)}`,
+              text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath, manifest)}`,
             },
           ],
         };
@@ -1237,24 +1251,33 @@ 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."),
+    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 +1386,29 @@ 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?'",
-      ),
+    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 +1467,25 @@ 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."),
+    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 +1602,19 @@ 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.",
-  {},
+  {
+    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 +1665,22 @@ 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.",
-  {},
+  {
+    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.12",
   "description": "Local-first MCP bridge for reading and transcribing TraceGist package zips.",
   "type": "module",
   "bin": {