@cachly-dev/mcp-server 0.1.0 → 0.5.1

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:
@@ -68,7 +50,7 @@ Once connected, just talk to your AI assistant:
 | **`recall_best_solution`** | Retrieve the best known solution for a topic (increments recall count). |
 | **`remember_context`** | Cache any analysis or architecture finding for future sessions. |
 | **`recall_context`** | Retrieve cached context by exact key (supports glob: `"file:*"`). |
-| **`smart_recall`** | Semantic search across all cached context by meaning/keywords. |
+| **`smart_recall`** | BM25+ keyword search across all cached context. Works **without any embedding provider**. Optionally adds semantic vector search if an API key is configured. |
 | **`list_remembered`** | List all cached context entries. |
 | **`forget_context`** | Delete stale context. |
 
@@ -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 |
@@ -242,23 +225,7 @@ AI:  [calls smart_recall("auth")]
      (No file reading needed — instant answer!)
 ```
 
-**Setup in 2 minutes:**
-
-1. Add to `.github/copilot-instructions.md` (or `CLAUDE.md` for Claude Code):
-```markdown
-## Cachly AI Brain
-
-At the START of every session:
-session_start(instance_id = "<id>", focus = "<what you plan to work on>")
-
-At the END of every session:
-session_end(instance_id = "<id>", summary = "...", files_changed = [...])
-
-After any bug fix: learn_from_attempts(instance_id = "<id>", topic = "category:keyword",
-  outcome = "success", what_worked = "...", severity = "major")
-```
-
-2. From now on: your AI calls `session_start` first and never re-reads what it already knows.
+The `setup` wizard (see top of this README) writes the session instructions automatically into your `CLAUDE.md` / `.github/copilot-instructions.md` — **no manual editing needed.** Just run `npx @cachly-dev/mcp-server setup` once and your AI assistant calls `session_start` at the start of every session automatically.
 
 ### 1. AI-Assisted Development — "Which caches am I using?"
 

package/dist/index.d.ts

@@ -1,2 +1,31 @@
 #!/usr/bin/env node
-export {};
+/**
+ * Stopwords — filtered out during tokenization.
+ * Covers: English, German, French, Spanish, Italian, Portuguese.
+ * Keeps the index small and scores meaningful.
+ */
+declare const STOPWORDS: Set<string>;
+/** Tokenize text into meaningful keywords. Handles unicode (accented chars). */
+declare function tokenize(text: string): string[];
+/**
+ * Split a multi-topic query into sub-queries.
+ * Detects numbered lists, semicolons, "and also", line breaks, etc.
+ *
+ * Example: "deploy API fix routing and also check auth" →
+ *   ["deploy API fix routing", "check auth"]
+ *
+ * Example: "1. deploy 2. fix routing 3. auth" →
+ *   ["deploy", "fix routing", "auth"]
+ */
+declare function splitMultiQuery(query: string): string[];
+/**
+ * Levenshtein distance — edit distance between two strings.
+ * Used for typo-tolerant fuzzy matching (distance ≤ 2 = match).
+ * O(n*m) but strings are short (tokens), so this is fast.
+ */
+declare function levenshtein(a: string, b: string): number;
+/** Extract a timestamp from JSON content (looks for "ts" or "created" fields). */
+declare function extractTimestamp(content: string): number | undefined;
+/** Recency multiplier: 1.0 for now, 0.5 after half-life days, exponential decay. */
+declare function recencyBoost(timestampMs: number | undefined): number;
+export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS };