easymd-cli 0.1.0 → 0.1.2

package/README.md

@@ -69,12 +69,24 @@ with `EASYMD_URL=https://your-easymd.example.com`.
 
 easymd ships an MCP server so AI agents edit the **same live documents** humans do — changes sync in real time and persist to Supabase.
 
+The easiest way is the CLI's bundled MCP server. It authenticates with your `easymd login` token (no API keys to paste) and works with any agent:
+
 ```bash
-cd web
-npm run mcp          # stdio MCP server (needs the collab server running + Supabase env)
+npm i -g easymd-cli
+easymd login
+easymd mcp-install        # registers it with Cursor + Claude Desktop
+# Claude Code:  claude mcp add easymd -- easymd mcp
 ```
 
-Tools: `list_documents`, `read_document`, `create_document`, `update_document`, `append_to_document`. Docs an agent creates show up in the app's document switcher for everyone; edits an agent makes appear live in any open editor. Register it with Cursor/Claude via `.cursor/mcp.json`.
+Or use [`add-mcp`](https://github.com/neondatabase-labs/add-mcp) to register it across **all** detected agents (Cursor, Claude Desktop, VS Code, …) in one command:
+
+```bash
+npx add-mcp@latest --command easymd --args "mcp" --name easymd
+```
+
+Tools: `list_documents`, `read_document`, `create_document`, `update_document`, `append_to_document`. Docs an agent creates show up in your dashboard; edits an agent makes appear live in any open editor.
+
+(The repo also has a server-side MCP at `web/scripts/mcp-server.mjs` — `npm run mcp` — which uses the service-role key directly; prefer the CLI version for end users.)
 
 ## Why
 

package/bin/easymd.js

@@ -3,11 +3,12 @@
 import { resolve } from 'path';
 import { access } from 'fs/promises';
 import openBrowser from 'open';
-import { startServer } from '../src/server.js';
 import { login, logout, whoami } from '../src/cli/auth.js';
 import { syncDir, watchDir } from '../src/cli/sync.js';
 import { autoOn, autoOff, autoStatus } from '../src/cli/auto.js';
 import { getCredentials } from '../src/cli/config.js';
+import { mcpInstall } from '../src/cli/mcp-install.js';
+import { hookInstall, hookUninstall } from '../src/cli/hook-install.js';
 
 const HELP = `
 easymd — collaborate on markdown files in your repo, live with humans and AI agents
@@ -24,6 +25,11 @@ Usage:
   easymd sync [dir]            One-shot: push all .md files under dir (default: .) to your account
   easymd watch [dir]           Foreground watcher (what 'auto on' runs in the background)
 
+  easymd mcp                   Run the MCP server (stdio) so AI agents can edit your docs
+  easymd mcp-install [agent]   Register the MCP server with Cursor / Claude (agent: --cursor | --claude-desktop)
+  easymd hook-install          Auto-sync .md to your account after every Claude Code session (everywhere)
+  easymd hook-uninstall        Remove the auto-sync hook
+
   easymd open <file>           Open a local .md for real-time collaborative editing in the browser
   easymd open <file> --port N  Use a fixed port (default: random)
 
@@ -65,6 +71,17 @@ async function cmdOpen(args) {
     console.log(`Note: ${absPath} does not exist yet — it will be created on save.`);
   }
 
+  // The local browser editor pulls in yjs/y-websocket/express — loaded lazily and as
+  // optional deps so the core commands (login/auto/sync/mcp) never depend on them.
+  let startServer;
+  try {
+    ({ startServer } = await import('../src/server.js'));
+  } catch {
+    console.error('`easymd open` needs the local editor packages. Install them with:');
+    console.error('  npm i -g easymd-cli  (ensures optional deps), or run from the repo.');
+    process.exit(1);
+  }
+
   const { url, shutdown } = await startServer(absPath, { port });
   console.log('');
   console.log('  easymd');
@@ -144,6 +161,16 @@ async function main() {
       return cmdWatch(rest);
     case 'sync':
       return cmdSync(rest);
+    case 'mcp':
+      // Importing starts the stdio MCP server (top-level await connect).
+      await import('../src/cli/mcp.mjs');
+      return;
+    case 'mcp-install':
+      return mcpInstall(rest[0]);
+    case 'hook-install':
+      return hookInstall();
+    case 'hook-uninstall':
+      return hookUninstall();
     case 'open':
       return cmdOpen(rest);
     default:

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "easymd-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Google Docs for markdown — collaborate on the actual .md file in your repo, live with humans and AI agents. CLI: login, auto-sync, and open .md files for real-time editing.",
   "type": "module",
   "bin": {
-    "easymd": "./bin/easymd.js"
+    "easymd": "./bin/easymd.js",
+    "easymd-cli": "./bin/easymd.js"
   },
   "files": [
     "bin",
@@ -31,9 +32,13 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chokidar": "^4.0.3",
-    "express": "^4.21.2",
     "open": "^10.1.0",
+    "zod": "^4.4.3"
+  },
+  "optionalDependencies": {
+    "express": "^4.21.2",
     "ws": "^8.18.0",
     "y-websocket": "^2.1.0",
     "yjs": "^13.6.24"

package/src/cli/auth.js

@@ -73,8 +73,17 @@ export async function login() {
 export async function logout() {
   await autoOff().catch(() => {});
   await clearAuto().catch(() => {});
+  // Revoke the token server-side so it can't be reused even if the file leaked.
+  const creds = await getCredentials();
+  if (creds?.token && creds?.url) {
+    try {
+      await fetch(`${creds.url}/api/cli/revoke`, { method: 'POST', headers: { Authorization: `Bearer ${creds.token}` } });
+    } catch {
+      /* offline — local credentials are still removed below */
+    }
+  }
   await clearCredentials();
-  console.log('✓ Logged out. Credentials removed.');
+  console.log('✓ Logged out. Token revoked and credentials removed.');
 }
 
 export async function whoami() {

package/src/cli/hook-install.js

@@ -0,0 +1,64 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { mkdir, readFile, writeFile, copyFile } from 'fs/promises';
+
+const CLAUDE_DIR = join(homedir(), '.claude');
+const SETTINGS = join(CLAUDE_DIR, 'settings.json');
+const HOOK_PATH = fileURLToPath(new URL('./hooks/easymd-stop-sync.sh', import.meta.url));
+const HOOK_CMD = `bash ${HOOK_PATH}`;
+const MARKER = 'easymd-stop-sync';
+
+async function readSettings() {
+  try {
+    return JSON.parse(await readFile(SETTINGS, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+async function writeSettings(s) {
+  await mkdir(CLAUDE_DIR, { recursive: true });
+  // Back up first — never clobber an existing config silently.
+  try {
+    await copyFile(SETTINGS, `${SETTINGS}.easymd-bak`);
+  } catch {
+    /* no existing file */
+  }
+  await writeFile(SETTINGS, JSON.stringify(s, null, 2));
+}
+
+// Registers a Claude Code Stop hook so that after any session that edits .md files,
+// they auto-sync to your easymd account — across every project, everywhere. Merges
+// alongside any existing Stop hooks (e.g. the obsidian-wiki capture hook).
+export async function hookInstall() {
+  const s = await readSettings();
+  s.hooks = s.hooks || {};
+  s.hooks.Stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : [];
+
+  if (JSON.stringify(s.hooks.Stop).includes(MARKER)) {
+    console.log('✓ easymd auto-sync hook is already installed.');
+    return;
+  }
+  s.hooks.Stop.push({ matcher: '', hooks: [{ type: 'command', command: HOOK_CMD }] });
+  await writeSettings(s);
+  console.log('✓ Installed the easymd auto-sync hook in ~/.claude/settings.json');
+  console.log('  After any Claude Code session that edits .md files, they sync to your account.');
+  console.log('  Requires `easymd login`. A backup was saved to settings.json.easymd-bak.');
+  console.log('  Remove anytime with `easymd hook-uninstall`.');
+}
+
+export async function hookUninstall() {
+  const s = await readSettings();
+  if (!s.hooks?.Stop?.length) {
+    console.log('easymd auto-sync hook is not installed.');
+    return;
+  }
+  const before = s.hooks.Stop.length;
+  s.hooks.Stop = s.hooks.Stop.filter((e) => !JSON.stringify(e).includes(MARKER));
+  if (s.hooks.Stop.length === before) {
+    console.log('easymd auto-sync hook is not installed.');
+    return;
+  }
+  await writeSettings(s);
+  console.log('✓ Removed the easymd auto-sync hook.');
+}

package/src/cli/hooks/easymd-stop-sync.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# easymd auto-sync Stop hook (adapted from the obsidian-wiki Stop-capture pattern).
+#
+# Fires on the Claude Code Stop event. If the session edited any .md files and you're
+# logged into easymd, it pushes those docs to your account — so your markdown stays
+# updated in easymd after every agent session, everywhere, with no daemon running.
+#
+# Always exits 0 (silent): it runs the sync directly, it never nudges Claude.
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Need credentials — no-op if not logged in.
+[[ -f "$HOME/.easymd/credentials.json" ]] || exit 0
+
+# Pull cwd + transcript path from the hook payload.
+read -r CWD TRANSCRIPT < <(printf '%s' "$INPUT" | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+print(d.get('cwd', ''), d.get('transcript_path', ''))
+" 2>/dev/null || echo " ")
+[[ -n "$TRANSCRIPT" && -f "$TRANSCRIPT" ]] || exit 0
+
+# Did this session write/edit any .md files?
+EDITED_MD=$(python3 - "$TRANSCRIPT" <<'PYEOF'
+import json, sys
+n = 0
+for line in open(sys.argv[1]):
+    line = line.strip()
+    if not line:
+        continue
+    try:
+        e = json.loads(line)
+    except json.JSONDecodeError:
+        continue
+    m = e.get("message") or {}
+    if m.get("role") != "assistant":
+        continue
+    for b in m.get("content") or []:
+        if isinstance(b, dict) and b.get("type") == "tool_use" and b.get("name") in ("Write", "Edit", "NotebookEdit"):
+            fp = (b.get("input") or {}).get("file_path", "")
+            if fp.endswith(".md"):
+                n += 1
+print(n)
+PYEOF
+)
+[[ "${EDITED_MD:-0}" -ge 1 ]] || exit 0
+
+# Resolve the easymd CLI from this script's own package (no PATH dependency).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EASYMD_BIN="$SCRIPT_DIR/../../../bin/easymd.js"
+[[ -f "$EASYMD_BIN" ]] || exit 0
+
+cd "${CWD:-$PWD}" 2>/dev/null || exit 0
+node "$EASYMD_BIN" sync . --quiet >/dev/null 2>&1 || true
+exit 0

package/src/cli/mcp-install.js

@@ -0,0 +1,48 @@
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+
+// Where each agent reads its MCP server config (macOS paths).
+const TARGETS = {
+  cursor: join(homedir(), '.cursor', 'mcp.json'),
+  'claude-desktop': join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+};
+
+// The bundled MCP server authenticates with the token from `easymd login`, so the
+// config needs no secrets — just the command.
+const SERVER = { command: 'easymd', args: ['mcp'] };
+
+async function mergeConfig(file) {
+  let cfg = {};
+  try {
+    cfg = JSON.parse(await readFile(file, 'utf8'));
+  } catch {
+    /* new file */
+  }
+  cfg.mcpServers = cfg.mcpServers || {};
+  cfg.mcpServers.easymd = SERVER;
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, JSON.stringify(cfg, null, 2));
+}
+
+export async function mcpInstall(arg) {
+  const which = (arg || '').replace(/^--/, '');
+  const entries = which && TARGETS[which] ? [[which, TARGETS[which]]] : Object.entries(TARGETS);
+
+  console.log('Registering the easymd MCP server…\n');
+  for (const [name, file] of entries) {
+    try {
+      await mergeConfig(file);
+      console.log(`  ✓ ${name.padEnd(15)} ${file}`);
+    } catch (e) {
+      console.log(`  ✗ ${name.padEnd(15)} ${e.message}`);
+    }
+  }
+  console.log('\nFor Claude Code (CLI), run instead:');
+  console.log('  claude mcp add easymd -- easymd mcp\n');
+  console.log('Prerequisites:');
+  console.log('  • Install globally:  npm i -g easymd-cli');
+  console.log('  • Log in once:       easymd login');
+  console.log('  • Restart your agent (Cursor / Claude) to load it.\n');
+  console.log('The server authenticates with your saved login — no API keys to paste.');
+}

package/src/cli/mcp.mjs

@@ -0,0 +1,125 @@
+// easymd MCP server (bundled in the CLI).
+//
+// Unlike the server-side MCP, this one is safe to run on any machine: it carries NO
+// server secrets. It authenticates as YOU using the CLI token saved at `easymd login`
+// (~/.easymd/credentials.json) and talks to the easymd web app's token-authed API.
+// So any agent (Claude, Cursor, …) can read/create/edit the same live documents you do.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { getCredentials } from './config.js';
+
+const creds = await getCredentials();
+const BASE = (creds?.url || process.env.EASYMD_URL || 'http://localhost:3000').replace(/\/$/, '');
+const TOKEN = creds?.token || '';
+
+const ok = (text) => ({ content: [{ type: 'text', text }] });
+const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
+const stripOwner = (name) => (name.includes('__') ? name.split('__').slice(1).join('__') : name);
+
+async function api(path, opts = {}) {
+  if (!TOKEN) throw new Error('Not logged in. Run `easymd login` first.');
+  const res = await fetch(`${BASE}${path}`, {
+    ...opts,
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${TOKEN}`, ...(opts.headers || {}) },
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(json.error || `HTTP ${res.status}`);
+  return json;
+}
+
+const server = new McpServer({ name: 'easymd', version: '0.1.1' });
+
+server.registerTool(
+  'list_documents',
+  {
+    title: 'List documents',
+    description: 'List all of your easymd documents (name, title, last updated). These are the live docs you edit in the browser.',
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      const { documents = [] } = await api('/api/cli/documents');
+      if (!documents.length) return ok('No documents yet. Use create_document to add one.');
+      return ok(documents.map((d) => `- ${stripOwner(d.name)}${d.title ? ` — ${d.title}` : ''} (updated ${d.updated_at})`).join('\n'));
+    } catch (e) {
+      return fail(e.message);
+    }
+  },
+);
+
+server.registerTool(
+  'read_document',
+  {
+    title: 'Read document',
+    description: 'Return the current markdown content of one of your documents by name.',
+    inputSchema: { name: z.string().describe('Document name, e.g. "product-spec"') },
+  },
+  async ({ name }) => {
+    try {
+      const { content } = await api(`/api/cli/documents?name=${encodeURIComponent(name)}`);
+      return ok(content || '(empty document)');
+    } catch (e) {
+      return fail(e.message);
+    }
+  },
+);
+
+server.registerTool(
+  'create_document',
+  {
+    title: 'Create document',
+    description: 'Create a new document in your account. It appears live in the editor and in your dashboard.',
+    inputSchema: {
+      name: z.string().describe('Short name/slug, e.g. "product-spec"'),
+      content: z.string().optional().describe('Optional initial markdown content'),
+    },
+  },
+  async ({ name, content }) => {
+    try {
+      const body = content && content.trim() ? content : `# ${name}\n\nCreated by an AI agent via MCP.\n`;
+      await api('/api/cli/documents', { method: 'POST', body: JSON.stringify({ name, title: name, content: body }) });
+      return ok(`Created "${name}". It now appears in your easymd dashboard and live editor.`);
+    } catch (e) {
+      return fail(e.message);
+    }
+  },
+);
+
+server.registerTool(
+  'update_document',
+  {
+    title: 'Update document (replace)',
+    description: 'Replace the entire markdown content of a document. Syncs live to anyone with it open.',
+    inputSchema: { name: z.string(), content: z.string().describe('New full markdown content') },
+  },
+  async ({ name, content }) => {
+    try {
+      await api('/api/cli/documents', { method: 'POST', body: JSON.stringify({ name, content }) });
+      return ok(`Updated "${name}" (${content.length} chars). Live editors saw it instantly.`);
+    } catch (e) {
+      return fail(e.message);
+    }
+  },
+);
+
+server.registerTool(
+  'append_to_document',
+  {
+    title: 'Append to document',
+    description: 'Append markdown to the end of a document without touching existing content. Syncs live.',
+    inputSchema: { name: z.string(), text: z.string().describe('Markdown to append') },
+  },
+  async ({ name, text }) => {
+    try {
+      const { bytes } = await api('/api/cli/documents', { method: 'POST', body: JSON.stringify({ name, op: 'append', text }) });
+      return ok(`Appended ${text.length} chars to "${name}" (now ${bytes} chars).`);
+    } catch (e) {
+      return fail(e.message);
+    }
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`easymd MCP ready → ${BASE} ${TOKEN ? '(authenticated)' : '(NOT logged in — run `easymd login`)'}`);