tracegist-mcp-bridge 0.1.4 → 0.2.2

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/tracegist-mcp-bridge.mjs

@@ -11,14 +11,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 const BRIDGE_NAME = "tracegist-mcp-bridge";
-const BRIDGE_VERSION = "0.1.4";
+const { version: BRIDGE_VERSION } = JSON.parse(
+  await fs.readFile(new URL("../package.json", import.meta.url), "utf8"),
+);
 
 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");
@@ -126,7 +126,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 {
@@ -147,9 +149,10 @@ function normalizeZipBaseName(entryName) {
 }
 
 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);
@@ -160,11 +163,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: [] };
@@ -354,10 +358,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}]`);
     }
   }
 
@@ -414,7 +415,7 @@ server.registerPrompt(
             "",
             "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\"`).",
+            '   showing all sections and their sizes. 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.",
@@ -462,23 +463,25 @@ server.registerTool(
   async ({ zipPath, model = "base", language }) => {
     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,
       };
     }
@@ -487,20 +490,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,
+            ),
+          },
+        ],
       };
     }
 
@@ -562,7 +567,8 @@ server.registerTool(
 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.",
     inputSchema: z.object({
       directory: z.string().optional(),
       limit: z.number().int().min(1).max(200).optional(),
@@ -591,7 +597,11 @@ server.registerTool(
   async ({ zipPath }) => {
     const { zip, entryNames } = await readZipEntries(zipPath);
     const { manifest, manifestEntryName } = await tryReadManifest(zip);
-    const { handoffMarkdown, handoffEntryName } = await tryReadHandoffMarkdown(zip, entryNames, manifest);
+    const { handoffMarkdown, handoffEntryName } = await tryReadHandoffMarkdown(
+      zip,
+      entryNames,
+      manifest,
+    );
 
     const overview = {
       zipPath,
@@ -637,17 +647,19 @@ 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,
       };
     }
@@ -657,10 +669,12 @@ server.registerTool(
     // 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}`,
+          },
+        ],
       };
     }
 
@@ -669,10 +683,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)}`,
+          },
+        ],
       };
     }
 
@@ -682,18 +698,22 @@ 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,
+        },
+      ],
     };
   },
 );
@@ -749,7 +769,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,
       };
     }
@@ -763,7 +785,9 @@ server.registerTool(
 );
 
 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.1.4",
+  "version": "0.2.2",
   "description": "Local-first MCP bridge for reading and transcribing TraceGist package zips.",
   "type": "module",
   "bin": {