jotview 0.2.0 → 0.3.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 mcp [--raw]       run as an MCP server for AI agents
 
   --raw                   never shorten; always the full /d URL
   --short                 always shorten, even when small
@@ -69,6 +70,43 @@ never expire.
 If the shortener is unreachable or rate-limited, jotview prints the full link
 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.
+
+**Claude Code**
+
+```bash
+claude mcp add jotview -- npx -y jotview mcp
+```
+
+**Claude Desktop, Cursor, and other clients** — add to the MCP config:
+
+```json
+{ "mcpServers": { "jotview": { "command": "npx", "args": ["-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.
+
+**Uploads.** Every character of a link costs tokens, so MCP shortens sooner
+than the CLI: links over **500** characters go through `surl.jotbins.com`,
+which uploads the document (short links expire after 30 days unused unless
+`keep` is set). To forbid uploads entirely, start the server with `--raw`:
+
+```bash
+claude mcp add jotview -- npx -y jotview mcp --raw
+```
+
+Works with clients on any MCP revision from `2024-11-05` through `2026-07-28`.
+
 ## Output contract
 
 **stdout is the URL and nothing else.** Notices, warnings, and errors go to

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jotview",
-  "version": "0.2.0",
-  "description": "Turn a markdown file into a jotbins /d link. Zero dependencies.",
+  "version": "0.3.0",
+  "description": "Turn markdown into a jotbins /d link — a CLI and an MCP server. Zero dependencies.",
   "type": "module",
   "bin": {
     "jotview": "bin/jotview.js"
@@ -22,7 +22,10 @@
     "markdown",
     "jotbins",
     "cli",
-    "share"
+    "share",
+    "mcp",
+    "mcp-server",
+    "mermaid"
   ],
   "license": "MIT",
   "repository": {

package/src/cli.js

@@ -1,8 +1,9 @@
 import { readFileSync } from "node:fs";
-import { encode, JotviewError, MAX_DOC_BYTES } from "./codec.js";
-import {
-  shorten, shouldShorten, DEFAULT_BASE_URL, SHORTEN_THRESHOLD, SHORTENER_URL,
-} from "./shorten.js";
+import { JotviewError, MAX_DOC_BYTES } from "./codec.js";
+import { DEFAULT_BASE_URL, SHORTENER_URL } from "./shorten.js";
+import { mint } from "./mint.js";
+import { serve } from "./mcp-stdio.js";
+import { renderTool } from "./mcp-tool.js";
 import { openUrl, copyText } from "./platform.js";
 export { DEFAULT_BASE_URL };
 
@@ -15,6 +16,8 @@ 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 mcp [--raw]       run as an MCP server (stdio) for AI agents;
+                            --raw never uploads, --base-url works too
 
 Options:
   --raw                     never shorten; always the full /d URL
@@ -98,6 +101,30 @@ export function parseArgs(argv) {
   return opts;
 }
 
+/**
+ * Flags after `jotview mcp`. Only the ones that mean something to a server.
+ * @param {string[]} argv
+ * @returns {{raw: boolean, baseUrl: string}}
+ */
+export function parseMcpArgs(argv) {
+  const opts = { raw: false, baseUrl: DEFAULT_BASE_URL };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--raw") {
+      opts.raw = true;
+    } else if (arg === "--base-url") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("-") || !/^https?:\/\//.test(value)) {
+        throw new JotviewError("usage", "--base-url needs an absolute http:// or https:// URL");
+      }
+      opts.baseUrl = value.replace(/\/+$/, "");
+    } else {
+      throw new JotviewError("usage", `jotview mcp does not take ${arg}`);
+    }
+  }
+  return opts;
+}
+
 /** @param {import("node:stream").Readable} stdin */
 async function readStdin(stdin) {
   /** @type {Buffer[]} */
@@ -165,6 +192,8 @@ function applySideEffects(url, opts, io) {
  * @returns {Promise<number>} exit code
  */
 export async function run(argv, io) {
+  if (argv[0] === "mcp") return runMcp(argv.slice(1), io);
+
   /** @type {Options} */
   let opts;
   try {
@@ -182,29 +211,23 @@ export async function run(argv, io) {
 
   try {
     const md = await readInput(opts, io);
-    if (md.trim() === "") throw new JotviewError("empty", "input is empty");
-    const rawUrl = `${opts.baseUrl}/d#${encode(md)}`;
-
-    if (!shouldShorten(rawUrl, opts)) {
-      // Over the threshold, but the host isn't the shortenable default —
-      // don't nag about it on documents that were never going to need it.
-      if (opts.baseUrl !== DEFAULT_BASE_URL && rawUrl.length > SHORTEN_THRESHOLD) {
-        io.stderr(
-          `note: shortening skipped — only ${DEFAULT_BASE_URL} links can be ` +
-            "shortened. using the full link.\n",
-        );
-      }
-      io.stdout(`${rawUrl}\n`);
-      applySideEffects(rawUrl, opts, io);
-      return 0;
-    }
+    const minted = await mint(md, {
+      baseUrl: opts.baseUrl,
+      shorten: opts.raw ? "never" : opts.short ? "always" : "auto",
+      keep: opts.keep,
+    });
+    const printed = minted.url;
 
-    const result = await shorten(rawUrl, { permanent: opts.keep });
-    let printed = rawUrl;
-    if (result.ok) {
-      printed = result.short;
+    if (minted.skipped === "custom-base") {
+      // Only reported when the link was over the threshold — documents that
+      // were never going to need shortening don't get nagged about it.
       io.stderr(
-        `note: uploaded to jotbins to shorten (${rawUrl.length} → ` +
+        `note: shortening skipped — only ${DEFAULT_BASE_URL} links can be ` +
+          "shortened. using the full link.\n",
+      );
+    } else if (minted.shortened) {
+      io.stderr(
+        `note: uploaded to jotbins to shorten (${minted.rawUrl.length} → ` +
           `${printed.length} chars). use --raw to keep it local.\n`,
       );
       io.stderr(
@@ -212,9 +235,9 @@ export async function run(argv, io) {
           ? "note: short link kept forever.\n"
           : "note: short link expires after 30 days unused. use --keep to keep it forever.\n",
       );
-    } else {
+    } else if (minted.failure) {
       io.stderr(
-        `note: upload to the shortener failed (${result.reason}); using the full ` +
+        `note: upload to the shortener failed (${minted.failure}); using the full ` +
           `link. the document may still have reached ${SHORTENER_HOST}.\n`,
       );
     }
@@ -226,3 +249,29 @@ export async function run(argv, io) {
     return 1;
   }
 }
+
+/**
+ * `jotview mcp`: stdout belongs to the protocol from here on, so usage
+ * errors go to stderr and nothing else is ever printed.
+ * @param {string[]} argv
+ * @param {Parameters<typeof run>[1]} io
+ * @returns {Promise<number>}
+ */
+async function runMcp(argv, io) {
+  let opts;
+  try {
+    opts = parseMcpArgs(argv);
+  } catch (err) {
+    io.stderr(`jotview: ${/** @type {Error} */ (err).message}\n\n${HELP}`);
+    return 2;
+  }
+  await serve({
+    input: io.stdin,
+    write: io.stdout,
+    ctx: {
+      version: io.version,
+      tools: [renderTool({ allowUpload: !opts.raw, baseUrl: opts.baseUrl })],
+    },
+  });
+  return 0;
+}

package/src/mcp-stdio.js

@@ -0,0 +1,39 @@
+import { createInterface } from "node:readline";
+import { handleMessage, parseError } from "./mcp.js";
+
+/**
+ * Serve MCP over stdio: one JSON-RPC message per line in, one per line out.
+ * Requests are handled concurrently — each response carries its own id.
+ * Resolves once the client closes stdin and every pending reply is written.
+ *
+ * @param {{
+ *   input: import("node:stream").Readable,
+ *   write: (s: string) => void,
+ *   ctx: import("./mcp.js").Context,
+ * }} opts
+ */
+export async function serve({ input, write, ctx }) {
+  /** @param {object|null} res */
+  const send = (res) => {
+    // JSON.stringify never emits a raw newline, so every message stays one line.
+    if (res) write(`${JSON.stringify(res)}\n`);
+  };
+
+  /** @type {Promise<void>[]} */
+  const pending = [];
+  // readline reassembles messages split across chunks and splits chunks that
+  // carry several messages.
+  for await (const raw of createInterface({ input, crlfDelay: Infinity })) {
+    const text = raw.trim();
+    if (text === "") continue;
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      send(parseError());
+      continue;
+    }
+    pending.push(handleMessage(msg, ctx).then(send));
+  }
+  await Promise.all(pending);
+}

package/src/mcp-tool.js

@@ -0,0 +1,138 @@
+import { mint } from "./mint.js";
+import { shorten, DEFAULT_BASE_URL, SHORTENER_URL } from "./shorten.js";
+import { JotviewError } from "./codec.js";
+
+/** 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
+ *  sooner than the CLI's 2000. */
+export const MCP_SHORTEN_THRESHOLD = 500;
+
+const SHORTENER_HOST = new URL(SHORTENER_URL).host;
+const TITLE_MAX = 80;
+const MODES = ["auto", "always", "never"];
+
+const DEFINITION = {
+  name: "render_markdown",
+  title: "Render markdown with jotbins",
+  description:
+    "Turn markdown (GitHub-flavored, with ```mermaid diagrams) 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 " +
+    "unused unless keep is true.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      content: { type: "string", description: "The markdown to render." },
+      keep: {
+        type: "boolean",
+        description: "Make a shortened link permanent instead of expiring after 30 days unused.",
+      },
+      shorten: {
+        type: "string",
+        enum: MODES,
+        description:
+          'Default "auto" shortens long links. "never" keeps the document out of ' +
+          'any upload (long link); "always" shortens even small ones.',
+      },
+    },
+    required: ["content"],
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: true, openWorldHint: true },
+};
+
+/**
+ * The first markdown heading, as safe link text.
+ * @param {string} md
+ */
+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}`);
+}
+
+/** @param {string} text */
+const toolError = (text) => ({ content: [{ type: "text", text }], isError: true });
+
+/**
+ * @param {Record<string, unknown>} args
+ * @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.keep !== undefined && typeof args.keep !== "boolean") return "keep must be true or false.";
+  if (args.shorten !== undefined && !MODES.includes(/** @type {string} */ (args.shorten))) {
+    return 'shorten must be "auto", "always" or "never".';
+  }
+  return null;
+}
+
+/**
+ * @param {import("./mint.js").MintResult} r
+ * @param {boolean} keepAsked
+ */
+function describe(r, keepAsked) {
+  if (r.shortened) {
+    return r.permanent
+      ? `Short link: the document was uploaded to ${SHORTENER_HOST} and the link is permanent.`
+      : `Short link: the document was uploaded to ${SHORTENER_HOST}. It is deleted after 30 days ` +
+          "without a visit; call again with keep: true for a permanent link.";
+  }
+  const notes = [];
+  if (r.skipped === "uploads-off") {
+    notes.push("Full link: uploads are turned off for this server, so it was not shortened. Nothing was uploaded.");
+  } else if (r.skipped === "custom-base") {
+    notes.push(`Full link: only ${DEFAULT_BASE_URL} links can be shortened. Nothing was uploaded.`);
+  } else if (r.failure) {
+    notes.push(
+      `Full link: shortening failed (${r.failure}). The document may still have reached ${SHORTENER_HOST}.`,
+    );
+  } else {
+    notes.push("Full link: the document lives in the link itself; nothing was uploaded and it never expires.");
+  }
+  if (keepAsked) notes.push("keep has no effect here: full links never expire.");
+  return notes.join(" ");
+}
+
+/**
+ * @param {{
+ *   allowUpload?: boolean,
+ *   baseUrl?: string,
+ *   shortenImpl?: typeof shorten,
+ * }} opts  `allowUpload: false` is `jotview mcp --raw`
+ * @returns {import("./mcp.js").Tool}
+ */
+export function renderTool(opts) {
+  return {
+    definition: DEFINITION,
+    async call(args) {
+      const problem = validate(args);
+      if (problem) return toolError(problem);
+
+      const md = /** @type {string} */ (args.content);
+      const keep = args.keep === true;
+      let r;
+      try {
+        r = await mint(md, {
+          baseUrl: opts.baseUrl,
+          shorten: /** @type {import("./mint.js").ShortenMode} */ (args.shorten ?? "auto"),
+          keep,
+          allowUpload: opts.allowUpload ?? true,
+          threshold: MCP_SHORTEN_THRESHOLD,
+          shortenImpl: opts.shortenImpl ?? shorten,
+        });
+      } catch (err) {
+        if (err instanceof JotviewError) return toolError(`${err.message}. Shorten or split the document.`);
+        throw err;
+      }
+
+      const text =
+        `[${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

@@ -0,0 +1,159 @@
+/**
+ * MCP message handling — pure, no I/O. `mcp-stdio.js` owns the transport.
+ *
+ * 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
+ * both eras are served from the same handlers and only the envelope differs.
+ */
+
+/** Newest first: `initialize` answers with the first one the client lacks. */
+export const LEGACY_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export const MODERN_VERSIONS = ["2026-07-28"];
+
+export const INSTRUCTIONS =
+  "Use render_markdown to share markdown — including Mermaid diagrams — 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 " +
+  'unless the user asked to keep them local (shorten: "never").';
+
+const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+const UNSUPPORTED_VERSION = -32022;
+
+/**
+ * @typedef {object} Tool
+ * @property {{name: string} & Record<string, unknown>} definition  as listed by tools/list
+ * @property {(args: Record<string, unknown>) => Promise<object>} call  returns a CallToolResult
+ */
+
+/**
+ * @typedef {object} Context
+ * @property {string} version  jotview's own version, reported as serverInfo
+ * @property {Tool[]} tools
+ */
+
+/**
+ * @param {string|number|null} id
+ * @param {number} code
+ * @param {string} message
+ * @param {unknown} [data]
+ */
+export function errorResponse(id, code, message, data) {
+  return { jsonrpc: "2.0", id, error: { code, message, ...(data !== undefined && { data }) } };
+}
+
+/** For the transport: a line that wasn't JSON at all. */
+export const parseError = () => errorResponse(null, PARSE_ERROR, "Parse error");
+
+/** @param {Context} ctx */
+const serverInfo = (ctx) => ({ name: "jotview", version: ctx.version });
+
+/**
+ * Handle one parsed JSON-RPC message.
+ * @param {unknown} msg
+ * @param {Context} ctx
+ * @returns {Promise<object|null>} the response, or null when none is owed
+ */
+export async function handleMessage(msg, ctx) {
+  if (Array.isArray(msg)) {
+    return errorResponse(null, INVALID_REQUEST, "Batches are not supported");
+  }
+  if (msg === null || typeof msg !== "object") {
+    return errorResponse(null, INVALID_REQUEST, "Invalid request");
+  }
+
+  const m = /** @type {Record<string, any>} */ (msg);
+  const hasId = "id" in m;
+  const id = hasId ? m.id : null;
+
+  // A response to something we sent. jotview never sends requests, so there
+  // is nothing to match it against.
+  if (typeof m.method !== "string" && hasId && ("result" in m || "error" in m)) return null;
+  if (m.jsonrpc !== "2.0" || typeof m.method !== "string") {
+    return hasId ? errorResponse(id, INVALID_REQUEST, "Invalid request") : null;
+  }
+  if (!hasId) return null; // notifications never get a reply
+
+  const params = m.params && typeof m.params === "object" ? m.params : {};
+  const meta = params._meta && typeof params._meta === "object" ? params._meta : {};
+  const modern = META_VERSION in meta;
+
+  if (modern) {
+    const requested = meta[META_VERSION];
+    if (!MODERN_VERSIONS.includes(requested)) {
+      return errorResponse(id, UNSUPPORTED_VERSION, "Unsupported protocol version", {
+        supported: MODERN_VERSIONS,
+        requested,
+      });
+    }
+    if (m.method !== "server/discover" && !(META_CAPABILITIES in meta)) {
+      return errorResponse(id, INVALID_PARAMS, `Missing _meta["${META_CAPABILITIES}"]`);
+    }
+  }
+
+  /** @param {object} result */
+  const ok = (result) => ({
+    jsonrpc: "2.0",
+    id,
+    result: modern ? { resultType: "complete", ...result } : result,
+  });
+
+  switch (m.method) {
+    case "initialize": {
+      const asked = params.protocolVersion;
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: LEGACY_VERSIONS.includes(asked) ? asked : LEGACY_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: serverInfo(ctx),
+          instructions: INSTRUCTIONS,
+        },
+      };
+    }
+
+    case "server/discover":
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          resultType: "complete",
+          supportedVersions: MODERN_VERSIONS,
+          capabilities: { tools: {} },
+          _meta: { "io.modelcontextprotocol/serverInfo": serverInfo(ctx) },
+          instructions: INSTRUCTIONS,
+          ttlMs: 60 * 60 * 1000,
+          cacheScope: "public",
+        },
+      };
+
+    case "ping":
+      return ok({});
+
+    case "tools/list":
+      return ok({ tools: ctx.tools.map((t) => t.definition) });
+
+    case "tools/call": {
+      const tool = ctx.tools.find((t) => t.definition.name === params.name);
+      if (!tool) return errorResponse(id, INVALID_PARAMS, `Unknown tool: ${params.name}`);
+      const args = params.arguments && typeof params.arguments === "object" ? params.arguments : {};
+      try {
+        return ok(await tool.call(args));
+      } catch (err) {
+        return errorResponse(id, INTERNAL_ERROR, /** @type {Error} */ (err).message);
+      }
+    }
+
+    default:
+      return errorResponse(id, METHOD_NOT_FOUND, `Method not found: ${m.method}`);
+  }
+}

package/src/mint.js

@@ -0,0 +1,62 @@
+import { encode, JotviewError } from "./codec.js";
+import { shorten, DEFAULT_BASE_URL, SHORTEN_THRESHOLD } from "./shorten.js";
+
+/** @typedef {"auto" | "always" | "never"} ShortenMode */
+
+/**
+ * @typedef {object} MintResult
+ * @property {string} url          what to hand the user — short when shortened
+ * @property {string} rawUrl       the full /d link, always
+ * @property {boolean} shortened
+ * @property {boolean} permanent   only true for a shortened link made with `keep`
+ * @property {string|null} failure the shortener's error, when it was tried and failed
+ * @property {"custom-base"|"uploads-off"|null} skipped
+ *   why a link that would have been shortened was not
+ */
+
+/**
+ * Turn markdown into a jotbins link, shortening it through surl when the
+ * mode and size call for it. Shared by the CLI and the MCP server so both
+ * make the same decision; each words the outcome for its own audience.
+ *
+ * @param {string} md
+ * @param {{
+ *   baseUrl?: string,
+ *   shorten?: ShortenMode,
+ *   keep?: boolean,
+ *   allowUpload?: boolean,
+ *   threshold?: number,
+ *   shortenImpl?: typeof shorten,
+ * }} [opts]
+ * @returns {Promise<MintResult>}
+ */
+export async function mint(md, opts = {}) {
+  const {
+    baseUrl = DEFAULT_BASE_URL,
+    shorten: mode = "auto",
+    keep = false,
+    allowUpload = true,
+    threshold = SHORTEN_THRESHOLD,
+    shortenImpl = shorten,
+  } = opts;
+
+  if (md.trim() === "") throw new JotviewError("empty", "input is empty");
+  const rawUrl = `${baseUrl}/d#${encode(md)}`;
+
+  /** @type {MintResult} */
+  const result = {
+    url: rawUrl, rawUrl, shortened: false, permanent: false, failure: null, skipped: null,
+  };
+
+  const wanted = mode === "always" || (mode === "auto" && rawUrl.length > threshold);
+  if (!wanted) return result;
+
+  // surl's allowlist accepts only jotbins.com hosts, so a custom base URL can
+  // never be shortened. Skip rather than fire a request guaranteed to 400.
+  if (baseUrl !== DEFAULT_BASE_URL) return { ...result, skipped: "custom-base" };
+  if (!allowUpload) return { ...result, skipped: "uploads-off" };
+
+  const outcome = await shortenImpl(rawUrl, { permanent: keep });
+  if (!outcome.ok) return { ...result, failure: outcome.reason };
+  return { ...result, url: outcome.short, shortened: true, permanent: keep };
+}