jotview 0.3.0 → 0.4.1

package/README.md

@@ -21,6 +21,7 @@ entirely in the browser.
 ```
 jotview <file>            mint a link from a file
 jotview                   read markdown from stdin
+jotview decode <url>      print the markdown behind a /d or short link
 jotview mcp [--raw]       run as an MCP server for AI agents
 
   --raw                   never shorten; always the full /d URL
@@ -40,8 +41,13 @@ jotview README.md --open
 cat notes.md | jotview
 jotview notes.md | pbcopy
 LINK=$(jotview notes.md --raw)
+jotview decode https://surl.jotbins.com/abc123 > notes.md
 ```
 
+`decode` accepts `jotbins.com/d` links (decoded locally) and
+`surl.jotbins.com` short links (fetched; like a click, that keeps an active
+short link alive).
+
 ## Shortening, and what it costs you
 
 A document's link grows with the document — roughly half the markdown's size in
@@ -72,9 +78,10 @@ and exits 0 — it never fails your pipeline over a shortening problem.
 
 ## Use with AI agents (MCP)
 
-`jotview mcp` is a stdio [MCP](https://modelcontextprotocol.io) server with one
-tool, `render_markdown`. An AI writes markdown — notes, a report, a Mermaid
-diagram — and gets back a jotbins link to hand you.
+`jotview mcp` is a stdio [MCP](https://modelcontextprotocol.io) server with two
+tools. With `render_markdown` an AI writes markdown — notes, a report, a
+Mermaid diagram — and gets back a jotbins link to hand you; with `read_link`
+it reads a jotbins link you share.
 
 **Claude Code**
 
@@ -90,11 +97,16 @@ claude mcp add jotview -- npx -y jotview mcp
 
 Then just ask: *"draw a diagram of our deploy flow and give me a jotbins link."*
 
-**The tool** takes `content` (the markdown), plus optional `keep` (make a
-short link permanent) and `shorten` (`"auto"`, `"always"` or `"never"`). It
-returns a ready-made markdown link, `[First heading](url)`, and a note on
-whether anything was uploaded. It never reads files — the AI passes text it
-already has.
+**`render_markdown`** takes `content` (the markdown), plus optional `title`
+(link text instead of the first heading), `keep` (make a short link
+permanent) and `shorten` (`"auto"`, `"always"` or `"never"`). It returns a
+ready-made markdown link, `[First heading](url)`, and a note on whether
+anything was uploaded. It never reads files — the AI passes text it already
+has.
+
+**`read_link`** takes a `url` (a `/d` link or a short link) and returns the
+markdown behind it, so you can paste a link and say *"fix the typos and give
+me a new link."* Links never change; an edit is a new link.
 
 **Uploads.** Every character of a link costs tokens, so MCP shortens sooner
 than the CLI: links over **500** characters go through `surl.jotbins.com`,
@@ -107,6 +119,23 @@ claude mcp add jotview -- npx -y jotview mcp --raw
 
 Works with clients on any MCP revision from `2024-11-05` through `2026-07-28`.
 
+### Remote server — no install
+
+The same tool runs at **`https://mcp.jotbins.com/mcp`** (Streamable HTTP, no
+sign-in), for clients that can't run local commands.
+
+- **claude.ai (web and mobile):** Settings → Connectors → Add custom
+  connector → paste `https://mcp.jotbins.com/mcp`.
+- **Claude Code:** `claude mcp add -s user --transport http jotview https://mcp.jotbins.com/mcp`
+
+Same rules as the local server, except it can't forbid uploads: use
+`shorten: "never"` per call, or the local `--raw` server, to keep a document
+off `surl.jotbins.com`. Uploads are rate-limited per client; over the limit
+you still get the full link.
+
+The Worker lives in [`worker/`](worker/) and deploys with
+`cd worker && npx wrangler deploy`.
+
 ## Output contract
 
 **stdout is the URL and nothing else.** Notices, warnings, and errors go to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jotview",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Turn markdown into a jotbins /d link — a CLI and an MCP server. Zero dependencies.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -2,8 +2,10 @@ import { readFileSync } from "node:fs";
 import { JotviewError, MAX_DOC_BYTES } from "./codec.js";
 import { DEFAULT_BASE_URL, SHORTENER_URL } from "./shorten.js";
 import { mint } from "./mint.js";
+import { readLink } from "./read.js";
 import { serve } from "./mcp-stdio.js";
 import { renderTool } from "./mcp-tool.js";
+import { readTool } from "./mcp-read-tool.js";
 import { openUrl, copyText } from "./platform.js";
 export { DEFAULT_BASE_URL };
 
@@ -16,6 +18,7 @@ export const HELP = `jotview — turn markdown into a jotbins /d link
 Usage:
   jotview <file>            mint a link from a file
   jotview                   read markdown from stdin
+  jotview decode <url>      print the markdown behind a /d or short link
   jotview mcp [--raw]       run as an MCP server (stdio) for AI agents;
                             --raw never uploads, --base-url works too
 
@@ -193,6 +196,7 @@ function applySideEffects(url, opts, io) {
  */
 export async function run(argv, io) {
   if (argv[0] === "mcp") return runMcp(argv.slice(1), io);
+  if (argv[0] === "decode") return runDecode(argv.slice(1), io);
 
   /** @type {Options} */
   let opts;
@@ -250,6 +254,28 @@ export async function run(argv, io) {
   }
 }
 
+/**
+ * `jotview decode <url>`: the markdown, byte for byte, on stdout — so
+ * `jotview decode URL > doc.md` and `jotview decode URL | jotview` round-trip.
+ * @param {string[]} argv
+ * @param {Parameters<typeof run>[1]} io
+ * @returns {Promise<number>}
+ */
+async function runDecode(argv, io) {
+  if (argv.length !== 1 || argv[0].startsWith("-")) {
+    io.stderr(`jotview: decode takes exactly one link\n\n${HELP}`);
+    return 2;
+  }
+  try {
+    const { markdown } = await readLink(argv[0]);
+    io.stdout(markdown);
+    return 0;
+  } catch (err) {
+    io.stderr(`jotview: ${/** @type {Error} */ (err).message}\n`);
+    return 1;
+  }
+}
+
 /**
  * `jotview mcp`: stdout belongs to the protocol from here on, so usage
  * errors go to stderr and nothing else is ever printed.
@@ -270,7 +296,7 @@ async function runMcp(argv, io) {
     write: io.stdout,
     ctx: {
       version: io.version,
-      tools: [renderTool({ allowUpload: !opts.raw, baseUrl: opts.baseUrl })],
+      tools: [renderTool({ allowUpload: !opts.raw, baseUrl: opts.baseUrl }), readTool({})],
     },
   });
   return 0;

package/src/codec.js

@@ -1,4 +1,4 @@
-import { deflateRawSync } from "node:zlib";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
 
 /** Payload prefix. Versions the encoding; must match jotbins' fragmentDoc.ts. */
 export const PREFIX = "z:";
@@ -7,7 +7,7 @@ export const PREFIX = "z:";
  *  the browser refuses to open, so reject at encode time instead. */
 export const MAX_DOC_BYTES = 1_000_000;
 
-/** @typedef {"too-large" | "empty" | "not-found" | "usage" | "read-failed"} ErrorCode */
+/** @typedef {"too-large" | "empty" | "not-found" | "usage" | "read-failed" | "bad-link" | "cleaned-up"} ErrorCode */
 
 export class JotviewError extends Error {
   /** @param {ErrorCode} code @param {string} message */
@@ -40,3 +40,29 @@ export function encode(md) {
   // produce via CompressionStream("deflate-raw").
   return PREFIX + toBase64Url(deflateRawSync(bytes));
 }
+
+const BASE64URL = /^[A-Za-z0-9_-]*$/;
+
+/**
+ * Decode a `z:` fragment payload back into markdown.
+ * @param {string} payload  the part after `#`
+ * @returns {string}
+ */
+export function decode(payload) {
+  if (!payload.startsWith(PREFIX)) {
+    throw new JotviewError("bad-link", `not a jotbins doc payload (expected it to start with ${PREFIX})`);
+  }
+  const body = payload.slice(PREFIX.length);
+  // Buffer's base64 decoder silently skips junk, so check the alphabet first.
+  if (!BASE64URL.test(body)) throw new JotviewError("bad-link", "the link's document data is corrupted");
+  try {
+    // Capped so a tiny link can't inflate into gigabytes.
+    return inflateRawSync(Buffer.from(body, "base64url"), { maxOutputLength: MAX_DOC_BYTES })
+      .toString("utf8");
+  } catch (err) {
+    if (/** @type {{code?: string}} */ (err).code === "ERR_BUFFER_TOO_LARGE") {
+      throw new JotviewError("too-large", `the document is over the ${MAX_DOC_BYTES}-byte limit`);
+    }
+    throw new JotviewError("bad-link", "the link's document data is corrupted");
+  }
+}

package/src/landing.js

@@ -0,0 +1,89 @@
+/**
+ * The page a person sees opening the MCP server in a browser: what it is and
+ * how to connect it to each common AI tool. Plain text, 80 columns.
+ * @param {string} endpoint  e.g. https://mcp.jotbins.com/mcp
+ */
+export const landingText = (endpoint) => `jotview MCP — rendered jotbins links from any AI tool
+=====================================================
+
+Connect this server and your AI gets one tool, render_markdown. Ask it for
+notes, a report or a Mermaid diagram "as a jotbins link" and it hands back a
+link that opens the page, fully rendered, on jotbins.com.
+
+  Endpoint:  ${endpoint}
+  Transport: Streamable HTTP. No sign-in, no API key.
+
+
+CONNECT IT
+----------
+
+claude.ai, Claude Desktop and the Claude mobile apps
+  1. Settings → Connectors → Add custom connector.
+  2. Name it jotview and paste the endpoint URL above.
+  3. In a chat, make sure jotview is switched on in the tools menu.
+  Connectors added on the web also show up on mobile. Custom connectors may
+  need a paid Claude plan; on Team and Enterprise an owner adds them.
+
+Claude Code
+  claude mcp add -s user --transport http jotview ${endpoint}
+
+Cursor — ~/.cursor/mcp.json
+  {
+    "mcpServers": {
+      "jotview": { "url": "${endpoint}" }
+    }
+  }
+
+VS Code (Copilot agent mode) — .vscode/mcp.json
+  {
+    "servers": {
+      "jotview": { "type": "http", "url": "${endpoint}" }
+    }
+  }
+
+Windsurf — ~/.codeium/windsurf/mcp_config.json
+  {
+    "mcpServers": {
+      "jotview": { "serverUrl": "${endpoint}" }
+    }
+  }
+
+Gemini CLI — ~/.gemini/settings.json
+  {
+    "mcpServers": {
+      "jotview": { "httpUrl": "${endpoint}" }
+    }
+  }
+
+Anything else
+  Add a remote MCP server with the endpoint URL. If your tool can only run
+  local servers, use the npm package instead (needs Node 18+):
+    npx -y jotview mcp
+
+
+TRY IT
+------
+
+  "Write up our deploy checklist and give me a jotbins link."
+  "Draw the login flow as a Mermaid sequence diagram, as a jotbins link."
+  "Here's my jotbins link — fix the typos and give me a new one."
+
+The AI answers with a link named after the document's first heading. It can
+also read any jotbins link you paste; an edit gives you a new link, the old
+one never changes.
+
+
+WHAT HAPPENS TO YOUR DOCUMENT
+-----------------------------
+
+Small documents live entirely inside the link, after the #. They never reach
+a server and never expire.
+
+Larger ones (a link over 500 characters) are uploaded to surl.jotbins.com
+for a short link. Short links are deleted after 30 days without a visit.
+Ask the AI to "keep" the link to make it permanent, or "don't upload" to
+always get the full link.
+
+
+Source, CLI and docs: https://github.com/jotbins/jotview
+`;

package/src/mcp-http.js

@@ -0,0 +1,64 @@
+import { handleMessage, parseError, LEGACY_VERSIONS, MODERN_VERSIONS } from "./mcp.js";
+import { landingText } from "./landing.js";
+
+/** Docs cap at 1 MB (MAX_DOC_BYTES); leave room for JSON escaping. */
+export const MAX_BODY_BYTES = 2_000_000;
+
+const KNOWN_VERSIONS = [...LEGACY_VERSIONS, ...MODERN_VERSIONS];
+
+// No cookies or credentials are involved, so any origin may call — that lets
+// browser-based clients such as MCP Inspector connect directly.
+const CORS = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "POST, OPTIONS",
+  "access-control-allow-headers": "content-type, accept, mcp-protocol-version, mcp-session-id",
+  "access-control-max-age": "86400",
+};
+
+/** @param {unknown} body @param {number} [status] */
+const json = (body, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { ...CORS, "content-type": "application/json" } });
+
+/** @param {string} text @param {number} status @param {Record<string,string>} [headers] */
+const plain = (text, status, headers = {}) =>
+  new Response(text, { status, headers: { ...CORS, "content-type": "text/plain; charset=utf-8", ...headers } });
+
+/**
+ * Serve MCP over Streamable HTTP. Every request gets exactly one JSON reply —
+ * no SSE stream and no sessions, since the only tool answers immediately.
+ *
+ * @param {Request} request
+ * @param {import("./mcp.js").Context} ctx
+ * @returns {Promise<Response>}
+ */
+export async function handleHttp(request, ctx) {
+  const url = new URL(request.url);
+  if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS });
+
+  if (url.pathname === "/") {
+    if (request.method !== "GET") return plain("Method not allowed\n", 405, { allow: "GET" });
+    return plain(landingText(`${url.origin}/mcp`), 200);
+  }
+  if (url.pathname !== "/mcp") return plain("Not found\n", 404);
+  if (request.method !== "POST") return plain("Method not allowed\n", 405, { allow: "POST, OPTIONS" });
+
+  const version = request.headers.get("mcp-protocol-version");
+  if (version !== null && !KNOWN_VERSIONS.includes(version)) {
+    return plain(`Unsupported MCP-Protocol-Version: ${version}\n`, 400);
+  }
+
+  const declared = Number(request.headers.get("content-length"));
+  if (declared > MAX_BODY_BYTES) return plain("Request too large\n", 413);
+  const bytes = await request.arrayBuffer();
+  if (bytes.byteLength > MAX_BODY_BYTES) return plain("Request too large\n", 413);
+
+  let msg;
+  try {
+    msg = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    return json(parseError(), 400);
+  }
+
+  const reply = await handleMessage(msg, ctx);
+  return reply ? json(reply) : new Response(null, { status: 202, headers: CORS });
+}

package/src/mcp-read-tool.js

@@ -0,0 +1,46 @@
+import { readLink } from "./read.js";
+import { JotviewError } from "./codec.js";
+
+const DEFINITION = {
+  name: "read_link",
+  title: "Read a jotbins link",
+  description:
+    "Get the markdown behind a jotbins link — a jotbins.com/d link or a " +
+    "surl.jotbins.com short link — so you can read, quote or edit it. Links " +
+    "never change: to edit, change the markdown and call render_markdown for " +
+    "a new link. Reading a short link counts as a visit and keeps it alive.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "The jotbins.com/d or surl.jotbins.com link." },
+    },
+    required: ["url"],
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: true, openWorldHint: true },
+};
+
+/** @param {string} text */
+const toolError = (text) => ({ content: [{ type: "text", text }], isError: true });
+
+/**
+ * @param {{fetchImpl?: typeof fetch}} opts  the Worker passes its surl binding
+ * @returns {import("./mcp.js").Tool}
+ */
+export function readTool(opts) {
+  return {
+    definition: DEFINITION,
+    async call(args) {
+      if (typeof args.url !== "string" || args.url.trim() === "") {
+        return toolError("url is required: pass the jotbins link to read.");
+      }
+      try {
+        const { markdown } = await readLink(args.url, { fetchImpl: opts.fetchImpl });
+        return { content: [{ type: "text", text: markdown }] };
+      } catch (err) {
+        if (err instanceof JotviewError) return toolError(`Can't read that link: ${err.message}`);
+        throw err;
+      }
+    },
+  };
+}

package/src/mcp-tool.js

@@ -28,6 +28,10 @@ const DEFINITION = {
         type: "boolean",
         description: "Make a shortened link permanent instead of expiring after 30 days unused.",
       },
+      title: {
+        type: "string",
+        description: "Link text to show instead of the document's first heading.",
+      },
       shorten: {
         type: "string",
         enum: MODES,
@@ -48,10 +52,12 @@ const DEFINITION = {
  */
 export function docTitle(md) {
   const match = md.match(/^#{1,6}[ \t]+(.+?)[ \t#]*$/m);
-  const title = match ? match[1].trim().slice(0, TITLE_MAX) : "jotbins doc";
-  return title.replace(/[\\[\]]/g, (c) => `\\${c}`);
+  return linkText(match ? match[1] : "jotbins doc");
 }
 
+/** @param {string} text */
+const linkText = (text) => text.trim().slice(0, TITLE_MAX).replace(/[\\[\]]/g, (c) => `\\${c}`);
+
 /** @param {string} text */
 const toolError = (text) => ({ content: [{ type: "text", text }], isError: true });
 
@@ -63,6 +69,9 @@ function validate(args) {
   if (typeof args.content !== "string") return "content is required: pass the markdown to render as a string.";
   if (args.content.trim() === "") return "content is empty: pass the markdown to render.";
   if (args.keep !== undefined && typeof args.keep !== "boolean") return "keep must be true or false.";
+  if (args.title !== undefined && (typeof args.title !== "string" || args.title.trim() === "")) {
+    return "title must be a non-empty string, or left out to use the first heading.";
+  }
   if (args.shorten !== undefined && !MODES.includes(/** @type {string} */ (args.shorten))) {
     return 'shorten must be "auto", "always" or "never".';
   }
@@ -129,7 +138,7 @@ export function renderTool(opts) {
       }
 
       const text =
-        `[${docTitle(md)}](${r.url})\n\n` +
+        `[${typeof args.title === "string" ? linkText(args.title) : docTitle(md)}](${r.url})\n\n` +
         `${describe(r, keep && !r.shortened)}\n` +
         "Show it to the user as the markdown link above, not as a bare URL.";
       return { content: [{ type: "text", text }] };

package/src/mcp.js

@@ -3,7 +3,7 @@
  *
  * jotview is a dual-era server. Clients on the handshake revisions open with
  * `initialize`; clients on 2026-07-28 open with `server/discover` and put the
- * protocol version in every request's `_meta`. The one tool is stateless, so
+ * protocol version in every request's `_meta`. The tools are stateless, so
  * both eras are served from the same handlers and only the envelope differs.
  */
 
@@ -16,7 +16,8 @@ export const INSTRUCTIONS =
   "rendered jotbins page. Show the returned link to the user as a markdown " +
   "link, [title](url); never paste a bare jotbins.com/d URL, it can be " +
   "thousands of characters. Long documents are uploaded to shorten the link " +
-  'unless the user asked to keep them local (shorten: "never").';
+  'unless the user asked to keep them local (shorten: "never"). Use read_link ' +
+  "to get the markdown behind a jotbins link the user shares.";
 
 const META_VERSION = "io.modelcontextprotocol/protocolVersion";
 const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";

package/src/read.js

@@ -0,0 +1,89 @@
+import { decode, JotviewError } from "./codec.js";
+import { SHORTENER_URL } from "./shorten.js";
+
+const SHORTENER_HOST = new URL(SHORTENER_URL).host;
+const DOC_HOSTS = ["jotbins.com", "www.jotbins.com"];
+const SHORT_PATH = /^\/[A-Za-z0-9]+$/;
+
+/** Milliseconds before giving up on surl. */
+const TIMEOUT_MS = 5000;
+
+// Pinned by surl's own page tests (src/pages.rs): the waiting page links its
+// target from #continue; the cleaned-up page has #deleted and #purge.
+const CONTINUE_HREF = /id="continue" href="([^"]*)"/;
+const DELETED = /id="deleted"/;
+const PURGE_TEXT = /id="purge">([^<]*)</;
+
+/** @param {string} s */
+const unescapeHtml = (s) =>
+  s.replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+
+const notJotbins = () =>
+  new JotviewError("bad-link", `only jotbins.com/d links and ${SHORTENER_HOST} short links can be read`);
+
+/**
+ * Decode a jotbins `/d` URL; anything else is a bad link.
+ * @param {string} raw
+ * @returns {{markdown: string, url: string}}
+ */
+function decodeDocUrl(raw) {
+  let url;
+  try { url = new URL(raw); } catch { throw notJotbins(); }
+  if (url.protocol !== "https:" || !DOC_HOSTS.includes(url.host) || url.pathname !== "/d") {
+    throw notJotbins();
+  }
+  return { markdown: decode(url.hash.slice(1)), url: raw };
+}
+
+/**
+ * Turn a jotbins link back into its markdown. `/d` links decode locally;
+ * surl short links are fetched (and, like a click, keep an active link alive).
+ * Only surl is ever fetched.
+ *
+ * @param {string} input
+ * @param {{fetchImpl?: typeof fetch}} [opts]
+ * @returns {Promise<{markdown: string, url: string}>} `url` is the /d link
+ */
+export async function readLink(input, opts = {}) {
+  const raw = input.trim();
+  let url;
+  try { url = new URL(raw); } catch { throw notJotbins(); }
+  if (url.host !== SHORTENER_HOST) return decodeDocUrl(raw);
+  if (url.protocol !== "https:" || !SHORT_PATH.test(url.pathname)) throw notJotbins();
+
+  const doFetch = opts.fetchImpl ?? fetch;
+  let response;
+  try {
+    response = await doFetch(`https://${SHORTENER_HOST}${url.pathname}`, {
+      redirect: "manual",
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw new JotviewError("read-failed", `couldn't reach ${SHORTENER_HOST}: ${/** @type {Error} */ (err).message}`);
+  }
+
+  if (response.status === 404) {
+    throw new JotviewError("not-found", "that short link doesn't exist (or was deleted for good)");
+  }
+  if (response.status >= 300 && response.status < 400) {
+    return decodeDocUrl(response.headers.get("location") ?? "");
+  }
+  if (!response.ok) {
+    throw new JotviewError("read-failed", `${SHORTENER_HOST} returned ${response.status}`);
+  }
+
+  const html = await response.text();
+  const target = html.match(CONTINUE_HREF);
+  if (target) return decodeDocUrl(unescapeHtml(target[1]));
+  if (DELETED.test(html)) {
+    const purge = html.match(PURGE_TEXT)?.[1];
+    throw new JotviewError(
+      "cleaned-up",
+      "that short link was cleaned up after 30 days without a visit" +
+        (purge ? ` and is gone for good on ${unescapeHtml(purge)}` : "") +
+        ". Open it in a browser and press Save to bring it back.",
+    );
+  }
+  throw new JotviewError("read-failed", `unexpected page from ${SHORTENER_HOST}`);
+}

package/src/shorten.js

@@ -28,15 +28,17 @@ export function shouldShorten(url, opts) {
 /**
  * Shorten a URL. Never throws — the caller falls back to the raw URL.
  * @param {string} url
- * @param {{endpoint?: string, permanent?: boolean}} [options]
+ * @param {{endpoint?: string, permanent?: boolean, fetchImpl?: typeof fetch}} [options]
  *   `permanent` asks surl for a link that never expires. Left out of the body
  *   when false, so the request matches what older surl versions expect.
+ *   `fetchImpl` lets the Worker route through its surl service binding.
  * @returns {Promise<{ok: true, short: string} | {ok: false, reason: string}>}
  */
 export async function shorten(url, options = {}) {
   const endpoint = options.endpoint ?? SHORTENER_URL;
+  const doFetch = options.fetchImpl ?? fetch;
   try {
-    const response = await fetch(endpoint, {
+    const response = await doFetch(endpoint, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(options.permanent ? { url, permanent: true } : { url }),