tracegist-mcp-bridge 0.2.12 → 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,16 +11,23 @@ export function normalizeZipBaseName(entryName) {
   return path.posix.basename(entryName).toLowerCase();
 }
 
-export function renderPackagesText(packages, directory, totalCount = null, hasMore = false, offset = 0) {
+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 countLabel = totalCount != null
-    ? `Showing ${packages.length} of ${totalCount} TraceGist package(s) in ${directory}:`
-    : `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(

package/bin/tracegist-mcp-bridge.mjs

@@ -416,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: {
@@ -437,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 {
@@ -538,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);
@@ -551,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: {
@@ -578,6 +591,20 @@ server.registerTool(
         .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, offset = 0 }) => {
     try {
@@ -587,10 +614,21 @@ server.registerTool(
         limit,
         offset,
       );
+      const structured = {
+        totalCount,
+        count: packages.length,
+        offset,
+        hasMore,
+        packages,
+      };
       return {
         content: [
-          { type: "text", text: renderPackagesText(packages, searchDir, totalCount, hasMore, offset) },
+          {
+            type: "text",
+            text: renderPackagesText(packages, searchDir, totalCount, hasMore, offset),
+          },
         ],
+        structuredContent: structured,
       };
     } catch (err) {
       return toolError(err);
@@ -601,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. " +
@@ -614,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 {
@@ -633,6 +681,7 @@ server.registerTool(
 
       return {
         content: [{ type: "text", text: JSON.stringify(overview, null, 2) }],
+        structuredContent: overview,
       };
     } catch (err) {
       return toolError(err);
@@ -643,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 " +
@@ -767,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 " +
@@ -807,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,
@@ -1254,6 +1306,7 @@ server.resource(
 server.registerTool(
   "watch_live_session",
   {
+    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" +
@@ -1389,6 +1442,7 @@ server.registerTool(
 server.registerTool(
   "ask_tester_question",
   {
+    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. " +
@@ -1470,6 +1524,7 @@ server.registerTool(
 server.registerTool(
   "get_tester_response",
   {
+    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" +
@@ -1605,6 +1660,7 @@ server.registerTool(
 server.registerTool(
   "get_live_screenshot",
   {
+    title: "Live Screenshot",
     description:
       "Capture a screenshot of the tester's current browser tab during a live shadowing session.",
     annotations: {
@@ -1668,6 +1724,7 @@ server.registerTool(
 server.registerTool(
   "get_live_session_summary",
   {
+    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 " +

package/package.json

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