@cachly-dev/mcp-server 0.5.1 β 0.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -262
- package/dist/index.js +194 -39
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
- package/scripts/postinstall.js +27 -0
- package/src/index.ts +196 -39
package/README.md
CHANGED
|
@@ -1,124 +1,94 @@
|
|
|
1
|
-
# cachly
|
|
1
|
+
# Your AI Assistant Has Amnesia. cachly Fixes That.
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> **cachly MCP Server** β Give GitHub Copilot, Claude Code, Cursor, and Windsurf a persistent brain that remembers every lesson, every decision, every bug you've ever fixed.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@cachly-dev/mcp-server)
|
|
6
|
+
[](../../LICENSE)
|
|
7
|
+
[](https://cachly.dev/legal)
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
---
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup
|
|
11
|
-
```
|
|
11
|
+
## The Pain
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
1. Authenticate with your cachly account (or prompt for JWT)
|
|
15
|
-
2. Let you pick which cache instance to use as your AI Brain
|
|
16
|
-
3. **Auto-detect** Cursor, Windsurf, VS Code, Claude Code, and Continue.dev
|
|
17
|
-
4. Write the correct MCP config for every detected editor
|
|
18
|
-
5. Create/update `CLAUDE.md` (idempotent β safe to re-run)
|
|
13
|
+
Every morning, you open your AI coding assistant. It doesn't remember yesterday. You explain your architecture. You explain the deployment process. You explain the bug you fixed last week. You paste the same context files over and over.
|
|
19
14
|
|
|
20
|
-
**
|
|
15
|
+
**The average developer wastes 45 minutes per day on context re-establishment.** That's β¬15,000+ in lost productivity per engineer per year.
|
|
21
16
|
|
|
22
|
-
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## The Fix β One Command
|
|
23
20
|
|
|
24
21
|
```bash
|
|
25
|
-
CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server
|
|
26
|
-
--instance-id your-instance-id \
|
|
27
|
-
--editor vscode
|
|
22
|
+
CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup
|
|
28
23
|
```
|
|
29
24
|
|
|
30
|
-
|
|
25
|
+
The wizard:
|
|
26
|
+
1. Authenticates with your cachly account
|
|
27
|
+
2. Lets you pick which instance to use as your AI Brain
|
|
28
|
+
3. **Auto-detects** Cursor, Windsurf, VS Code, Claude Code, Continue.dev
|
|
29
|
+
4. Writes the correct MCP config for every detected editor
|
|
30
|
+
5. Creates `CLAUDE.md` / `.github/copilot-instructions.md` with the memory rules
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
**Result:** Your AI assistant remembers everything. Always.
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## With vs. Without cachly Brain
|
|
37
|
+
|
|
38
|
+
| Situation | Without cachly | With cachly |
|
|
39
|
+
|-----------|----------------|-------------|
|
|
40
|
+
| Session start | "What's your architecture?" | "Ready. 23 lessons, last session: deployed API." |
|
|
41
|
+
| Known bug hits again | Re-researches from scratch | "You fixed this on March 12, here's the exact command" |
|
|
42
|
+
| After holiday / team handoff | Context dead | Fully briefed in < 10 seconds |
|
|
43
|
+
| Repeated LLM patterns | Pays for each re-discovery | Recalls from cache, ~1,200 tokens saved per hit |
|
|
44
|
+
| Architecture decisions | Lost in chat history | Permanently stored, searchable |
|
|
45
|
+
| New team member | Weeks to onboard | Session start gives full context instantly |
|
|
46
|
+
|
|
47
|
+
---
|
|
40
48
|
|
|
41
|
-
##
|
|
49
|
+
## How It Works
|
|
42
50
|
|
|
43
|
-
|
|
51
|
+
The MCP server gives your AI 30+ tools backed by your cachly Valkey instance:
|
|
44
52
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
| **`
|
|
49
|
-
| **`
|
|
53
|
+
### π§ Session & Memory
|
|
54
|
+
| Tool | What it does |
|
|
55
|
+
|------|-------------|
|
|
56
|
+
| **`session_start`** | Full briefing: last session, lessons, open failures, brain health. Call at the start of every session. |
|
|
57
|
+
| **`session_end`** | Save summary, files changed, duration. Auto-extracts lessons. |
|
|
58
|
+
| **`learn_from_attempts`** | Store structured lessons after any fix or deploy. Deduplicates by topic. |
|
|
50
59
|
| **`recall_best_solution`** | Retrieve the best known solution for a topic (increments recall count). |
|
|
51
|
-
| **`remember_context`** | Cache
|
|
52
|
-
| **`
|
|
53
|
-
| **`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. |
|
|
54
|
-
| **`list_remembered`** | List all cached context entries. |
|
|
55
|
-
| **`forget_context`** | Delete stale context. |
|
|
60
|
+
| **`remember_context`** | Cache architecture findings, decisions, file summaries. |
|
|
61
|
+
| **`smart_recall`** | BM25+ search across all brain data β no embedding needed. |
|
|
56
62
|
|
|
57
63
|
### βοΈ Instance Management
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|---|---|
|
|
64
|
+
| Tool | What it does |
|
|
65
|
+
|------|-------------|
|
|
61
66
|
| `list_instances` | List all your cache instances |
|
|
62
|
-
| `create_instance` |
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `delete_instance` | Permanently delete an instance |
|
|
67
|
+
| `create_instance` | Spin up a new instance (free or paid) |
|
|
68
|
+
| `get_connection_string` | Get the `redis://` URL |
|
|
69
|
+
| `delete_instance` | Remove an instance |
|
|
66
70
|
|
|
67
71
|
### ποΈ Cache Operations
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|---|---|
|
|
72
|
+
| Tool | What it does |
|
|
73
|
+
|------|-------------|
|
|
71
74
|
| `cache_get` / `cache_set` / `cache_delete` | Live cache operations |
|
|
72
|
-
| `cache_exists` / `cache_ttl` / `cache_keys` | Key inspection |
|
|
73
|
-
| `cache_stats` | Memory, hit rate, ops/sec |
|
|
74
75
|
| `cache_mget` / `cache_mset` | Bulk pipeline operations |
|
|
75
|
-
| `cache_lock_acquire` / `cache_lock_release` | Distributed locks
|
|
76
|
+
| `cache_lock_acquire` / `cache_lock_release` | Distributed locks |
|
|
76
77
|
| `cache_stream_set` / `cache_stream_get` | LLM token streaming cache |
|
|
78
|
+
| `cache_stats` | Memory, hit rate, ops/sec |
|
|
77
79
|
|
|
78
80
|
### π Semantic & AI
|
|
81
|
+
| Tool | What it does |
|
|
82
|
+
|------|-------------|
|
|
83
|
+
| `semantic_search` | Find cached entries by meaning (requires embedding provider) |
|
|
84
|
+
| `cache_warmup` | Pre-warm the cache with prompt/response pairs |
|
|
85
|
+
| `detect_namespace` | Classify a prompt into semantic namespace |
|
|
79
86
|
|
|
80
|
-
|
|
81
|
-
|---|---|
|
|
82
|
-
| `semantic_search` | Vector similarity search (Speed/Business tier) |
|
|
83
|
-
| `detect_namespace` | Auto-classify prompt into semantic namespace |
|
|
84
|
-
| `cache_warmup` | Pre-warm semantic cache with known Q&A pairs |
|
|
85
|
-
| `index_project` | Index local source files for AI semantic search |
|
|
86
|
-
| `get_api_status` | Check API health + JWT auth info |
|
|
87
|
-
|
|
88
|
-
## Setup
|
|
89
|
-
|
|
90
|
-
### Recommended: Zero-Touch via npx
|
|
91
|
-
|
|
92
|
-
```bash
|
|
93
|
-
CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
No install, no build step. The wizard auto-detects your editors and writes all config files.
|
|
97
|
-
|
|
98
|
-
### Manual configuration
|
|
99
|
-
|
|
100
|
-
Get your JWT token at **[cachly.dev/settings](https://cachly.dev/settings)** β API Tokens.
|
|
101
|
-
|
|
102
|
-
#### Claude Code / Claude Desktop
|
|
103
|
-
|
|
104
|
-
```json
|
|
105
|
-
{
|
|
106
|
-
"mcpServers": {
|
|
107
|
-
"cachly": {
|
|
108
|
-
"command": "npx",
|
|
109
|
-
"args": ["-y", "@cachly-dev/mcp-server"],
|
|
110
|
-
"env": { "CACHLY_JWT": "your-jwt-token-here" }
|
|
111
|
-
}
|
|
112
|
-
}
|
|
113
|
-
}
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
- **Claude Code:** add to `.claude/mcp.json` in your project
|
|
117
|
-
- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
87
|
+
---
|
|
118
88
|
|
|
119
|
-
|
|
89
|
+
## Manual Setup (without wizard)
|
|
120
90
|
|
|
121
|
-
Add to
|
|
91
|
+
Add to `~/.vscode/mcp.json`, `.cursor/mcp.json`, or `.mcp.json`:
|
|
122
92
|
|
|
123
93
|
```json
|
|
124
94
|
{
|
|
@@ -127,189 +97,39 @@ Add to `.vscode/mcp.json`:
|
|
|
127
97
|
"type": "stdio",
|
|
128
98
|
"command": "npx",
|
|
129
99
|
"args": ["-y", "@cachly-dev/mcp-server"],
|
|
130
|
-
"env": { "CACHLY_JWT": "your-jwt-token
|
|
100
|
+
"env": { "CACHLY_JWT": "your-jwt-token" }
|
|
131
101
|
}
|
|
132
102
|
}
|
|
133
103
|
}
|
|
134
104
|
```
|
|
135
105
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
```json
|
|
143
|
-
{
|
|
144
|
-
"mcpServers": {
|
|
145
|
-
"cachly": {
|
|
146
|
-
"command": "npx",
|
|
147
|
-
"args": ["-y", "@cachly-dev/mcp-server"],
|
|
148
|
-
"env": { "CACHLY_JWT": "your-jwt-token-here" }
|
|
149
|
-
}
|
|
150
|
-
}
|
|
151
|
-
}
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
#### Windsurf / Continue.dev
|
|
155
|
-
|
|
156
|
-
Same `stdio`/`mcpServers` format β add to their respective MCP config file.
|
|
157
|
-
|
|
158
|
-
## Environment Variables
|
|
159
|
-
|
|
160
|
-
| Variable | Required | Default | Description |
|
|
161
|
-
|---|---|---|---|
|
|
162
|
-
| `CACHLY_JWT` | β
| β | Your Keycloak JWT from cachly.dev/settings |
|
|
163
|
-
| `CACHLY_API_URL` | β | `https://api.cachly.dev` | Override for local dev |
|
|
164
|
-
|
|
165
|
-
## Example Session
|
|
166
|
-
|
|
167
|
-
```
|
|
168
|
-
User: Create a free cache instance for my OpenAI project
|
|
169
|
-
|
|
170
|
-
Copilot: I'll create a free cachly instance for you.
|
|
171
|
-
[calls create_instance(name="openai-cache", tier="free")]
|
|
172
|
-
|
|
173
|
-
β
Instance **openai-cache** (FREE) created and provisioning started!
|
|
174
|
-
ID: `a1b2c3d4-...`
|
|
175
|
-
Status: provisioning
|
|
176
|
-
|
|
177
|
-
Use `get_connection_string` to get your Redis URL in ~30 seconds.
|
|
178
|
-
|
|
179
|
-
User: Get the connection string
|
|
180
|
-
|
|
181
|
-
Copilot: [calls get_connection_string(instance_id="a1b2c3d4-...")]
|
|
182
|
-
|
|
183
|
-
Connection string for openai-cache:
|
|
184
|
-
redis://:password@my-node.cachly.dev:30101
|
|
185
|
-
|
|
186
|
-
Environment variable:
|
|
187
|
-
REDIS_URL="redis://:password@my-node.cachly.dev:30101"
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
## Local Development
|
|
191
|
-
|
|
192
|
-
```bash
|
|
193
|
-
# Run against local API
|
|
194
|
-
CACHLY_JWT=your-token CACHLY_API_URL=http://localhost:3001 npm run dev
|
|
106
|
+
Add to `CLAUDE.md` / `.github/copilot-instructions.md`:
|
|
107
|
+
```markdown
|
|
108
|
+
## AI Brain Rules (cachly)
|
|
109
|
+
- Call session_start BEFORE reading any files or making changes
|
|
110
|
+
- Call learn_from_attempts AFTER every fix, deploy, or discovery
|
|
111
|
+
- Call session_end when closing the window
|
|
195
112
|
```
|
|
196
113
|
|
|
197
114
|
---
|
|
198
115
|
|
|
199
|
-
##
|
|
200
|
-
|
|
201
|
-
### π§ Stop Re-Reading Your Codebase β "Thinking Cache"
|
|
202
|
-
|
|
203
|
-
**The Problem:** Every time you ask Copilot about your codebase, it runs "Ich verschaffe mir einen Γberblick ΓΌber die Codebasis" and re-reads hundreds of files.
|
|
204
|
-
|
|
205
|
-
**The Solution:** Cache your AI's "thinking" results:
|
|
206
|
-
|
|
207
|
-
```
|
|
208
|
-
You: "Analyze the authentication architecture"
|
|
209
|
-
AI: [reads 47 files, takes 30 seconds]
|
|
210
|
-
The auth uses Keycloak with JWT tokens. The flow is:
|
|
211
|
-
1. User hits /sign-in β NextAuth redirect
|
|
212
|
-
2. Keycloak validates credentials
|
|
213
|
-
3. JWT returned, stored in session
|
|
214
|
-
|
|
215
|
-
[calls remember_context("auth_architecture", "The auth uses Keycloak...")]
|
|
216
|
-
π§ Context saved for future sessions.
|
|
217
|
-
|
|
218
|
-
--- Next day, new session ---
|
|
219
|
-
|
|
220
|
-
You: "How does auth work?"
|
|
221
|
-
AI: [calls smart_recall("auth")]
|
|
222
|
-
π§ Found cached context:
|
|
223
|
-
The auth uses Keycloak with JWT tokens...
|
|
224
|
-
|
|
225
|
-
(No file reading needed β instant answer!)
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
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.
|
|
229
|
-
|
|
230
|
-
### 1. AI-Assisted Development β "Which caches am I using?"
|
|
116
|
+
## Pricing
|
|
231
117
|
|
|
232
|
-
|
|
118
|
+
| Tier | RAM | Price | Best for |
|
|
119
|
+
|------|-----|-------|----------|
|
|
120
|
+
| **Free** | 25 MB | β¬0/mo | Dev & side projects |
|
|
121
|
+
| **Dev** | 200 MB | β¬9/mo | Individual developers |
|
|
122
|
+
| **Pro** | 900 MB | β¬29/mo | Teams |
|
|
123
|
+
| **Speed** | 900 MB Dragonfly + Semantic Cache | β¬79/mo | AI-heavy workloads |
|
|
124
|
+
| **Business** | 7 GB | β¬199/mo | Scale-ups |
|
|
233
125
|
|
|
234
|
-
|
|
235
|
-
You: "List all my cachly instances and their status"
|
|
236
|
-
AI: Using cachly_list_instances...
|
|
237
|
-
|
|
238
|
-
You have 3 instances:
|
|
239
|
-
1. prod-api (Pro, running) β redis://:***@prod.cachly.dev:30101
|
|
240
|
-
2. staging (Dev, running) β redis://:***@staging.cachly.dev:30102
|
|
241
|
-
3. ml-pipeline (Speed, running) β redis://:***@ml.cachly.dev:30103
|
|
242
|
-
|
|
243
|
-
Total MRR: β¬72/month
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
### 2. Cache Debugging β "Why is my hit rate dropping?"
|
|
247
|
-
|
|
248
|
-
Your semantic cache hit rate dropped overnight. Debug it without leaving your editor:
|
|
249
|
-
|
|
250
|
-
```
|
|
251
|
-
You: "Check the analytics for my prod-api instance"
|
|
252
|
-
AI: Using cachly_semantic_stats...
|
|
253
|
-
|
|
254
|
-
β οΈ Hit rate dropped 23% in the last 24h (82% β 63%)
|
|
255
|
-
|
|
256
|
-
Anomaly detected: near-miss spike (+140%)
|
|
257
|
-
β 47 queries are hitting similarity 0.80-0.84 (just below your 0.85 threshold)
|
|
258
|
-
|
|
259
|
-
Recommendation: Lower threshold to 0.82 to capture these near-misses.
|
|
260
|
-
|
|
261
|
-
You: "Do it"
|
|
262
|
-
AI: Using cachly_set_threshold... β
Threshold set to 0.82 for namespace cachly:sem
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
### 3. Deployment Cache Warmup β "Pre-fill the cache for the new release"
|
|
266
|
-
|
|
267
|
-
After deploying a new version, warm the semantic cache with common queries:
|
|
268
|
-
|
|
269
|
-
```
|
|
270
|
-
You: "Warm up the staging cache with our top 50 support questions"
|
|
271
|
-
AI: Using cachly_batch_index with your FAQ embeddings...
|
|
272
|
-
|
|
273
|
-
β
Indexed 50 entries in 340ms (batch pipeline)
|
|
274
|
-
Namespace: cachly:sem:qa
|
|
275
|
-
|
|
276
|
-
Your cache is ready β first users will get instant responses.
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
### 4. Cost Monitoring β "How much am I saving?"
|
|
280
|
-
|
|
281
|
-
Track your LLM cost savings directly in your IDE:
|
|
282
|
-
|
|
283
|
-
```
|
|
284
|
-
You: "How much has cachly saved me this month?"
|
|
285
|
-
AI: Using cachly_semantic_stats...
|
|
286
|
-
|
|
287
|
-
π This month's savings:
|
|
288
|
-
- Total cache hits: 12,847
|
|
289
|
-
- Estimated savings: $384.21 (vs. direct LLM calls)
|
|
290
|
-
- Efficiency score: 84/100 (Grade: A)
|
|
291
|
-
- Best namespace: cachly:sem:qa (94% hit rate)
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
### 5. CI Pipeline Integration β "Check cache health before deploy"
|
|
295
|
-
|
|
296
|
-
Add cache health checks to your deployment workflow:
|
|
297
|
-
|
|
298
|
-
```
|
|
299
|
-
You: "Check if any cache anomalies would block a deploy"
|
|
300
|
-
AI: Using cachly_analytics_anomalies...
|
|
301
|
-
|
|
302
|
-
β
No critical anomalies detected.
|
|
303
|
-
1 info-level notice: stale cache in namespace "translations"
|
|
304
|
-
(12 near-misses/24h, 0 new entries)
|
|
305
|
-
|
|
306
|
-
Recommendation: Run warmup after deploy for translations namespace.
|
|
307
|
-
Deploy is safe to proceed.
|
|
308
|
-
```
|
|
126
|
+
All plans: **German servers Β· GDPR-compliant Β· No US data transfer Β· 99.9% SLA**
|
|
309
127
|
|
|
310
128
|
---
|
|
311
129
|
|
|
312
|
-
##
|
|
313
|
-
|
|
314
|
-
MIT Β© [cachly.dev](https://cachly.dev)
|
|
130
|
+
## Links
|
|
315
131
|
|
|
132
|
+
- [cachly.dev](https://cachly.dev) β Dashboard & free signup
|
|
133
|
+
- [AI Brain docs](https://cachly.dev/docs/ai-memory) β Full documentation
|
|
134
|
+
- [npm](https://www.npmjs.com/package/@cachly-dev/mcp-server) β Package
|
|
135
|
+
- [GitHub](https://github.com/cachly-dev/mcp-server)
|