@taciturnaxolotl/traverse 0.1.0 → 0.1.1

package/README.md

@@ -4,7 +4,7 @@ interactive code walkthrough diagrams via MCP. share them with anyone.
 
 The canonical repo for this is hosted on tangled over at [`dunkirk.sh/traverse`](https://tangled.org/@dunkirk.sh/traverse)
 
-## install
+## try it now
 
 ```sh
 bunx @taciturnaxolotl/traverse
@@ -12,9 +12,17 @@ bunx @taciturnaxolotl/traverse
 
 requires [bun](https://bun.sh). runs an MCP server on stdio and a web server on `localhost:4173`.
 
-## usage
+## setup
 
-add to your MCP client config:
+add to your MCP client:
+
+**claude code:**
+
+```sh
+claude mcp add traverse -- bunx @taciturnaxolotl/traverse
+```
+
+**claude desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -27,6 +35,8 @@ add to your MCP client config:
 }
 ```
 
+**other MCP clients** — same JSON config, wherever your client reads `.mcp.json` or equivalent.
+
 your AI calls the `walkthrough_diagram` tool with mermaid code + node descriptions, and you get a clickable diagram in your browser.
 
 diagrams persist to sqlite at `~/Library/Application Support/traverse/traverse.db` (macOS) or `$XDG_DATA_HOME/traverse/traverse.db` (linux). override with `TRAVERSE_DATA_DIR`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taciturnaxolotl/traverse",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Interactive code walkthrough diagrams via MCP",
   "module": "src/index.ts",
   "type": "module",

package/src/index.ts

@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod/v4";
 import { generateViewerHTML } from "./template.ts";
 import type { WalkthroughDiagram } from "./types.ts";
-import { initDb, loadAllDiagrams, saveDiagram, deleteDiagramFromDb, generateId } from "./storage.ts";
+import { initDb, loadAllDiagrams, saveDiagram, deleteDiagramFromDb, generateId, getSharedUrl, saveSharedUrl } from "./storage.ts";
 import { loadConfig } from "./config.ts";
 
 const PORT = parseInt(process.env.TRAVERSE_PORT || "4173", 10);
@@ -18,107 +18,139 @@ initDb();
 const diagrams = loadAllDiagrams();
 
 // --- Web server for serving interactive diagrams ---
-Bun.serve({
-  port: PORT,
-  async fetch(req) {
-    const url = new URL(req.url);
-    const diagramMatch = url.pathname.match(/^\/diagram\/([\w-]+)$/);
+let isClient = false;
 
-    if (diagramMatch) {
-      const id = diagramMatch[1]!;
-      const diagram = diagrams.get(id);
-      if (!diagram) {
-        return new Response(generate404HTML("Diagram not found", "This diagram doesn't exist or may have expired."), {
-          status: 404,
+try {
+  Bun.serve({
+    port: PORT,
+    async fetch(req) {
+      const url = new URL(req.url);
+      const diagramMatch = url.pathname.match(/^\/diagram\/([\w-]+)$/);
+
+      if (diagramMatch) {
+        const id = diagramMatch[1]!;
+        const diagram = diagrams.get(id);
+        if (!diagram) {
+          return new Response(generate404HTML("Diagram not found", "This diagram doesn't exist or may have expired."), {
+            status: 404,
+            headers: { "Content-Type": "text/html; charset=utf-8" },
+          });
+        }
+        const existingShareUrl = getSharedUrl(id);
+        return new Response(generateViewerHTML(diagram, GIT_HASH, process.cwd(), {
+          mode: MODE,
+          shareServerUrl: config.shareServerUrl,
+          diagramId: id,
+          existingShareUrl: existingShareUrl ?? undefined,
+        }), {
           headers: { "Content-Type": "text/html; charset=utf-8" },
         });
       }
-      return new Response(generateViewerHTML(diagram, GIT_HASH, process.cwd(), {
-        mode: MODE,
-        shareServerUrl: config.shareServerUrl,
-        diagramId: id,
-      }), {
-        headers: { "Content-Type": "text/html; charset=utf-8" },
-      });
-    }
 
-    // DELETE /api/diagrams/:id
-    const apiMatch = url.pathname.match(/^\/api\/diagrams\/([\w-]+)$/);
-    if (apiMatch && req.method === "DELETE") {
-      const id = apiMatch[1]!;
-      if (!diagrams.has(id)) {
-        return Response.json({ error: "not found" }, { status: 404 });
+      // DELETE /api/diagrams/:id
+      const apiMatch = url.pathname.match(/^\/api\/diagrams\/([\w-]+)$/);
+      if (apiMatch && req.method === "DELETE") {
+        const id = apiMatch[1]!;
+        if (!diagrams.has(id)) {
+          return Response.json({ error: "not found" }, { status: 404 });
+        }
+        diagrams.delete(id);
+        deleteDiagramFromDb(id);
+        return Response.json({ ok: true, id });
       }
-      diagrams.delete(id);
-      deleteDiagramFromDb(id);
-      return Response.json({ ok: true, id });
-    }
 
-    // POST /api/diagrams (server mode: accept diagrams from remote)
-    if (url.pathname === "/api/diagrams" && req.method === "POST") {
-      if (MODE !== "server") {
-        return Response.json({ error: "POST only available in server mode" }, { status: 403 });
+      // POST /api/diagrams/:id/shared-url — save a shared URL for a local diagram
+      const sharedUrlMatch = url.pathname.match(/^\/api\/diagrams\/([\w-]+)\/shared-url$/);
+      if (sharedUrlMatch && req.method === "POST") {
+        const id = sharedUrlMatch[1]!;
+        try {
+          const body = await req.json() as { url: string };
+          if (!body.url) {
+            return Response.json({ error: "missing required field: url" }, { status: 400 });
+          }
+          saveSharedUrl(id, body.url);
+          return Response.json({ ok: true, id, url: body.url });
+        } catch {
+          return Response.json({ error: "invalid JSON body" }, { status: 400 });
+        }
       }
-      try {
-        const body = await req.json() as WalkthroughDiagram;
-        if (!body.code || !body.summary || !body.nodes) {
-          return Response.json({ error: "missing required fields: code, summary, nodes" }, { status: 400 });
+
+      // GET /api/diagrams/:id/shared-url — retrieve a stored shared URL
+      if (sharedUrlMatch && req.method === "GET") {
+        const id = sharedUrlMatch[1]!;
+        const sharedUrl = getSharedUrl(id);
+        if (!sharedUrl) {
+          return Response.json({ url: null });
         }
-        const id = generateId();
-        const diagram: WalkthroughDiagram = {
-          code: body.code,
-          summary: body.summary,
-          nodes: body.nodes,
-          createdAt: new Date().toISOString(),
-        };
-        diagrams.set(id, diagram);
-        saveDiagram(id, diagram);
-        const diagramUrl = `${url.origin}/diagram/${id}`;
-        return Response.json({ id, url: diagramUrl }, {
-          status: 201,
+        return Response.json({ url: sharedUrl });
+      }
+
+      // POST /api/diagrams — accept diagrams from remote or sibling instances
+      if (url.pathname === "/api/diagrams" && req.method === "POST") {
+        try {
+          const body = await req.json() as WalkthroughDiagram;
+          if (!body.code || !body.summary || !body.nodes) {
+            return Response.json({ error: "missing required fields: code, summary, nodes" }, { status: 400 });
+          }
+          const id = generateId();
+          const diagram: WalkthroughDiagram = {
+            code: body.code,
+            summary: body.summary,
+            nodes: body.nodes,
+            createdAt: new Date().toISOString(),
+          };
+          diagrams.set(id, diagram);
+          saveDiagram(id, diagram);
+          const diagramUrl = `${url.origin}/diagram/${id}`;
+          return Response.json({ id, url: diagramUrl }, {
+            status: 201,
+            headers: {
+              "Access-Control-Allow-Origin": "*",
+            },
+          });
+        } catch {
+          return Response.json({ error: "invalid JSON body" }, { status: 400 });
+        }
+      }
+
+      // OPTIONS /api/diagrams — CORS preflight
+      if (url.pathname === "/api/diagrams" && req.method === "OPTIONS") {
+        return new Response(null, {
+          status: 204,
           headers: {
             "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "POST, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type",
           },
         });
-      } catch {
-        return Response.json({ error: "invalid JSON body" }, { status: 400 });
       }
-    }
 
-    // OPTIONS /api/diagrams — CORS preflight
-    if (url.pathname === "/api/diagrams" && req.method === "OPTIONS") {
-      return new Response(null, {
-        status: 204,
-        headers: {
-          "Access-Control-Allow-Origin": "*",
-          "Access-Control-Allow-Methods": "POST, OPTIONS",
-          "Access-Control-Allow-Headers": "Content-Type",
-        },
-      });
-    }
+      if (url.pathname === "/icon.svg") {
+        return new Response(Bun.file(import.meta.dir + "/../icon.svg"), {
+          headers: { "Content-Type": "image/svg+xml" },
+        });
+      }
 
-    if (url.pathname === "/icon.svg") {
-      return new Response(Bun.file(import.meta.dir + "/../icon.svg"), {
-        headers: { "Content-Type": "image/svg+xml" },
-      });
-    }
+      // List available diagrams
+      if (url.pathname === "/") {
+        const html = MODE === "server"
+          ? generateServerIndexHTML(diagrams.size, GIT_HASH)
+          : generateLocalIndexHTML(diagrams, GIT_HASH);
+        return new Response(html, {
+          headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
+      }
 
-    // List available diagrams
-    if (url.pathname === "/") {
-      const html = MODE === "server"
-        ? generateServerIndexHTML(diagrams.size, GIT_HASH)
-        : generateLocalIndexHTML(diagrams, GIT_HASH);
-      return new Response(html, {
+      return new Response(generate404HTML("Page not found", "There's nothing at this URL."), {
+        status: 404,
         headers: { "Content-Type": "text/html; charset=utf-8" },
       });
-    }
-
-    return new Response(generate404HTML("Page not found", "There's nothing at this URL."), {
-      status: 404,
-      headers: { "Content-Type": "text/html; charset=utf-8" },
-    });
-  },
-});
+    },
+  });
+} catch {
+  isClient = true;
+  console.error(`Web server already running on port ${PORT}, running in client mode`);
+}
 
 // --- MCP Server (local mode only) ---
 if (MODE === "local") {
@@ -158,17 +190,34 @@ Then build the diagram:
       nodes: z.record(z.string(), nodeMetadataSchema),
     }),
   }, async ({ code, summary, nodes }) => {
-    const id = generateId();
-    const diagram: WalkthroughDiagram = {
-      code,
-      summary,
-      nodes,
-      createdAt: new Date().toISOString(),
-    };
-    diagrams.set(id, diagram);
-    saveDiagram(id, diagram);
+    let diagramUrl: string;
 
-    const diagramUrl = `http://localhost:${PORT}/diagram/${id}`;
+    if (isClient) {
+      // POST diagram to the existing web server instance
+      const res = await fetch(`http://localhost:${PORT}/api/diagrams`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ code, summary, nodes }),
+      });
+      if (!res.ok) {
+        return {
+          content: [{ type: "text", text: `Failed to send diagram to server: ${res.statusText}` }],
+        };
+      }
+      const data = await res.json() as { id: string; url: string };
+      diagramUrl = data.url;
+    } else {
+      const id = generateId();
+      const diagram: WalkthroughDiagram = {
+        code,
+        summary,
+        nodes,
+        createdAt: new Date().toISOString(),
+      };
+      diagrams.set(id, diagram);
+      saveDiagram(id, diagram);
+      diagramUrl = `http://localhost:${PORT}/diagram/${id}`;
+    }
 
     return {
       content: [

package/src/storage.ts

@@ -34,6 +34,13 @@ export function initDb(): Database {
       created_at TEXT
     )
   `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS shared_urls (
+      local_id TEXT PRIMARY KEY,
+      remote_url TEXT,
+      shared_at TEXT
+    )
+  `);
   return db;
 }
 
@@ -57,6 +64,18 @@ export function deleteDiagramFromDb(id: string): void {
   db.run("DELETE FROM diagrams WHERE id = ?", [id]);
 }
 
+export function getSharedUrl(localId: string): string | null {
+  const row = db.query("SELECT remote_url FROM shared_urls WHERE local_id = ?").get(localId) as { remote_url: string } | null;
+  return row?.remote_url ?? null;
+}
+
+export function saveSharedUrl(localId: string, remoteUrl: string): void {
+  db.run(
+    "INSERT OR REPLACE INTO shared_urls (local_id, remote_url, shared_at) VALUES (?, ?, ?)",
+    [localId, remoteUrl, new Date().toISOString()]
+  );
+}
+
 export function generateId(): string {
   return crypto.randomUUID();
 }

package/src/template.ts

@@ -4,11 +4,12 @@ interface ViewerOptions {
   mode?: "local" | "server";
   shareServerUrl?: string;
   diagramId?: string;
+  existingShareUrl?: string;
 }
 
 export function generateViewerHTML(diagram: WalkthroughDiagram, gitHash: string = "dev", projectRoot: string = "", options: ViewerOptions = {}): string {
   const diagramJSON = JSON.stringify(diagram).replace(/<\//g, "<\\/");
-  const { mode = "local", shareServerUrl = "", diagramId = "" } = options;
+  const { mode = "local", shareServerUrl = "", diagramId = "", existingShareUrl = "" } = options;
 
   return `<!DOCTYPE html>
 <html lang="en">
@@ -648,6 +649,7 @@ export function generateViewerHTML(diagram: WalkthroughDiagram, gitHash: string
     const SHARE_SERVER_URL = ${JSON.stringify(shareServerUrl)};
     const DIAGRAM_ID = ${JSON.stringify(diagramId)};
     const VIEWER_MODE = ${JSON.stringify(mode)};
+    let EXISTING_SHARE_URL = ${JSON.stringify(existingShareUrl)};
 
     const COPY_ICON = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="5" y="5" width="8" height="8" rx="1.5"/><path d="M3 11V3a1.5 1.5 0 011.5-1.5H11"/></svg>';
     const CHECK_ICON = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 8.5l3.5 3.5 6.5-7"/></svg>';
@@ -935,6 +937,18 @@ export function generateViewerHTML(diagram: WalkthroughDiagram, gitHash: string
       shareBtn.addEventListener("click", async () => {
         shareBtn.disabled = true;
         try {
+          // If we already have a shared URL, just copy it
+          if (EXISTING_SHARE_URL) {
+            await navigator.clipboard.writeText(EXISTING_SHARE_URL);
+            shareBtn.querySelector("span").textContent = "Copied link!";
+            shareBtn.classList.add("shared");
+            setTimeout(() => {
+              shareBtn.querySelector("span").textContent = "Share";
+              shareBtn.classList.remove("shared");
+            }, 2000);
+            return;
+          }
+
           const res = await fetch(SHARE_SERVER_URL + "/api/diagrams", {
             method: "POST",
             headers: { "Content-Type": "application/json" },
@@ -943,6 +957,17 @@ export function generateViewerHTML(diagram: WalkthroughDiagram, gitHash: string
           if (!res.ok) throw new Error("Share failed");
           const data = await res.json();
           await navigator.clipboard.writeText(data.url);
+
+          // Save the shared URL locally so we don't re-upload next time
+          if (DIAGRAM_ID) {
+            fetch("/api/diagrams/" + DIAGRAM_ID + "/shared-url", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ url: data.url }),
+            }).catch(() => {}); // best-effort
+            EXISTING_SHARE_URL = data.url;
+          }
+
           shareBtn.querySelector("span").textContent = "Copied link!";
           shareBtn.classList.add("shared");
           setTimeout(() => {