@taciturnaxolotl/traverse 0.1.0

package/LICENSE.md

@@ -0,0 +1,10 @@
+# The O'Saasy License
+
+Copyright © `2026` `Kieran Klukas`
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# traverse
+
+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
+
+```sh
+bunx @taciturnaxolotl/traverse
+```
+
+requires [bun](https://bun.sh). runs an MCP server on stdio and a web server on `localhost:4173`.
+
+## usage
+
+add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "traverse": {
+      "command": "bunx",
+      "args": ["@taciturnaxolotl/traverse"]
+    }
+  }
+}
+```
+
+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`.
+
+## sharing
+
+click the share button on any diagram to upload it to `traverse.dunkirk.sh` and copy a public link.
+
+configure the share server in `~/Library/Application Support/traverse/config.json`:
+
+```json
+{
+  "shareServerUrl": "https://traverse.dunkirk.sh"
+}
+```
+
+or set `TRAVERSE_SHARE_URL`.
+
+## server mode
+
+run your own share server:
+
+```sh
+TRAVERSE_MODE=server bun run src/index.ts
+```
+
+accepts `POST /api/diagrams` with a diagram JSON body, returns `{ id, url }`.
+
+## env vars
+
+| var | default | description |
+|-----|---------|-------------|
+| `TRAVERSE_PORT` | `4173` | web server port |
+| `TRAVERSE_MODE` | `local` | `local` (mcp + web) or `server` (web only) |
+| `TRAVERSE_SHARE_URL` | `https://traverse.dunkirk.sh` | share server url |
+| `TRAVERSE_DATA_DIR` | platform default | sqlite db location |
+
+<p align="center">
+    <img src="https://raw.githubusercontent.com/taciturnaxolotl/carriage/main/.github/images/line-break.svg" />
+</p>
+
+<p align="center">
+    <i><code>&copy 2026-present <a href="https://dunkirk.sh">Kieran Klukas</a></code></i>
+</p>
+
+<p align="center">
+    <a href="https://tangled.org/dunkirk.sh/traverse/blob/main/LICENSE.md"><img src="https://img.shields.io/static/v1.svg?style=for-the-badge&label=License&message=O'Saasy&logoColor=d9e0ee&colorA=363a4f&colorB=b7bdf8"/></a>
+</p>

package/bin/traverse.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const { execSync, execFileSync } = require("child_process");
+const { resolve } = require("path");
+
+try {
+  execSync("bun --version", { stdio: "ignore" });
+} catch {
+  console.error("Traverse requires Bun to run.");
+  console.error("");
+  console.error("  Install it: curl -fsSL https://bun.sh/install | bash");
+  console.error("  Learn more: https://bun.sh");
+  process.exit(1);
+}
+
+const entry = resolve(__dirname, "..", "src", "index.ts");
+try {
+  execFileSync("bun", ["run", entry], { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status ?? 1);
+}

package/icon.svg

@@ -0,0 +1,5 @@
+<svg width="1024" height="1024" viewBox="0 0 1024 1024" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="1024" height="1024" fill="#191919"/>
+<rect x="124.5" y="193.5" width="774" height="637" stroke="white" stroke-width="41"/>
+<path d="M524.021 291.979C517.382 285.34 506.618 285.34 499.979 291.979L391.792 400.167C385.153 406.805 385.153 417.569 391.792 424.208C398.431 430.847 409.195 430.847 415.833 424.208L512 328.042L608.167 424.208C614.805 430.847 625.569 430.847 632.208 424.208C638.847 417.569 638.847 406.805 632.208 400.167L524.021 291.979ZM512 764H529V304H512H495V764H512Z" fill="white"/>
+</svg>

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@taciturnaxolotl/traverse",
+  "version": "0.1.0",
+  "description": "Interactive code walkthrough diagrams via MCP",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "traverse": "./bin/traverse.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "icon.svg"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --hot run src/index.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,32 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { TraverseConfig } from "./types.ts";
+
+const DEFAULT_SHARE_URL = "https://traverse.dunkirk.sh";
+
+function getConfigDir(): string {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "traverse");
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(xdg, "traverse");
+}
+
+export function loadConfig(): TraverseConfig {
+  if (process.env.TRAVERSE_SHARE_URL) {
+    return { shareServerUrl: process.env.TRAVERSE_SHARE_URL };
+  }
+
+  const configPath = join(getConfigDir(), "config.json");
+
+  try {
+    const text = require("node:fs").readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(text);
+    return {
+      shareServerUrl: parsed.shareServerUrl || DEFAULT_SHARE_URL,
+    };
+  } catch {
+    return { shareServerUrl: DEFAULT_SHARE_URL };
+  }
+}