@smartdoc/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# SmartDoc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Review your documents with your own AI. SmartDoc is a desktop app that shows your document (a PDF); your AI reads it, marks up the text and writes findings, and you decide on each one in the app. The AI then writes the next draft from your decisions.
+
+This package is SmartDoc's MCP server. AI apps start it, and it opens the SmartDoc app for them (downloading it from the [GitHub release](https://github.com/tw050x/smartdoc/releases) the first time).
+
+## Claude Code
+
+```sh
+claude mcp add --scope user smartdoc -- npx -y @smartdoc/mcp
+```
+
+Then start a new session and ask Claude to review your document.
+
+## Claude Desktop
+
+Download the bundle from the [website](https://tw050x.github.io/smartdoc/) and open it.
+
+## Requirements
+
+- macOS (Apple silicon or Intel). Windows is planned.
+- Node.js 18 or later.
+
+SmartDoc keeps your document and its drafts on your computer. Your agent reads the document through SmartDoc's tools, so what it reads goes wherever your agent sends it.

package/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// SmartDoc's MCP server, as AI apps start it: Claude Code through npx, Claude Desktop from
+// the .mcpb bundle. It opens the SmartDoc app (downloading it the first time) and passes
+// the AI's messages to it. Only MCP messages go to stdout; progress and errors go to stderr.
+import { runBridge } from './lib/bridge.js';
+import { ensureRunning, readToken } from './lib/launch.js';
+
+const log = (message) => process.stderr.write(`[smartdoc] ${message}\n`);
+
+await runBridge({
+  ensure: () => ensureRunning({ log }),
+  token: () => readToken(),
+  log,
+});

package/lib/bridge.js

@@ -0,0 +1,71 @@
+import readline from 'node:readline';
+import { mcpUrl } from './platform.js';
+
+// Carries MCP messages between an AI app, which talks to this launcher over stdio (one JSON-RPC
+// message per line), and the app's MCP server over HTTP. Messages wait until the app is
+// running. If the app goes away (say the user quits it), the next message opens it again.
+//
+// `ensure()` makes sure the app is running; `token()` reads its current token.
+export function runBridge({ input = process.stdin, output = process.stdout, env = process.env, ensure, token, log = () => {} }) {
+  let ready = null;
+  const whenReady = () => (ready ??= ensure().catch((error) => {
+    ready = null; // try again with the next message
+    throw error;
+  }));
+
+  const write = (message) => output.write(`${JSON.stringify(message)}\n`);
+  const fail = (id, message) => id !== undefined && write({ jsonrpc: '2.0', id, error: { code: -32000, message } });
+
+  async function post(line) {
+    const res = await fetch(mcpUrl(env), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: `Bearer ${token() ?? ''}` },
+      body: line,
+    });
+    return { status: res.status, text: (await res.text()).trim() };
+  }
+
+  async function forward(line, message) {
+    await whenReady();
+    let reply;
+    try {
+      reply = await post(line);
+    } catch {
+      // Nothing listening: the app was closed since. Open it again and retry once.
+      ready = null;
+      await whenReady();
+      reply = await post(line);
+    }
+    if (reply.status >= 400) {
+      let reason = `The app refused the request (HTTP ${reply.status}).`;
+      try {
+        reason = JSON.parse(reply.text).error ?? reason;
+      } catch {}
+      return fail(message.id, reason);
+    }
+    if (reply.text) output.write(`${reply.text}\n`);
+  }
+
+  const pending = new Set();
+  const lines = readline.createInterface({ input });
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    const job = forward(line, message).catch((error) => {
+      log(error.message);
+      fail(message.id, error.message);
+    });
+    pending.add(job);
+    job.finally(() => pending.delete(job));
+  });
+
+  // Start the app straight away, rather than waiting for the first message.
+  whenReady().catch((error) => log(error.message));
+
+  return new Promise((resolve) => lines.on('close', () => Promise.allSettled([...pending]).then(resolve)));
+}

package/lib/install.js

@@ -0,0 +1,109 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createWriteStream, existsSync } from 'node:fs';
+import { mkdir, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+import { APP_NAME, CHECKSUMS, VERSION, assetName, cacheDir, downloadBase } from './platform.js';
+
+// Fetches the app build matching this launcher's version from the GitHub release, checks it
+// against the release's checksums, and unpacks it into the cache, once per version. Two
+// launchers starting at the same time (say Claude Desktop and Claude Code) share one download:
+// the first takes a lock and the other waits for it to finish.
+
+const run = promisify(execFile);
+const LOCK_STALE_MS = 10 * 60 * 1000;
+const WAIT_STEP_MS = 500;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class UnsupportedPlatformError extends Error {}
+
+export function parseChecksums(text) {
+  const sums = new Map();
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.trim().match(/^([0-9a-f]{64})\s+\*?(.+)$/i);
+    if (match) sums.set(match[2].trim(), match[1].toLowerCase());
+  }
+  return sums;
+}
+
+// The installed app for this version, downloading it first if needed. Resolves to its path.
+export async function ensureInstalled({ env = process.env, log = () => {} } = {}) {
+  const asset = assetName();
+  if (!asset) throw new UnsupportedPlatformError(`${APP_NAME} isn’t available for ${process.platform} (${process.arch}) yet. It runs on macOS for now.`);
+  const root = cacheDir({ env });
+  const dir = path.join(root, VERSION);
+  const appPath = path.join(dir, `${APP_NAME}.app`);
+  if (existsSync(appPath)) return appPath;
+
+  await mkdir(root, { recursive: true });
+  const lock = `${dir}.lock`;
+  while (!(await takeLock(lock))) {
+    if (existsSync(appPath)) return appPath;
+    await sleep(WAIT_STEP_MS);
+  }
+  try {
+    if (existsSync(appPath)) return appPath;
+    const base = downloadBase({ env });
+    log(`Downloading ${APP_NAME} ${VERSION}…`);
+    const sums = parseChecksums(await (await get(`${base}/${CHECKSUMS}`)).text());
+    const expected = sums.get(asset);
+    if (!expected) throw new Error(`The release has no checksum for ${asset}.`);
+
+    const zip = `${dir}.download.zip`;
+    const actual = await download(`${base}/${asset}`, zip);
+    if (actual !== expected) {
+      await rm(zip, { force: true });
+      throw new Error(`The download of ${asset} didn’t match the release’s checksum, so it wasn’t used.`);
+    }
+
+    // ditto keeps the app's code signature, permissions and symlinks intact.
+    const unpacked = `${dir}.partial`;
+    await rm(unpacked, { recursive: true, force: true });
+    await mkdir(unpacked);
+    await run('ditto', ['-x', '-k', zip, unpacked]);
+    await rm(zip, { force: true });
+    if (!existsSync(path.join(unpacked, `${APP_NAME}.app`))) throw new Error(`${asset} doesn’t contain ${APP_NAME}.app.`);
+    await rename(unpacked, dir);
+    log(`Installed ${APP_NAME} ${VERSION}.`);
+    return appPath;
+  } finally {
+    await rm(lock, { recursive: true, force: true });
+  }
+}
+
+// A lock is a folder: creating it is atomic. One left behind by a launcher that died mid-download
+// is taken over once it's old enough.
+async function takeLock(lock) {
+  try {
+    await mkdir(lock);
+    return true;
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const { mtimeMs } = await stat(lock).catch(() => ({ mtimeMs: 0 }));
+    if (Date.now() - mtimeMs > LOCK_STALE_MS) await rm(lock, { recursive: true, force: true });
+    return false;
+  }
+}
+
+async function get(url) {
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`Couldn’t download ${url} (HTTP ${res.status}).`);
+  return res;
+}
+
+// Streams a download to a file, hashing it on the way. Resolves to its SHA-256.
+async function download(url, file) {
+  const res = await get(url);
+  const hash = createHash('sha256');
+  const tap = new Transform({
+    transform(chunk, _encoding, done) {
+      hash.update(chunk);
+      done(null, chunk);
+    },
+  });
+  await pipeline(Readable.fromWeb(res.body), tap, createWriteStream(file));
+  return hash.digest('hex');
+}

package/lib/launch.js

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { ensureInstalled } from './install.js';
+import { APP_NAME, mcpUrl, userDataDir } from './platform.js';
+
+// Makes sure the app is running with its MCP server up, opening it if not. A running app is
+// shared: every launcher connects to the same one, and it stays open when they disconnect.
+
+const START_TIMEOUT_MS = 90 * 1000;
+const POLL_MS = 400;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// The token the app's MCP server expects. It's kept in the app's data folder, so it's only
+// readable by the user (and only exists once the app has run).
+export function readToken({ env = process.env } = {}) {
+  try {
+    return readFileSync(path.join(userDataDir({ env }), 'mcp-token'), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+// 'up' when the server answers with this token; 'down' when nothing is listening; 'locked' when
+// something answers but refuses the token (it may not have been written yet).
+export async function probe({ env = process.env } = {}) {
+  const token = readToken({ env });
+  try {
+    // The server only takes POST, so a GET that gets past the token check answers 405.
+    const res = await fetch(mcpUrl(env), { headers: token ? { authorization: `Bearer ${token}` } : {} });
+    await res.body?.cancel();
+    return res.status === 405 ? 'up' : 'locked';
+  } catch {
+    return 'down';
+  }
+}
+
+export async function ensureRunning({ env = process.env, log = () => {} } = {}) {
+  if ((await probe({ env })) === 'up') return;
+  await openApp({ env, log });
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if ((await probe({ env })) === 'up') return;
+    await sleep(POLL_MS);
+  }
+  throw new Error(`${APP_NAME} didn’t start in time. Open it yourself, then try again.`);
+}
+
+async function openApp({ env, log }) {
+  const override = env.SMARTDOC_APP;
+  if (override) {
+    log(`Opening ${override}…`);
+    return start(appCommand(path.resolve(override)), env);
+  }
+  const appPath = await ensureInstalled({ env, log });
+  log(`Opening ${APP_NAME}…`);
+  return start(['open', [appPath]], env);
+}
+
+// How to start an app given by path: a macOS app bundle, a project folder (run with its own
+// Electron, as in development) or an executable.
+export function appCommand(target) {
+  if (target.endsWith('.app')) return ['open', [target]];
+  if (existsSync(target) && statSync(target).isDirectory()) {
+    const electron = path.join(target, 'node_modules', '.bin', process.platform === 'win32' ? 'electron.cmd' : 'electron');
+    return [electron, [target]];
+  }
+  return [target, []];
+}
+
+// Detached, so the app outlives this launcher and the AI app that started it.
+function start([command, args], env) {
+  const child = spawn(command, args, { detached: true, stdio: 'ignore', env });
+  child.on('error', () => {}); // reported as a timeout by ensureRunning
+  child.unref();
+}

package/lib/platform.js

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Where things are on this computer, and which build of the app it needs. Everything here can be
+// overridden with environment variables, which development and tests use to keep away from the
+// user's real app and data:
+//   SMARTDOC_APP        the app to open: a SmartDoc.app, an executable, or a project
+//                       folder (run with its own Electron), instead of the downloaded one
+//   SMARTDOC_USER_DATA  the app's data folder (passed on to a project-folder app)
+//   SMARTDOC_PORT       the port the app's MCP server listens on (likewise)
+//   SMARTDOC_CACHE      where downloaded builds are kept
+//   SMARTDOC_DOWNLOADS  the base URL builds are downloaded from (a release's download URL)
+
+export const APP_NAME = 'SmartDoc';
+export const REPOSITORY = 'tw050x/smartdoc';
+export const DEFAULT_PORT = 47815;
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+export const port = (env = process.env) => Number(env.SMARTDOC_PORT) || DEFAULT_PORT;
+export const mcpUrl = (env = process.env) => `http://127.0.0.1:${port(env)}/mcp`;
+
+// The folder Electron gives the app for its data (it holds the MCP server's token).
+export function userDataDir({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.SMARTDOC_USER_DATA) return path.resolve(env.SMARTDOC_USER_DATA);
+  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', APP_NAME);
+  if (platform === 'win32') return path.join(env.APPDATA ?? path.join(home, 'AppData', 'Roaming'), APP_NAME);
+  return path.join(env.XDG_CONFIG_HOME ?? path.join(home, '.config'), APP_NAME);
+}
+
+// Downloaded builds live here, one folder per version.
+export function cacheDir({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.SMARTDOC_CACHE) return path.resolve(env.SMARTDOC_CACHE);
+  if (platform === 'darwin') return path.join(home, 'Library', 'Caches', 'smartdoc');
+  if (platform === 'win32') return path.join(env.LOCALAPPDATA ?? path.join(home, 'AppData', 'Local'), 'smartdoc', 'Cache');
+  return path.join(env.XDG_CACHE_HOME ?? path.join(home, '.cache'), 'smartdoc');
+}
+
+// The release file holding the app for this computer, as named by the release build
+// (electron-builder's artifactName in the app's package.json). Null where there's no build yet.
+export function assetName({ version = VERSION, platform = process.platform, arch = process.arch } = {}) {
+  if (platform === 'darwin' && (arch === 'arm64' || arch === 'x64')) return `smartdoc-${version}-mac-${arch}.zip`;
+  return null;
+}
+
+export const downloadBase = ({ env = process.env, version = VERSION } = {}) =>
+  (env.SMARTDOC_DOWNLOADS ?? `https://github.com/${REPOSITORY}/releases/download/v${version}`).replace(/\/$/, '');
+
+export const CHECKSUMS = 'SHA256SUMS.txt';

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@smartdoc/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Review documents with your own AI. Opens the SmartDoc app and connects it to Claude Code, Claude Desktop and other MCP clients.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "smartdoc-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "lib/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tw050x/smartdoc.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://tw050x.github.io/smartdoc/",
+  "keywords": [
+    "mcp",
+    "document",
+    "review",
+    "pdf",
+    "claude"
+  ]
+}