easymd-cli 0.1.0 → 0.1.1

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,11 @@
 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';
 
 const HELP = `
 easymd — collaborate on markdown files in your repo, live with humans and AI agents
@@ -24,6 +24,9 @@ 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 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 +68,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 +158,12 @@ 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 'open':
       return cmdOpen(rest);
     default:

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "easymd-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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/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`)'}`);