jotview 0.4.1 → 0.5.1

package/README.md

@@ -29,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
@@ -89,7 +90,11 @@ it reads a jotbins link you share.
 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"] } } }
@@ -104,6 +109,19 @@ 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.
@@ -141,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
@@ -151,6 +178,24 @@ 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`.
+
+If a release run fails partway, fix the cause and finish it with
+`gh workflow run release.yml -f tag=vX.Y.Z` — finished steps are skipped.
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "jotview",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "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

@@ -3,6 +3,7 @@ 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";
@@ -20,7 +21,8 @@ Usage:
   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
@@ -28,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
@@ -48,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
@@ -60,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++) {
@@ -71,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": {
@@ -110,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)) {
@@ -245,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) {
@@ -285,8 +299,10 @@ async function runDecode(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;
@@ -296,7 +312,7 @@ async function runMcp(argv, io) {
     write: io.stdout,
     ctx: {
       version: io.version,
-      tools: [renderTool({ allowUpload: !opts.raw, baseUrl: opts.baseUrl }), readTool({})],
+      tools: [renderTool({ allowUpload: !opts.raw, baseUrl: opts.baseUrl, roots }), readTool({})],
     },
   });
   return 0;

package/src/codec.js

@@ -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" | "bad-link" | "cleaned-up"} 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 */

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/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
@@ -15,7 +17,8 @@ const DEFINITION = {
   name: "render_markdown",
   title: "Render markdown with jotbins",
   description:
-    "Turn markdown (GitHub-flavored, with ```mermaid diagrams) into a link that " +
+    "Turn markdown (GitHub-flavored, with ```mermaid diagrams, $math$ / $$math$$, " +
+    "> [!NOTE] callouts and :emoji: shortcodes) into a link that " +
     "renders it as a page on jotbins.com. Returns a ready-made markdown link to " +
     "show the user. Small documents live entirely in the link; larger ones are " +
     "uploaded to surl.jotbins.com for a short link that expires after 30 days " +
@@ -46,13 +49,40 @@ 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);
-  return linkText(match ? match[1] : "jotbins doc");
+  return linkText(match ? match[1] : fallback);
 }
 
 /** @param {string} text */
@@ -66,8 +96,13 @@ 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.";
@@ -110,17 +145,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 {
@@ -133,12 +182,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 =
-        `[${typeof args.title === "string" ? linkText(args.title) : 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

@@ -12,7 +12,8 @@ export const LEGACY_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-
 export const MODERN_VERSIONS = ["2026-07-28"];
 
 export const INSTRUCTIONS =
-  "Use render_markdown to share markdown — including Mermaid diagrams — as a " +
+  "Use render_markdown to share markdown — including Mermaid diagrams, $…$ " +
+  "math and > [!NOTE] / [!TIP] / [!WARNING] callouts — as a " +
   "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 " +