@cachly-dev/mcp-server 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,13 +1,33 @@
 # Changelog – cachly SDK (mcp)
 
 **Language:** MCP (Model Context Protocol)  
-**Package:** `@cachly-dev/mcp` on **npm**
+**Package:** `@cachly-dev/mcp-server` on **npm**
 
 > Full cross-SDK release notes: [../CHANGELOG.md](../CHANGELOG.md)
 
 ---
 
-## [0.2.0] – 2026-04-07
+## [0.2.0] – 2026-04-17
+
+### Added
+
+- **`setup` command** — interactive zero-arg CLI wizard (`npx @cachly-dev/mcp-server setup`):
+  - Reads `CACHLY_JWT` from env or prompts interactively via readline
+  - Fetches instances from API; presents list when multiple exist
+  - Auto-detects installed editors (Cursor, Windsurf, VS Code, Continue.dev) by checking for their config directories
+  - Writes the correct MCP config file for each detected editor in one step
+  - Always writes/updates `CLAUDE.md` (idempotent via `<!-- cachly-brain-start/end -->` markers)
+- **`init` command** now idempotent — re-running `npx @cachly-dev/mcp-server init` updates the brain block in `CLAUDE.md` instead of appending a duplicate
+- Shared helpers: `buildMcpConfig()`, `buildClaudeMdBlock()`, `writeClaudeMd()` — used by both `setup` and `init`
+
+### Fixed
+
+- `init` no longer duplicates the brain block in `CLAUDE.md` when run multiple times
+- Correct package name `@cachly-dev/mcp-server` used consistently (was `@cachly-dev/mcp` in generated configs)
+
+---
+
+## [0.1.1] – 2026-04-07
 
 ### Fixed
 

package/README.md

@@ -2,49 +2,31 @@
 
 > Manage your [cachly.dev](https://cachly.dev) cache instances directly from **GitHub Copilot, Claude, Cursor, Windsurf** and any other MCP-compatible AI assistant.
 
-## 🚀 One-Click Setup for GitHub Copilot
+## 🚀 Zero-Touch Setup — One Command
 
-Stop your AI from re-reading your entire codebase every time. One command enables **context memory**:
+Stop your AI from re-reading your entire codebase every time. One command enables **context memory** and configures all your editors automatically:
 
 ```bash
-# 1. Create a free cachly instance at https://cachly.dev
-# 2. Copy your JWT token from Settings
-# 3. Add to .vscode/mcp.json:
+CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup
 ```
 
-```json
-{
-  "servers": {
-    "cachly": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@cachly-dev/mcp-server"],
-      "env": {
-        "CACHLY_JWT": "your-jwt-token-here"
-      }
-    }
-  }
-}
-```
+The interactive wizard will:
+1. Authenticate with your cachly account (or prompt for JWT)
+2. Let you pick which cache instance to use as your AI Brain
+3. **Auto-detect** Cursor, Windsurf, VS Code, Claude Code, and Continue.dev
+4. Write the correct MCP config for every detected editor
+5. Create/update `CLAUDE.md` (idempotent — safe to re-run)
 
-Then add to `.github/copilot-instructions.md`:
-
-```markdown
-## Cachly AI Brain
-
-At the START of every session — single call:
-session_start(instance_id = "<your-instance-id>", focus = "<what you're working on>")
+**Result:** 60% fewer file reads, instant context across sessions, zero re-discovery.
 
-At the END of every session:
-session_end(instance_id = "<your-instance-id>", summary = "...", files_changed = [...])
+### Non-interactive (CI / scripted setup)
 
-After any bug fix or deploy:
-learn_from_attempts(instance_id = "<your-instance-id>", topic = "category:keyword",
-  outcome = "success", what_worked = "...", what_failed = "...", severity = "major")
+```bash
+CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server init \
+  --instance-id your-instance-id \
+  --editor vscode
 ```
 
-**Result:** 60% fewer file reads, instant context across sessions, zero re-discovery.
-
 ## What you can do
 
 Once connected, just talk to your AI assistant:
@@ -105,73 +87,74 @@ Once connected, just talk to your AI assistant:
 
 ## Setup
 
-### 1. Build
+### Recommended: Zero-Touch via npx
 
 ```bash
-npm install
-npm run build
+CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup
 ```
 
-### 2. Get your API token
+No install, no build step. The wizard auto-detects your editors and writes all config files.
 
-Go to **[cachly.dev/settings](https://cachly.dev/settings)** → API Tokens → Generate token.
+### Manual configuration
 
-### 3. Configure your AI client
+Get your JWT token at **[cachly.dev/settings](https://cachly.dev/settings)** → API Tokens.
 
-#### GitHub Copilot (VS Code)
-
-Add to `.vscode/mcp.json` in your project (or global user settings):
+#### Claude Code / Claude Desktop
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "cachly": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/absolute/path/to/sdk/mcp/dist/index.js"],
-      "env": {
-        "CACHLY_JWT": "your-jwt-token-here",
-        "CACHLY_API_URL": "https://api.cachly.dev"
-      }
+      "command": "npx",
+      "args": ["-y", "@cachly-dev/mcp-server"],
+      "env": { "CACHLY_JWT": "your-jwt-token-here" }
     }
   }
 }
 ```
 
-Then in VS Code: **Ctrl/Cmd+Shift+P → "MCP: List Servers"** → start `cachly`.
+- **Claude Code:** add to `.claude/mcp.json` in your project
+- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-#### Claude Desktop
+#### GitHub Copilot (VS Code)
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+Add to `.vscode/mcp.json`:
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "cachly": {
-      "command": "node",
-      "args": ["/absolute/path/to/sdk/mcp/dist/index.js"],
-      "env": {
-        "CACHLY_JWT": "your-jwt-token-here"
-      }
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cachly-dev/mcp-server"],
+      "env": { "CACHLY_JWT": "your-jwt-token-here" }
     }
   }
 }
 ```
 
-#### Cursor / Windsurf / Continue.dev
+Then: **Ctrl/Cmd+Shift+P → "MCP: List Servers"** → start `cachly`.
 
-Add to their respective MCP config (same `stdio` format as above).
+#### Cursor
 
-#### Via npx (no local build needed, once published to npm)
+Add to `.cursor/mcp.json`:
 
 ```json
 {
-  "command": "npx",
-  "args": ["-y", "@cachly-dev/mcp-server"],
-  "env": { "CACHLY_JWT": "your-token" }
+  "mcpServers": {
+    "cachly": {
+      "command": "npx",
+      "args": ["-y", "@cachly-dev/mcp-server"],
+      "env": { "CACHLY_JWT": "your-jwt-token-here" }
+    }
+  }
 }
 ```
 
+#### Windsurf / Continue.dev
+
+Same `stdio`/`mcpServers` format — add to their respective MCP config file.
+
 ## Environment Variables
 
 | Variable | Required | Default | Description |

package/dist/index.js

@@ -2790,87 +2790,221 @@ process.on('unhandledRejection', (reason) => {
     // Write to stderr only (stdout is the JSON-RPC channel)
     process.stderr.write(`[cachly-mcp] unhandledRejection: ${msg}\n`);
 });
+// ── CLI helpers ───────────────────────────────────────────────────────────────
+const EDITOR_FILES = {
+    claude: '.mcp.json',
+    cursor: '.cursor/mcp.json',
+    windsurf: '.windsurf/mcp.json',
+    copilot: '.vscode/mcp.json',
+    continue: '.continue/config.json',
+};
+const CLAUDE_MD_MARKER_START = '<!-- cachly-brain-start -->';
+const CLAUDE_MD_MARKER_END = '<!-- cachly-brain-end -->';
+function buildMcpConfig(apiKey, instanceId, editor) {
+    if (editor === 'continue') {
+        return JSON.stringify({
+            experimental: {
+                modelContextProtocolServers: [{
+                        transport: { type: 'stdio', command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'] },
+                        env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+                    }],
+            },
+        }, null, 2);
+    }
+    return JSON.stringify({
+        mcpServers: {
+            cachly: {
+                command: 'npx',
+                args: ['-y', '@cachly-dev/mcp-server@latest'],
+                env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+            },
+        },
+    }, null, 2);
+}
+function buildClaudeMdBlock(instanceId) {
+    return `${CLAUDE_MD_MARKER_START}
+## Cachly AI Brain
+
+The Cachly MCP server is available as tool \`cachly\`.
+
+### At the START of every session (one call):
+\`\`\`
+session_start(
+  instance_id = "${instanceId}",
+  focus       = "<what you plan to work on today>",
+)
+\`\`\`
+
+### At the END of every session:
+\`\`\`
+session_end(
+  instance_id     = "${instanceId}",
+  summary         = "What was accomplished (2-3 sentences)",
+  files_changed   = ["src/..."],
+  lessons_learned = 1,
+)
+\`\`\`
+
+### After fixing any bug or learning something new:
+\`\`\`
+learn_from_attempts(
+  instance_id = "${instanceId}",
+  topic       = "category:keyword",
+  outcome     = "success",
+  what_worked = "...",
+  what_failed = "...",
+  severity    = "critical" | "major" | "minor",
+  file_paths  = ["path/to/file"],
+  commands    = ["the command that worked"],
+  tags        = ["tag1", "tag2"],
+)
+\`\`\`
+${CLAUDE_MD_MARKER_END}`;
+}
+async function writeClaudeMd(projectDir, instanceId) {
+    const { writeFile, appendFile, readFile } = await import('node:fs/promises');
+    const { existsSync } = await import('node:fs');
+    const { resolve } = await import('node:path');
+    const claudeMdPath = resolve(projectDir, 'CLAUDE.md');
+    const block = '\n' + buildClaudeMdBlock(instanceId) + '\n';
+    if (existsSync(claudeMdPath)) {
+        const existing = await readFile(claudeMdPath, 'utf-8');
+        if (existing.includes(CLAUDE_MD_MARKER_START)) {
+            // Idempotent update: replace existing block (new instance-id, refreshed content)
+            const updated = existing.replace(new RegExp(`${CLAUDE_MD_MARKER_START}[\\s\\S]*?${CLAUDE_MD_MARKER_END}`), buildClaudeMdBlock(instanceId));
+            await writeFile(claudeMdPath, updated, 'utf-8');
+            return 'updated';
+        }
+        await appendFile(claudeMdPath, block, 'utf-8');
+        return 'appended';
+    }
+    await writeFile(claudeMdPath, block.trimStart(), 'utf-8');
+    return 'written';
+}
 // ── CLI: cachly init ──────────────────────────────────────────────────────────
 // Usage: npx @cachly-dev/mcp-server init --instance-id <id> --api-key <key> [--editor claude|cursor|windsurf|copilot|continue] [--project-dir /path]
 if (process.argv[2] === 'init') {
     const { writeFile, mkdir } = await import('node:fs/promises');
-    const { existsSync } = await import('node:fs');
     const { resolve, dirname } = await import('node:path');
-    // Parse CLI flags
     const argv = process.argv.slice(3);
-    const flag = (name) => {
-        const i = argv.indexOf(`--${name}`);
-        return i !== -1 ? argv[i + 1] : undefined;
-    };
+    const flag = (name) => { const i = argv.indexOf(`--${name}`); return i !== -1 ? argv[i + 1] : undefined; };
     const instanceId = flag('instance-id') ?? process.env.CACHLY_BRAIN_INSTANCE_ID;
     const apiKey = flag('api-key') ?? process.env.CACHLY_JWT;
     const editor = (flag('editor') ?? 'claude').toLowerCase();
     const projectDir = resolve(flag('project-dir') ?? '.');
     if (!instanceId || !apiKey) {
         console.error('\nUsage: npx @cachly-dev/mcp-server@latest init --instance-id <uuid> --api-key <cky_live_...> [--editor claude|cursor|windsurf|copilot|continue] [--project-dir /path]\n');
-        console.error('Get your instance ID and API key from: https://cachly.dev/instances\n');
+        console.error('Or run interactively (no flags needed): npx @cachly-dev/mcp-server@latest setup\n');
+        console.error('Get your credentials from: https://cachly.dev/setup-ai\n');
         process.exit(1);
     }
-    const editorFiles = {
-        claude: '.mcp.json',
-        cursor: '.cursor/mcp.json',
-        windsurf: '.windsurf/mcp.json',
-        copilot: '.vscode/mcp.json',
-        continue: '.continue/config.json',
-    };
-    const configFile = editorFiles[editor] ?? '.mcp.json';
+    const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
     const configPath = resolve(projectDir, configFile);
-    // Build config content
-    let configContent;
-    if (editor === 'continue') {
-        configContent = JSON.stringify({
-            experimental: {
-                modelContextProtocolServers: [{
-                        transport: { type: 'stdio', command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'] },
-                        env: {
-                            CACHLY_API_URL: 'https://api.cachly.dev',
-                            CACHLY_JWT: apiKey,
-                            CACHLY_BRAIN_INSTANCE_ID: instanceId,
-                        },
-                    }],
-            },
-        }, null, 2);
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, buildMcpConfig(apiKey, instanceId, editor), 'utf-8');
+    console.log(`\n✅ Written: ${configFile}`);
+    // Always write CLAUDE.md (idempotent — safe to run multiple times)
+    const result = await writeClaudeMd(projectDir, instanceId);
+    const action = result === 'updated' ? '✅ Updated' : result === 'appended' ? '✅ Appended to' : '✅ Written';
+    console.log(`${action}: CLAUDE.md`);
+    console.log(`\n🧠 Cachly AI Brain configured for ${editor === 'claude' ? 'Claude Code' : editor}!`);
+    console.log(`   Restart your editor — the \`cachly\` MCP tools will appear.\n`);
+    process.exit(0);
+}
+// ── CLI: cachly setup (interactive — no flags required) ───────────────────────
+// Usage: npx @cachly-dev/mcp-server setup
+if (process.argv[2] === 'setup') {
+    const { writeFile, mkdir } = await import('node:fs/promises');
+    const { existsSync } = await import('node:fs');
+    const { resolve, dirname } = await import('node:path');
+    const { createInterface } = await import('node:readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise(res => rl.question(q, ans => res(ans.trim())));
+    console.log('\n🧠  cachly AI Brain — Interactive Setup');
+    console.log('────────────────────────────────────────\n');
+    // ── Step 1: API token ──────────────────────────────────────────────────────
+    let token = process.env.CACHLY_JWT ?? '';
+    if (token) {
+        console.log('✓  Using token from CACHLY_JWT env var\n');
     }
     else {
-        configContent = JSON.stringify({
-            mcpServers: {
-                cachly: {
-                    command: 'npx',
-                    args: ['-y', '@cachly-dev/mcp-server@latest'],
-                    env: {
-                        CACHLY_API_URL: 'https://api.cachly.dev',
-                        CACHLY_JWT: apiKey,
-                        CACHLY_BRAIN_INSTANCE_ID: instanceId,
-                    },
-                },
-            },
-        }, null, 2);
-    }
-    // Create parent dirs if needed, then write config
-    await mkdir(dirname(configPath), { recursive: true });
-    await writeFile(configPath, configContent, 'utf-8');
-    console.log(`\n✅ Written: ${configPath}`);
-    // For Claude Code, also offer to append CLAUDE.md snippet
-    if (editor === 'claude') {
-        const claudeMdSnippet = `\n## Cachly AI Brain\n\nThe Cachly MCP server is available as tool \`cachly\`.\n\n### At the START of every session (one call):\n\`\`\`\nsession_start(\n  instance_id = "${instanceId}",\n  focus       = "<what you plan to work on today>",\n)\n\`\`\`\n\n### At the END of every session:\n\`\`\`\nsession_end(\n  instance_id     = "${instanceId}",\n  summary         = "What was accomplished",\n  files_changed   = ["src/..."],\n  lessons_learned = 1,\n)\n\`\`\`\n\n### After fixing any bug or learning something:\n\`\`\`\nlearn_from_attempts(\n  instance_id = "${instanceId}",\n  topic       = "category:keyword",\n  outcome     = "success",\n  what_worked = "...",\n  what_failed = "...",\n  severity    = "critical" | "major" | "minor",\n  file_paths  = ["path/to/file"],\n  commands    = ["the command that worked"],\n  tags        = ["tag1", "tag2"],\n)\n\`\`\`\n`;
-        const claudeMdPath = resolve(projectDir, 'CLAUDE.md');
-        const { appendFile } = await import('node:fs/promises');
-        if (existsSync(claudeMdPath)) {
-            await appendFile(claudeMdPath, claudeMdSnippet, 'utf-8');
-            console.log(`✅ Appended: ${claudeMdPath}`);
-        }
-        else {
-            await writeFile(claudeMdPath, claudeMdSnippet.trimStart(), 'utf-8');
-            console.log(`✅ Written: ${claudeMdPath}`);
+        console.log('Step 1: Get your API token at https://cachly.dev/setup-ai\n');
+        token = await ask('   Paste API token (cky_live_...): ');
+        if (!token) {
+            console.error('\nToken is required. Aborting.\n');
+            rl.close();
+            process.exit(1);
         }
+        console.log('');
     }
-    console.log(`\n🧠 Cachly AI Brain configured for ${editor === 'claude' ? 'Claude Code' : editor}!`);
-    console.log(`   Restart your editor — the \`cachly\` MCP tools will appear.\n`);
+    // ── Step 2: Fetch & pick instance ─────────────────────────────────────────
+    process.stdout.write('⏳ Fetching your instances...');
+    let instances = [];
+    try {
+        const res = await fetch(`${API_URL}/api/v1/instances`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const body = await res.json();
+        instances = (body.data ?? []).filter(i => i.status === 'running');
+    }
+    catch (e) {
+        console.error(`\n\nFailed to fetch instances: ${e.message}`);
+        console.error('Check your token and try again.\n');
+        rl.close();
+        process.exit(1);
+    }
+    console.log(` found ${instances.length}\n`);
+    if (instances.length === 0) {
+        console.error('No running instances found. Create one at https://cachly.dev/instances\n');
+        rl.close();
+        process.exit(1);
+    }
+    let instance = instances[0];
+    if (instances.length > 1) {
+        console.log('Step 2: Pick your Brain instance:\n');
+        instances.forEach((inst, idx) => console.log(`   ${idx + 1}. ${inst.name.padEnd(24)} ${inst.tier.padEnd(10)} ${inst.region}`));
+        const raw = await ask(`\n   Pick [1-${instances.length}] (Enter = 1): `);
+        const idx = parseInt(raw || '1', 10) - 1;
+        instance = instances[Math.max(0, Math.min(instances.length - 1, idx))];
+    }
+    console.log(`✓  Instance: ${instance.name} (${instance.id.slice(0, 8)}…)\n`);
+    // ── Step 3: Detect editors ────────────────────────────────────────────────
+    const cwd = process.cwd();
+    const detected = [];
+    // Claude Code: always include (CLAUDE.md is universal)
+    detected.push('claude');
+    if (existsSync(resolve(cwd, '.cursor')))
+        detected.push('cursor');
+    if (existsSync(resolve(cwd, '.windsurf')))
+        detected.push('windsurf');
+    if (existsSync(resolve(cwd, '.vscode')))
+        detected.push('copilot');
+    if (existsSync(resolve(cwd, '.continue')))
+        detected.push('continue');
+    const editorLabel = (e) => ({ claude: 'Claude Code', cursor: 'Cursor', windsurf: 'Windsurf', copilot: 'GitHub Copilot', continue: 'Continue.dev' })[e] ?? e;
+    console.log(`Step 3: Detected editors: ${detected.map(editorLabel).join(', ')}`);
+    const editorsRaw = await ask(`   Configure for which? [all / ${detected.join('/')}] (Enter = all): `);
+    const editorsToSetup = !editorsRaw || editorsRaw.toLowerCase() === 'all'
+        ? detected
+        : editorsRaw.split(/[,\s]+/).map(s => s.toLowerCase()).filter(s => EDITOR_FILES[s]);
+    console.log('');
+    // ── Step 4: Write editor configs ──────────────────────────────────────────
+    for (const editor of editorsToSetup) {
+        const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
+        const configPath = resolve(cwd, configFile);
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, buildMcpConfig(token, instance.id, editor), 'utf-8');
+        console.log(`✅ Written: ${configFile}`);
+    }
+    // ── Step 5: CLAUDE.md (always — idempotent) ───────────────────────────────
+    const mdResult = await writeClaudeMd(cwd, instance.id);
+    const mdLabel = mdResult === 'updated' ? '✅ Updated' : mdResult === 'appended' ? '✅ Appended to' : '✅ Written';
+    console.log(`${mdLabel}: CLAUDE.md`);
+    rl.close();
+    console.log(`\n🧠  Done! Restart your editor — the \`cachly\` MCP tools will appear.`);
+    console.log(`    Your AI now has persistent memory across every session.\n`);
     process.exit(0);
 }
 // ── Start ─────────────────────────────────────────────────────────────────────