mdinterface 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Sundstrom
+
+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.
+
+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,131 @@
+# mdinterface
+
+[![CI](https://github.com/kevinsundstrom/mdinterface/actions/workflows/ci.yml/badge.svg)](https://github.com/kevinsundstrom/mdinterface/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)
+
+<!-- TODO: drop a demo GIF here (select text → ask → the block flashes and re-renders). It's a
+     visual tool; a 10-second capture sells it faster than any paragraph. e.g. docs/demo.gif -->
+
+mdinterface makes editing with Claude precise. A rendered markdown canvas sits beside a live
+Claude session, bridged by the file on disk. The passage you highlight sets both what Claude
+sees and what it is allowed to change, so edits stay scoped to what you pointed at instead of
+sprawling across the document. Ask for a small fix or a full rewrite of that part, and watch
+just that block change and re-render.
+
+The two panes never talk to each other directly. The file on disk is the interface,
+and Claude's awareness is wired through its hooks, not by typing into its prompt:
+
+
+    full doc          ──SessionStart hook──▶ in Claude's context from the start
+    canvas selection  ──file + UserPromptSubmit hook──▶ rides along with each message
+    Claude Code       ──edits──────────────▶ the file on disk
+    file watcher      ──content────────────▶ canvas re-render
+
+## Setup
+
+    cd mdinterface
+    npm install        # express, ws, node-pty (ships a native helper)
+
+Requires Node 18+ and the `claude` CLI on your PATH.
+
+If the terminal pane says **"Terminal unavailable,"** `node-pty`'s prebuilt helper lost
+its executable bit (a common install hiccup). Restore it:
+
+    chmod +x node_modules/node-pty/prebuilds/*/spawn-helper
+
+If there's no prebuilt binary for your platform, build it instead (needs Xcode Command
+Line Tools / build-essential):
+
+    npm rebuild node-pty
+
+The rendering and terminal libraries (`marked`, `xterm` and its addons, `DOMPurify`) are
+**bundled in `public/vendor/`** and served locally, so mdinterface works fully offline — no
+CDN, no first-load internet requirement.
+
+## Run
+
+    node server.js path/to/doc.md
+    # prints a URL like http://localhost:7777/?t=… — open THAT (it carries a session token)
+
+Options:
+
+    --port 8000        # different port
+    --cmd "claude --continue"   # custom launch command (or set MDINTERFACE_CMD)
+
+## Use
+
+- **Select** any text in the rendered doc and it becomes *ambient context* — nothing is
+  typed into the prompt. The selection is mirrored to `.claude/mdinterface-selection.txt`
+  next to the doc, and a `UserPromptSubmit` hook (auto-installed into
+  `.claude/settings.local.json`) silently attaches it to your next message. Give a normal
+  instruction — "tighten this up", "explain this" — and Claude already knows what "this"
+  is. Clear the selection and it stops.
+- **Edits apply immediately** — Claude changes the file and the canvas re-renders. To take
+  one back, use the **Undo** button (rolls back the last change) or ask Claude to revert it;
+  in a git repo, every change is also one `git diff` away.
+- The right pane is the genuine CLI: `/commands`, plan mode, `claude --resume`,
+  everything works, because it *is* claude running in a PTY.
+- When Claude (or anything else — your editor, git checkout) changes the file,
+  only what changed flashes green and updates. Scroll position is preserved.
+
+## Notes
+
+- If `claude` isn't found, it falls back to your shell so you can debug.
+- Undo = git. Run it in a repo and every accepted change is one `git diff` away.
+
+## Security
+
+mdinterface runs a live shell/Claude session over a local WebSocket, so it is locked down to
+this machine only:
+
+- The server binds to **127.0.0.1** (loopback), never reachable from the network.
+- Every request carries a **per-launch token** (in the URL); the WebSocket also checks the
+  `Origin` and `Host` headers, so a website you visit can't connect to it.
+- Rendered markdown HTML is **sanitized** (DOMPurify) before display.
+
+Still your responsibility:
+
+- **Only open documents you trust.** The whole file is fed into Claude's context and an
+  auto-approved `canvas_edit` tool can write it, so a malicious document is a
+  prompt-injection vector.
+- **Single-user machines only.** The launch token is written to
+  `.claude/mdinterface-runtime.json` (mode `600`) so the helper process can reach the server.
+  Anyone who can read your files can read that token and drive the session — fine on your
+  own machine, not on a shared host.
+- mdinterface **writes into the document's folder**: `.claude/settings.local.json`
+  (hooks + MCP pre-approval), `.mcp.json`, `.claude/mdinterface-selection.txt`, and
+  `.claude/mdinterface-runtime.json`. The shipped `.gitignore` covers these for mdinterface's
+  own repo; when you point it at a doc in **another** repo, add them to that repo's
+  `.gitignore`.
+
+### Threat model — how you'd actually get owned
+
+There is essentially **one door, and it's a document you didn't write.** A remote attacker
+can't reach the server (loopback bind + per-launch token + WebSocket `Origin`/`Host` checks
+mean a website you visit or someone on your network can't connect — they don't have the token
+and can't read it cross-origin). So the only way in is to get a file *to* you and have you
+open it in the canvas — a contributor's PR, a shared `.md`, a downloaded doc.
+
+When you open it, the **whole file is fed into Claude's context**, so any instructions hidden
+in it (an HTML comment, white-on-white text, or just confident prose) are read as if you'd
+typed them. From there:
+
+- **The dangerous escalation is `Bash`, and `Bash` is not pre-approved** — it hits the normal
+  permission prompt. So a poisoned doc degrades to social engineering: it tries to get Claude
+  to propose a benign-looking command (`npm install && ./setup.sh`) that you approve on
+  autopilot. **Approving a command you didn't ask for, with a foreign doc open, is the whole
+  ballgame** — that's RCE as you. Don't.
+- **Never run the pane in bypass-permissions / "YOLO" mode with an untrusted doc open.** That
+  auto-approves `Bash`, turning the above into a true zero-click RCE on file open.
+- **Zero-click, no approval needed (bounded):** an injection can still use whatever is already
+  auto-approved — e.g. a `WebFetch(domain:…)` grant becomes a silent exfiltration channel
+  (doc/selection text smuggled in a URL), and `canvas_edit` can silently tamper with the doc
+  you're about to publish. **Prune auto-approve grants you aren't using.**
+
+What an attacker **cannot** do, by construction: reach you over the network, escape
+`canvas_edit`/`canvas_open` into `.claude/` to plant a hook (path-scoped: realpath +
+extension allow-list + `.claude` refusal), steal the token via XSS (sanitized, with a
+plain-text fallback), or read the `600` token file as another user. The boundary that's
+*yours* to hold is the first line: **treat any document you didn't write as untrusted input,
+and don't approve commands for it.**

package/access.js

@@ -0,0 +1,60 @@
+/* Access control for mdinterface. The server drives a live shell/Claude PTY, so it must be
+ * reachable only from this machine's loopback, only by clients holding the per-launch
+ * token, and (for WebSockets) only from the mdinterface page itself — not a random site you
+ * visit (WebSockets bypass same-origin) and not via DNS rebinding.
+ *
+ * Exported as a factory so it can be unit-tested without starting the server.
+ *
+ * @param {number} PORT  the loopback port the server listens on
+ * @param {string} TOKEN the per-launch secret required on every request
+ */
+module.exports = function makeAccess(PORT, TOKEN) {
+  const ALLOWED_HOSTS = new Set([`localhost:${PORT}`, `127.0.0.1:${PORT}`, `[::1]:${PORT}`]);
+
+  /**
+   * Pull the `?t=` token out of a request URL (resolved against `host`).
+   * @param {string} reqUrl
+   * @param {string} [host]
+   * @returns {string | null}
+   */
+  function tokenOf(reqUrl, host) {
+    try {
+      return new URL(reqUrl, `http://${host || "localhost"}`).searchParams.get("t");
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * True iff the WebSocket Origin is a loopback origin on our port (or absent — non-browser).
+   * Exact host equality, so `127.0.0.1.attacker.com` can't slip past a substring check.
+   * @param {string} [origin]
+   * @returns {boolean}
+   */
+  function originAllowed(origin) {
+    if (!origin) return true; // non-browser clients omit Origin; the token still gates them
+    try {
+      const u = new URL(origin);
+      const loopback =
+        u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
+      return loopback && (u.port === String(PORT) || (!u.port && String(PORT) === "80"));
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Gate a WebSocket upgrade: exact Host (anti-rebinding) + loopback Origin + valid token.
+   * @param {{ url?: string, headers: { host?: string, origin?: string } }} req
+   * @returns {boolean}
+   */
+  function wsAllowed(req) {
+    return (
+      ALLOWED_HOSTS.has(req.headers.host) && // DNS-rebinding guard
+      originAllowed(req.headers.origin) && // cross-site WebSocket guard
+      tokenOf(req.url, req.headers.host) === TOKEN
+    ); // per-launch secret token
+  }
+
+  return { ALLOWED_HOSTS, tokenOf, originAllowed, wsAllowed };
+};

package/mcp-server.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/* mdinterface MCP server — exposes `canvas_edit` so Claude can edit the canvas document
+ * WITHOUT the built-in Edit/Write tools' mandatory prior Read. The document is already
+ * in Claude's context (via the SessionStart hook), so it can supply old/new text
+ * directly. This process just writes the file; the running mdinterface server's file
+ * watcher broadcasts the change, so the canvas re-renders instantly.
+ *
+ * Transport: newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio transport).
+ * Only stdout carries protocol messages — never log to stdout; use stderr.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DOC = process.argv[2] ? path.resolve(process.argv[2]) : null;
+const RUNTIME_FILE = DOC
+  ? path.join(path.dirname(DOC), ".claude", "mdinterface-runtime.json")
+  : null;
+
+// How to reach the mdinterface server (port/token) and which document is open (doc), written by
+// the server. Used by canvas_open and to follow file switches; absent ⇒ empty (editing still
+// works, since canvas_edit writes the file directly).
+function runtime() {
+  try {
+    return JSON.parse(fs.readFileSync(RUNTIME_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// Switch the canvas to a different document via the server (so it broadcasts + re-points
+// the watcher). The file must already exist.
+async function canvasOpen(args) {
+  const p = args?.path;
+  if (typeof p !== "string" || !p.trim()) throw new Error("path is required.");
+  const rt = runtime();
+  if (!rt.port || !rt.token) throw new Error("The mdinterface server can't be reached.");
+  let r;
+  try {
+    r = await fetch(`http://127.0.0.1:${rt.port}/open?t=${rt.token}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ path: p }),
+    });
+  } catch {
+    throw new Error("The mdinterface server can't be reached.");
+  }
+  const j = await r.json().catch(() => ({}));
+  if (j.error) throw new Error(j.error);
+  return `Opened ${path.basename(p)} in the canvas.`;
+}
+
+function send(msg) {
+  process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+function result(id, res) {
+  send({ jsonrpc: "2.0", id, result: res });
+}
+function rpcError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+const TOOLS = [
+  {
+    name: "canvas_edit",
+    description:
+      "Edit the markdown document shown in the mdinterface canvas by replacing an exact " +
+      "string. Use this INSTEAD of the built-in Edit/Write tools for the canvas document: " +
+      "it needs no prior Read (the document is already in your context) and the canvas " +
+      "updates instantly. `old_string` must match the file exactly and be unique unless " +
+      "`replace_all` is true. To delete text, pass an empty `new_string`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        old_string: {
+          type: "string",
+          description: "Exact text to replace, verbatim from the document.",
+        },
+        new_string: { type: "string", description: "Replacement text (empty string to delete)." },
+        replace_all: { type: "boolean", description: "Replace every occurrence (default false)." },
+      },
+      required: ["old_string", "new_string"],
+    },
+  },
+  {
+    name: "canvas_open",
+    description:
+      "Switch the mdinterface canvas to a different document so the user sees and edits it. " +
+      "Pass an absolute path to a local .md file (the file must already exist — write it " +
+      "first if needed). Use this to open a draft you just created, e.g. one pulled from " +
+      "Notion. Does not restart the session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute path to the .md file to open." },
+      },
+      required: ["path"],
+    },
+  },
+];
+
+// A regex that matches `str` literally EXCEPT runs of whitespace match any whitespace,
+// so an edit succeeds even if the model got indentation / line-wrapping slightly off.
+/**
+ * @param {string} str
+ * @param {string} flags
+ * @returns {RegExp}
+ */
+function wsTolerantRegex(str, flags) {
+  const escaped = str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(escaped.replace(/\s+/g, "\\s+"), flags);
+}
+
+// Line numbers of up to 5 exact matches, for a "not unique" hint.
+function matchLines(content, str) {
+  const lines = [];
+  let idx = content.indexOf(str);
+  while (idx !== -1 && lines.length < 5) {
+    lines.push(content.slice(0, idx).split("\n").length);
+    idx = content.indexOf(str, idx + str.length);
+  }
+  return lines.length ? ` (lines ${lines.join(", ")})` : "";
+}
+
+// When nothing matches, point the model at the closest text so it fixes its next attempt
+// in one try instead of guessing — the main cause of repeated failed edits.
+function nearbyHint(content, oldStr) {
+  const norm = oldStr.replace(/\s+/g, " ").trim();
+  for (let len = Math.min(norm.length, 50); len >= 10; len -= 5) {
+    let m;
+    try {
+      m = wsTolerantRegex(norm.slice(0, len), "").exec(content);
+    } catch {
+      continue;
+    }
+    if (m) {
+      const line = content.slice(0, m.index).split("\n").length;
+      const text = (content.split("\n")[line - 1] || "").trim();
+      return ` Closest text is at line ${line}: «${text.slice(0, 90)}».`;
+    }
+  }
+  return "";
+}
+
+// Match (exact, then whitespace-tolerant) and apply — or, with dryRun, just validate and
+// return the message that WOULD result without writing (used by the unit tests).
+/**
+ * @param {string} doc absolute path to the document to edit
+ * @param {string} old_string exact text to replace
+ * @param {string} new_string replacement text ("" to delete)
+ * @param {boolean} [replace_all] replace every occurrence instead of requiring uniqueness
+ * @param {boolean} [dryRun] validate only — do not write the file
+ * @returns {string} a human-readable result message
+ */
+function applyEdit(doc, old_string, new_string, replace_all, dryRun) {
+  const content = fs.readFileSync(doc, "utf8");
+  const base = path.basename(doc);
+
+  const exact = content.split(old_string).length - 1;
+  if (exact >= 1) {
+    if (exact > 1 && !replace_all)
+      throw new Error(
+        `old_string matches ${exact} places${matchLines(content, old_string)} — add surrounding context to make it unique, or set replace_all: true.`
+      );
+    if (!dryRun)
+      fs.writeFileSync(
+        doc,
+        replace_all
+          ? content.split(old_string).join(new_string)
+          : content.replace(old_string, () => new_string)
+      );
+    return replace_all ? `Replaced ${exact} occurrence(s) in ${base}.` : `Edited ${base}.`;
+  }
+
+  const re = wsTolerantRegex(old_string, "g");
+  const fuzzy = (content.match(re) || []).length;
+  if (fuzzy >= 1) {
+    if (fuzzy > 1 && !replace_all)
+      throw new Error(
+        `old_string matches ${fuzzy} places (ignoring whitespace) — add surrounding context, or set replace_all: true.`
+      );
+    if (!dryRun)
+      fs.writeFileSync(
+        doc,
+        content.replace(re, () => new_string)
+      ); // global re; fuzzy===1 unless replace_all
+    return `Edited ${base} (matched ignoring whitespace differences).`;
+  }
+
+  throw new Error(
+    `old_string not found in ${base}.${nearbyHint(content, old_string)} ` +
+      `Copy the text verbatim from the document, including punctuation such as em dashes (—) and arrows.`
+  );
+}
+
+async function canvasEdit(args) {
+  const { old_string, new_string, replace_all } = args || {};
+  if (typeof old_string !== "string" || typeof new_string !== "string")
+    throw new Error("old_string and new_string are required strings.");
+  if (!old_string) throw new Error("old_string must not be empty.");
+  if (old_string === new_string) throw new Error("old_string and new_string are identical.");
+
+  const rt = runtime();
+  // The currently-open document — read from the runtime file so canvas_edit follows the
+  // file picker, falling back to the doc this server was launched with.
+  const doc = rt.doc ? path.resolve(rt.doc) : DOC;
+  if (!doc) throw new Error("No document is open.");
+  return applyEdit(doc, old_string, new_string, replace_all, false);
+}
+
+function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    result(id, {
+      protocolVersion: params?.protocolVersion || "2025-06-18",
+      capabilities: { tools: {} },
+      serverInfo: { name: "mdinterface", version: "0.1.0" },
+    });
+  } else if (method === "tools/list") {
+    result(id, { tools: TOOLS });
+  } else if (method === "tools/call") {
+    const name = params?.name;
+    const tool = name === "canvas_edit" ? canvasEdit : name === "canvas_open" ? canvasOpen : null;
+    if (!tool) return rpcError(id, -32602, `Unknown tool: ${name}`);
+    // Tools are async; surface failures as isError results
+    // so the model can react and retry.
+    tool(params.arguments)
+      .then((text) => result(id, { content: [{ type: "text", text }] }))
+      .catch((e) =>
+        result(id, { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true })
+      );
+  } else if (method === "ping") {
+    result(id, {});
+  } else if (id !== undefined) {
+    rpcError(id, -32601, `Method not found: ${method}`);
+  }
+  // notifications (no id), e.g. notifications/initialized — nothing to return
+}
+
+// Run the stdio JSON-RPC loop only when invoked directly. When this file is `require`d
+// (e.g. by the unit tests) the loop stays dormant and only the pure helpers are exposed.
+if (require.main === module) {
+  let buf = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buf += chunk;
+    while (true) {
+      const nl = buf.indexOf("\n");
+      if (nl === -1) break;
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      try {
+        handle(msg);
+      } catch (e) {
+        if (msg && msg.id !== undefined) rpcError(msg.id, -32603, e.message);
+      }
+    }
+  });
+  process.stdin.on("end", () => process.exit(0));
+}
+
+// Exposed for unit tests; importing this module never starts the stdio server (see guard above).
+module.exports = { applyEdit, wsTolerantRegex, matchLines, nearbyHint };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "mdinterface",
+  "version": "0.1.1",
+  "description": "A live markdown canvas wired to Claude Code. Highlight a passage to set both the context and the scope, ask, and Claude edits exactly that and leaves the rest alone.",
+  "license": "MIT",
+  "author": "Kevin Sundstrom",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kevinsundstrom/mdinterface.git"
+  },
+  "homepage": "https://github.com/kevinsundstrom/mdinterface#readme",
+  "bugs": {
+    "url": "https://github.com/kevinsundstrom/mdinterface/issues"
+  },
+  "bin": {
+    "mdinterface": "server.js"
+  },
+  "scripts": {
+    "start": "bash start.sh",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "markdown",
+    "canvas",
+    "live-preview",
+    "editor",
+    "terminal",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "server.js",
+    "mcp-server.js",
+    "access.js",
+    "start.sh",
+    "public/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "express": "^4.19.0",
+    "node-pty": "^1.0.0",
+    "ws": "^8.17.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.14.0",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.5.0"
+  }
+}