jotview 0.4.0 → 0.5.0

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
@@ -28,6 +29,7 @@ jotview mcp [--raw]       run as an MCP server for AI agents
   --keep                  make a shortened link permanent
   --open                  open the link in your browser
   --copy                  copy the link to your clipboard
+  --json                  print the result as one JSON line (see below)
   --base-url <url>        override https://jotbins.com
   -h, --help
   -v, --version
@@ -40,8 +42,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 +79,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**
 
@@ -82,7 +90,11 @@ diagram — and gets back a jotbins link to hand you.
 claude mcp add jotview -- npx -y jotview mcp
 ```
 
-**Claude Desktop, Cursor, and other clients** — add to the MCP config:
+**Claude Desktop** — download `jotview.mcpb` from the
+[latest release](https://github.com/jotbins/jotview/releases/latest) and
+double-click it. Optionally pick a docs folder it may read files from.
+
+**Cursor and other clients** — add to the MCP config:
 
 ```json
 { "mcpServers": { "jotview": { "command": "npx", "args": ["-y", "jotview", "mcp"] } } }
@@ -90,11 +102,29 @@ 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.
+
+**Rendering files.** The local server can also take a `path` instead of
+`content`, so the AI doesn't have to paste a whole file into the tool call.
+It reads only `.md`, `.markdown`, `.mdx` and `.txt` files, and only inside
+the folder the server runs in (Claude Code starts it in your project) or a
+folder you allow with `--allow-dir`:
+
+```bash
+claude mcp add -s user jotview -- npx -y jotview mcp --allow-dir ~/notes
+```
+
+If the server runs in `/` or your home folder and no `--allow-dir` is given,
+`path` is switched off. The remote server never reads files.
+
+**`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`,
@@ -129,6 +159,15 @@ The Worker lives in [`worker/`](worker/) and deploys with
 **stdout is the URL and nothing else.** Notices, warnings, and errors go to
 stderr, so `$(jotview x.md)` and `jotview x.md | pbcopy` stay clean.
 
+With `--json`, stdout is one JSON line instead, for scripts and CI:
+
+```json
+{"url":"https://surl.jotbins.com/abc123","rawUrl":"https://jotbins.com/d#z:…","shortened":true,"permanent":false,"failure":null}
+```
+
+`failure` is the shortener's error when shortening was tried and failed
+(`url` is then the full link).
+
 Exit codes: `0` success, `1` runtime error, `2` usage error.
 
 ## Limits
@@ -139,6 +178,21 @@ Input is capped at 1 MB, matching what the `/d` renderer will open.
 
 Node 18 or newer.
 
+## Releasing
+
+Releases run from GitHub Actions. On an up-to-date `main`:
+
+```bash
+npm version minor
+git push --follow-tags
+```
+
+`npm version` also updates `manifest.json` and `server.json`. The `v*` tag
+then tests, publishes to npm (trusted publishing, with provenance), attaches
+`jotview.mcpb` to a GitHub release, and updates the MCP Registry entry. Move
+the `Unreleased` notes in `CHANGELOG.md` under the new version first (commit that before `npm version`). The
+Worker deploys separately: `cd worker && npx wrangler deploy`.
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "jotview",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Turn markdown into a jotbins /d link — a CLI and an MCP server. Zero dependencies.",
+  "mcpName": "io.github.jotbins/jotview",
   "type": "module",
   "bin": {
     "jotview": "bin/jotview.js"
@@ -16,7 +17,9 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "version": "node scripts/sync-version.js && git add manifest.json server.json",
+    "bundle": "npx -y @anthropic-ai/mcpb pack . jotview.mcpb"
   },
   "keywords": [
     "markdown",

package/src/cli.js

@@ -2,8 +2,11 @@ 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 { allowedRoots } from "./files.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,8 +19,10 @@ 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
+                            --raw never uploads, --base-url works too,
+                            --allow-dir <dir> lets it read files there
 
 Options:
   --raw                     never shorten; always the full /d URL
@@ -25,6 +30,7 @@ Options:
   --keep                    make a shortened link permanent
   --open                    open the link in your browser
   --copy                    copy the link to your clipboard
+  --json                    print {url, rawUrl, shortened, permanent, failure}
   --base-url <url>          override ${DEFAULT_BASE_URL}
   -h, --help                show this help
   -v, --version             show the version
@@ -45,6 +51,7 @@ saved from the link's waiting page. Full /d links never expire.
  * @property {boolean} keep
  * @property {boolean} open
  * @property {boolean} copy
+ * @property {boolean} json
  * @property {string} baseUrl
  * @property {boolean} help
  * @property {boolean} version
@@ -57,7 +64,7 @@ saved from the link's waiting page. Full /d links never expire.
 export function parseArgs(argv) {
   /** @type {Options} */
   const opts = {
-    file: null, raw: false, short: false, keep: false, open: false, copy: false,
+    file: null, raw: false, short: false, keep: false, open: false, copy: false, json: false,
     baseUrl: DEFAULT_BASE_URL, help: false, version: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -68,6 +75,7 @@ export function parseArgs(argv) {
       case "--keep": opts.keep = true; break;
       case "--open": opts.open = true; break;
       case "--copy": opts.copy = true; break;
+      case "--json": opts.json = true; break;
       case "-h": case "--help": opts.help = true; break;
       case "-v": case "--version": opts.version = true; break;
       case "--base-url": {
@@ -107,11 +115,15 @@ export function parseArgs(argv) {
  * @returns {{raw: boolean, baseUrl: string}}
  */
 export function parseMcpArgs(argv) {
-  const opts = { raw: false, baseUrl: DEFAULT_BASE_URL };
+  const opts = { raw: false, baseUrl: DEFAULT_BASE_URL, allowDirs: /** @type {string[]} */ ([]) };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--raw") {
       opts.raw = true;
+    } else if (arg === "--allow-dir") {
+      const value = argv[++i];
+      if (value === undefined) throw new JotviewError("usage", "--allow-dir needs a folder");
+      opts.allowDirs.push(value);
     } else if (arg === "--base-url") {
       const value = argv[++i];
       if (value === undefined || value.startsWith("-") || !/^https?:\/\//.test(value)) {
@@ -193,6 +205,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;
@@ -241,7 +254,12 @@ export async function run(argv, io) {
           `link. the document may still have reached ${SHORTENER_HOST}.\n`,
       );
     }
-    io.stdout(`${printed}\n`);
+    if (opts.json) {
+      const { url, rawUrl, shortened, permanent, failure } = minted;
+      io.stdout(`${JSON.stringify({ url, rawUrl, shortened, permanent, failure })}\n`);
+    } else {
+      io.stdout(`${printed}\n`);
+    }
     applySideEffects(printed, opts, io);
     return 0;
   } catch (err) {
@@ -250,6 +268,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.
@@ -259,8 +299,10 @@ export async function run(argv, io) {
  */
 async function runMcp(argv, io) {
   let opts;
+  let roots;
   try {
     opts = parseMcpArgs(argv);
+    roots = allowedRoots({ cwd: process.cwd(), extra: opts.allowDirs });
   } catch (err) {
     io.stderr(`jotview: ${/** @type {Error} */ (err).message}\n\n${HELP}`);
     return 2;
@@ -270,7 +312,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, roots }), 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" | "not-allowed"} 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/files.js

@@ -0,0 +1,87 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { extname, isAbsolute, parse, resolve, sep } from "node:path";
+import { JotviewError, MAX_DOC_BYTES } from "./codec.js";
+
+/** The only files the MCP `path` input reads: a prompt-injected model must
+ *  not be able to render (and upload) keys, .env files and the like. */
+export const READABLE_EXTENSIONS = [".md", ".markdown", ".mdx", ".txt"];
+
+/** @param {string} p */
+const isFilesystemRoot = (p) => parse(p).root === p;
+
+/** @param {string} dir */
+function realDir(dir) {
+  try {
+    const real = realpathSync(dir);
+    if (statSync(real).isDirectory()) return real;
+  } catch {
+    // fall through
+  }
+  throw new JotviewError("usage", `--allow-dir: not a folder: ${dir}`);
+}
+
+/**
+ * Folders the MCP server may read from: its working folder (Claude Code
+ * starts it in the project) unless that is `/` or the home folder, plus any
+ * `--allow-dir`. Blank values and unfilled `${…}` placeholders (an unset
+ * Desktop bundle setting) are ignored.
+ *
+ * @param {{cwd: string, extra?: string[], home?: string}} opts
+ * @returns {string[]} real paths, deduplicated
+ */
+export function allowedRoots({ cwd, extra = [], home = homedir() }) {
+  const roots = [];
+  const realCwd = realpathSync(cwd);
+  let realHome = home;
+  try { realHome = realpathSync(home); } catch { /* keep as given */ }
+  if (!isFilesystemRoot(realCwd) && realCwd !== realHome) roots.push(realCwd);
+  for (const dir of extra) {
+    if (dir.trim() === "" || dir.startsWith("${")) continue;
+    roots.push(realDir(resolve(cwd, dir)));
+  }
+  return [...new Set(roots)];
+}
+
+/** @param {string} p */
+const readable = (p) => READABLE_EXTENSIONS.includes(extname(p).toLowerCase());
+
+/**
+ * Read a markdown or text file inside one of `roots`. Relative paths resolve
+ * against the first root. Symlinks are resolved before the checks.
+ *
+ * @param {string} path
+ * @param {string[]} roots  from allowedRoots
+ * @returns {string}
+ */
+export function readAllowedFile(path, roots) {
+  if (roots.length === 0) {
+    throw new JotviewError("not-allowed", "file access is off for this server; pass the markdown as content");
+  }
+  const target = isAbsolute(path) ? path : resolve(roots[0], path);
+  const allowedTypes = READABLE_EXTENSIONS.join(" ");
+  if (!readable(target)) {
+    throw new JotviewError("not-allowed", `only ${allowedTypes} files can be read`);
+  }
+
+  let real;
+  try {
+    real = realpathSync(target);
+  } catch {
+    throw new JotviewError("not-found", `no such file: ${path}`);
+  }
+  const inside = roots.some((r) => real.startsWith(r.endsWith(sep) ? r : r + sep));
+  if (!inside) {
+    throw new JotviewError("not-allowed", `${path} is outside the folders this server may read (${roots.join(", ")})`);
+  }
+  if (!readable(real)) {
+    throw new JotviewError("not-allowed", `only ${allowedTypes} files can be read`);
+  }
+
+  const stat = statSync(real);
+  if (!stat.isFile()) throw new JotviewError("not-found", `not a file: ${path}`);
+  if (stat.size > MAX_DOC_BYTES) {
+    throw new JotviewError("too-large", `${path} is ${stat.size} bytes; the limit is ${MAX_DOC_BYTES}`);
+  }
+  return readFileSync(real, "utf8");
+}

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

@@ -1,4 +1,5 @@
 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;
@@ -22,18 +23,6 @@ const json = (body, status = 200) =>
 const plain = (text, status, headers = {}) =>
   new Response(text, { status, headers: { ...CORS, "content-type": "text/plain; charset=utf-8", ...headers } });
 
-/** @param {string} endpoint */
-const landing = (endpoint) => `jotview — an MCP server that turns markdown into rendered jotbins links.
-
-MCP endpoint (Streamable HTTP, no sign-in):
-  ${endpoint}
-
-claude.ai: Settings → Connectors → Add custom connector → paste the URL above.
-Claude Code: claude mcp add -s user --transport http jotview ${endpoint}
-
-Source: https://github.com/jotbins/jotview
-`;
-
 /**
  * Serve MCP over Streamable HTTP. Every request gets exactly one JSON reply —
  * no SSE stream and no sessions, since the only tool answers immediately.
@@ -48,7 +37,7 @@ export async function handleHttp(request, ctx) {
 
   if (url.pathname === "/") {
     if (request.method !== "GET") return plain("Method not allowed\n", 405, { allow: "GET" });
-    return plain(landing(`${url.origin}/mcp`), 200);
+    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" });

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

@@ -1,6 +1,8 @@
 import { mint } from "./mint.js";
 import { shorten, DEFAULT_BASE_URL, SHORTENER_URL } from "./shorten.js";
 import { JotviewError } from "./codec.js";
+import { readAllowedFile, READABLE_EXTENSIONS } from "./files.js";
+import { basename } from "node:path";
 
 /** Every character of a /d link costs the user tokens twice — once handed
  *  back to the model, once written into its reply — so MCP shortens much
@@ -28,6 +30,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,
@@ -42,16 +48,45 @@ const DEFINITION = {
   annotations: { readOnlyHint: true, openWorldHint: true },
 };
 
+/**
+ * The definition, plus a `path` input when the server may read files.
+ * @param {string[]} roots
+ */
+function definitionFor(roots) {
+  if (roots.length === 0) return DEFINITION;
+  const { required: _required, ...schema } = DEFINITION.inputSchema;
+  return {
+    ...DEFINITION,
+    inputSchema: {
+      ...schema,
+      properties: {
+        ...schema.properties,
+        content: { type: "string", description: "The markdown to render. Pass this or path." },
+        path: {
+          type: "string",
+          description:
+            `A ${READABLE_EXTENSIONS.join("/")} file to render instead of content — saves ` +
+            `sending the text. Relative to ${roots[0]}; only files under ` +
+            `${roots.join(", ")} can be read.`,
+        },
+      },
+    },
+  };
+}
+
 /**
  * The first markdown heading, as safe link text.
  * @param {string} md
+ * @param {string} [fallback]  used when there is no heading
  */
-export function docTitle(md) {
+export function docTitle(md, fallback = "jotbins doc") {
   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] : fallback);
 }
 
+/** @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 });
 
@@ -60,9 +95,17 @@ const toolError = (text) => ({ content: [{ type: "text", text }], isError: true
  * @returns {string|null} what's wrong, phrased for the model to fix
  */
 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.path !== undefined) {
+    if (args.content !== undefined) return "pass content or path, not both.";
+    if (typeof args.path !== "string" || args.path.trim() === "") return "path must be a file path.";
+  } else {
+    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".';
   }
@@ -101,17 +144,31 @@ function describe(r, keepAsked) {
  *   allowUpload?: boolean,
  *   baseUrl?: string,
  *   shortenImpl?: typeof shorten,
- * }} opts  `allowUpload: false` is `jotview mcp --raw`
+ *   roots?: string[],
+ * }} opts  `allowUpload: false` is `jotview mcp --raw`; `roots` (from
+ *   allowedRoots) enables the `path` input
  * @returns {import("./mcp.js").Tool}
  */
 export function renderTool(opts) {
+  const roots = opts.roots ?? [];
   return {
-    definition: DEFINITION,
+    definition: definitionFor(roots),
     async call(args) {
       const problem = validate(args);
       if (problem) return toolError(problem);
 
-      const md = /** @type {string} */ (args.content);
+      const path = /** @type {string|undefined} */ (args.path);
+      let md;
+      if (path === undefined) {
+        md = /** @type {string} */ (args.content);
+      } else {
+        try {
+          md = readAllowedFile(path, roots);
+        } catch (err) {
+          if (err instanceof JotviewError) return toolError(`Can't read that file: ${err.message}.`);
+          throw err;
+        }
+      }
       const keep = args.keep === true;
       let r;
       try {
@@ -124,12 +181,14 @@ export function renderTool(opts) {
           shortenImpl: opts.shortenImpl ?? shorten,
         });
       } catch (err) {
-        if (err instanceof JotviewError) return toolError(`${err.message}. Shorten or split the document.`);
+        if (err instanceof JotviewError) {
+          return toolError(err.code === "too-large" ? `${err.message}. Shorten or split the document.` : `${err.message}.`);
+        }
         throw err;
       }
 
       const text =
-        `[${docTitle(md)}](${r.url})\n\n` +
+        `[${typeof args.title === "string" ? linkText(args.title) : docTitle(md, path && basename(path))}](${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}`);
+}