heurchain 1.2.0 → 1.2.1

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.
Files changed (3) hide show
  1. package/README.md +2 -0
  2. package/package.json +1 -1
  3. package/server.js +328 -204
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # HeurChain
2
2
 
3
+ > **HeurChain** — short for **Heuristic Chaining** — describes the core design principle: knowledge is not stored in isolation but chained through heuristic reasoning, so that each piece of stored information reinforces and contextualizes what came before. The result is a memory system that improves its own recall accuracy over time, across every agent that writes to it.
4
+
3
5
  **One memory system. Every AI agent. Simultaneously.**
4
6
 
5
7
  HeurChain is a universal persistent memory layer for AI agents. Claude Code, Kimi, Hermes, OpenClaw, ChatGPT, and any HTTP or MCP client share the same tiered knowledge store — BM25-ranked search, session continuity, and automatic tier promotion — without any agent-specific configuration beyond a URL and an interface choice.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "heurchain",
3
- "version": "1.2.0",
3
+ "version": "1.2.1",
4
4
  "description": "MCP (Model Context Protocol) server for HeurChain — tiered agent memory with BM25 search, session lifecycle, and infrastructure knowledge tools",
5
5
  "main": "server.js",
6
6
  "scripts": {
package/server.js CHANGED
@@ -13,10 +13,60 @@ app.use(cors());
13
13
  const redis = createClient({ url: process.env.REDIS_URL || "redis://localhost:6379" });
14
14
  redis.on("error", (err) => console.error("Redis error:", err));
15
15
 
16
- const OBSIDIAN_VAULT_PATH = process.env.OBSIDIAN_VAULT_PATH || "/opt/obsidian-vault";
16
+ const OBSIDIAN_VAULT_PATH = path.resolve(process.env.OBSIDIAN_VAULT_PATH || "/opt/obsidian-vault");
17
+ const VAULT_ROOT = OBSIDIAN_VAULT_PATH + path.sep;
17
18
 
18
19
  // ---------------------------------------------------------------------------
19
- // BM25 Index
20
+ // Auth middleware — set MCP_AUTH_TOKEN env var to enforce bearer token auth.
21
+ // If unset, access is unrestricted (warn loudly).
22
+ // ---------------------------------------------------------------------------
23
+
24
+ const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN || "";
25
+ if (!MCP_AUTH_TOKEN) {
26
+ console.warn("⚠️ SECURITY WARNING: MCP_AUTH_TOKEN is not set. All endpoints are unauthenticated. Set this env var to a secret token.");
27
+ }
28
+
29
+ function requireAuth(req, res, next) {
30
+ if (!MCP_AUTH_TOKEN) return next(); // auth disabled — allow (warned at startup)
31
+ const auth = req.headers.authorization || "";
32
+ if (!auth.startsWith("Bearer ") || auth.slice(7) !== MCP_AUTH_TOKEN) {
33
+ return res.status(401).json({ error: "Unauthorized" });
34
+ }
35
+ next();
36
+ }
37
+
38
+ // ---------------------------------------------------------------------------
39
+ // Key validation & path resolution — #1 path traversal fix
40
+ // ---------------------------------------------------------------------------
41
+
42
+ const SAFE_KEY_SEGMENT = /^[a-zA-Z0-9_\-\.]+$/;
43
+
44
+ function validateKey(key) {
45
+ if (typeof key !== "string" || key.length === 0 || key.length > 512)
46
+ throw new Error("invalid key: must be a non-empty string ≤ 512 chars");
47
+ if (/[\\/\x00]/.test(key))
48
+ throw new Error("invalid key: contains illegal characters");
49
+ const segments = key.split(":");
50
+ for (const seg of segments) {
51
+ if (seg === "" || seg === "." || seg === "..")
52
+ throw new Error("invalid key: empty or dot segment");
53
+ if (!SAFE_KEY_SEGMENT.test(seg))
54
+ throw new Error(`invalid key: segment '${seg}' contains illegal characters`);
55
+ }
56
+ }
57
+
58
+ function keyToObsidianPath(key) {
59
+ validateKey(key);
60
+ const relative = key.replace(/:/g, path.sep) + ".md";
61
+ const resolved = path.resolve(OBSIDIAN_VAULT_PATH, relative);
62
+ if (resolved !== OBSIDIAN_VAULT_PATH && !resolved.startsWith(VAULT_ROOT))
63
+ throw new Error("invalid key: path escapes vault");
64
+ return resolved;
65
+ }
66
+
67
+ // ---------------------------------------------------------------------------
68
+ // BM25 Index — fixes: drop tokens array (#13), O(N²) rebuild (#5),
69
+ // pending-ops queue to survive rebuild (#4), tier validation (#15)
20
70
  // ---------------------------------------------------------------------------
21
71
 
22
72
  const STOPWORDS = new Set([
@@ -30,8 +80,9 @@ const STOPWORDS = new Set([
30
80
  "if","up","out","about","into","through","over","after","before","between"
31
81
  ]);
32
82
 
33
- // Low-signal session metadata patterns — excluded from search by default
34
- const NOISE_KEY_PATTERNS = [/session-summary/, /agent-end/, /heartbeat/];
83
+ const VALID_TIERS = new Set(["all", "longterm", "working"]);
84
+
85
+ const NOISE_KEY_PATTERNS = [/session-summary/, /agent-end/, /heartbeat/];
35
86
  const NOISE_CONTENT_PATTERNS = [
36
87
  /^\d+ user turns,\s*\d+ total messages/i,
37
88
  /^openclaw session on [a-z0-9-]+:/i,
@@ -40,16 +91,16 @@ const NOISE_CONTENT_PATTERNS = [
40
91
 
41
92
  function isSessionNoise(key, content) {
42
93
  if (NOISE_KEY_PATTERNS.some(p => p.test(key))) return true;
43
- const trimmed = (content || "").trim();
44
- return NOISE_CONTENT_PATTERNS.some(p => p.test(trimmed));
94
+ return NOISE_CONTENT_PATTERNS.some(p => p.test((content || "").trim()));
45
95
  }
46
96
 
47
97
  class BM25Index {
48
98
  constructor(k1 = 1.5, b = 0.75) {
49
99
  this.k1 = k1;
50
100
  this.b = b;
51
- this.docs = new Map(); // key -> { tf, tokens, content, tier, updatedAt }
52
- this.df = new Map(); // term -> document frequency count
101
+ // doc entry: { tf: Map<term,count>, dl: number, content: string, tier: string, updatedAt: string|null }
102
+ this.docs = new Map();
103
+ this.df = new Map(); // term -> document frequency
53
104
  this.avgLen = 0;
54
105
  this.N = 0;
55
106
  }
@@ -62,16 +113,30 @@ class BM25Index {
62
113
  .filter(t => t.length > 1 && !STOPWORDS.has(t));
63
114
  }
64
115
 
116
+ // Single-doc add — used for incremental updates; calls _recalcStats each time
65
117
  add(key, content, tier, updatedAt) {
66
118
  if (this.docs.has(key)) this._removeFromIndex(key);
67
119
  const tokens = this.tokenize(content);
68
120
  const tf = new Map();
69
121
  for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
70
- this.docs.set(key, { tf, tokens, content, tier, updatedAt });
122
+ this.docs.set(key, { tf, dl: tokens.length, content, tier, updatedAt });
71
123
  for (const term of tf.keys()) this.df.set(term, (this.df.get(term) || 0) + 1);
72
124
  this._recalcStats();
73
125
  }
74
126
 
127
+ // Bulk add — O(N log N) instead of O(N²); calls _recalcStats once at end
128
+ bulkAdd(entries) {
129
+ for (const { key, content, tier, updatedAt } of entries) {
130
+ if (this.docs.has(key)) this._removeFromIndex(key);
131
+ const tokens = this.tokenize(content);
132
+ const tf = new Map();
133
+ for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
134
+ this.docs.set(key, { tf, dl: tokens.length, content, tier, updatedAt });
135
+ for (const term of tf.keys()) this.df.set(term, (this.df.get(term) || 0) + 1);
136
+ }
137
+ this._recalcStats();
138
+ }
139
+
75
140
  remove(key) {
76
141
  if (!this.docs.has(key)) return;
77
142
  this._removeFromIndex(key);
@@ -82,9 +147,9 @@ class BM25Index {
82
147
  const doc = this.docs.get(key);
83
148
  if (!doc) return;
84
149
  for (const term of doc.tf.keys()) {
85
- const count = this.df.get(term) || 0;
86
- if (count <= 1) this.df.delete(term);
87
- else this.df.set(term, count - 1);
150
+ const c = this.df.get(term) || 0;
151
+ if (c <= 1) this.df.delete(term);
152
+ else this.df.set(term, c - 1);
88
153
  }
89
154
  this.docs.delete(key);
90
155
  }
@@ -93,41 +158,40 @@ class BM25Index {
93
158
  this.N = this.docs.size;
94
159
  if (this.N === 0) { this.avgLen = 0; return; }
95
160
  let total = 0;
96
- for (const doc of this.docs.values()) total += doc.tokens.length;
161
+ for (const doc of this.docs.values()) total += doc.dl;
97
162
  this.avgLen = total / this.N;
98
163
  }
99
164
 
100
165
  _scoreDoc(queryTokens, docKey) {
101
166
  const doc = this.docs.get(docKey);
102
167
  if (!doc) return 0;
103
- const dl = doc.tokens.length;
104
- const lenNorm = this.avgLen > 0 ? dl / this.avgLen : 1;
168
+ const lenNorm = this.avgLen > 0 ? doc.dl / this.avgLen : 1;
105
169
  let score = 0;
106
170
  for (const term of queryTokens) {
107
171
  const tf = doc.tf.get(term) || 0;
108
172
  if (tf === 0) continue;
109
- const df = this.df.get(term) || 0;
173
+ const df = this.df.get(term) || 0;
110
174
  const idf = Math.log((this.N - df + 0.5) / (df + 0.5) + 1);
111
- const tfNorm = (tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + this.b * lenNorm));
112
- score += idf * tfNorm;
175
+ const tfn = (tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + this.b * lenNorm));
176
+ score += idf * tfn;
113
177
  }
114
178
  return score;
115
179
  }
116
180
 
117
181
  search(query, { limit = 10, tier = "all", minScore = 0, noiseFilter = true, namespace = null } = {}) {
182
+ const safeTier = VALID_TIERS.has(tier) ? tier : "all";
183
+ const safeLimit = Math.max(1, Math.min(Number.isFinite(limit) ? Math.floor(limit) : 10, 50));
118
184
  const queryTokens = this.tokenize(query);
119
185
  if (queryTokens.length === 0) return [];
120
186
  const results = [];
121
187
  for (const [key, doc] of this.docs.entries()) {
122
- if (tier !== "all" && doc.tier !== tier) continue;
188
+ if (safeTier !== "all" && doc.tier !== safeTier) continue;
123
189
  if (namespace && !key.startsWith(namespace + ":")) continue;
124
190
  if (noiseFilter && isSessionNoise(key, doc.content)) continue;
125
191
  const score = this._scoreDoc(queryTokens, key);
126
- if (score > minScore) {
127
- results.push({ key, score, tier: doc.tier, content: doc.content, updated_at: doc.updatedAt });
128
- }
192
+ if (score > minScore) results.push({ key, score, tier: doc.tier, content: doc.content, updated_at: doc.updatedAt });
129
193
  }
130
- return results.sort((a, b) => b.score - a.score).slice(0, limit);
194
+ return results.sort((a, b) => b.score - a.score).slice(0, safeLimit);
131
195
  }
132
196
 
133
197
  get size() { return this.N; }
@@ -135,21 +199,40 @@ class BM25Index {
135
199
 
136
200
  const bm25 = new BM25Index();
137
201
 
202
+ // Pending-ops queue: writes/removes that occur during a rebuild are applied
203
+ // after the swap so they aren't silently discarded — fix #4
204
+ let isBuilding = false;
205
+ const pendingOps = [];
206
+
207
+ function indexAdd(key, content, tier, updatedAt) {
208
+ bm25.add(key, content, tier, updatedAt); // update live index for immediate search
209
+ if (isBuilding) pendingOps.push({ op: "add", key, content, tier, updatedAt });
210
+ }
211
+
212
+ function indexRemove(key) {
213
+ bm25.remove(key);
214
+ if (isBuilding) pendingOps.push({ op: "remove", key });
215
+ }
216
+
138
217
  // ---------------------------------------------------------------------------
139
- // Index Build & Maintenance
218
+ // Index build
140
219
  // ---------------------------------------------------------------------------
141
220
 
142
221
  async function buildIndex() {
143
- const freshIndex = new BM25Index();
222
+ if (isBuilding) return; // skip if already running
223
+ isBuilding = true;
224
+ pendingOps.length = 0;
225
+
226
+ const entries = [];
144
227
 
145
- // Scan all Redis keys
146
- let redisCount = 0;
228
+ // Scan Redis — use TYPE: "string" to skip hashes/lists/sets
147
229
  try {
148
- for await (const key of redis.scanIterator({ MATCH: "*", COUNT: 200 })) {
149
- const val = await redis.get(key);
150
- if (val) {
151
- freshIndex.add(key, val, "longterm", null);
152
- redisCount++;
230
+ for await (const key of redis.scanIterator({ MATCH: "*", COUNT: 200, TYPE: "string" })) {
231
+ try {
232
+ const val = await redis.get(key);
233
+ if (val) entries.push({ key, content: val, tier: "longterm", updatedAt: null });
234
+ } catch (e) {
235
+ console.warn(`Index build — skipping key '${key}': ${e.message}`);
153
236
  }
154
237
  }
155
238
  } catch (e) {
@@ -157,22 +240,20 @@ async function buildIndex() {
157
240
  }
158
241
 
159
242
  // Walk Obsidian vault
160
- let vaultCount = 0;
161
243
  async function walk(dir) {
162
- let entries;
163
- try { entries = await fs.readdir(dir, { withFileTypes: true }); }
244
+ let items;
245
+ try { items = await fs.readdir(dir, { withFileTypes: true }); }
164
246
  catch (e) { if (e.code === "ENOENT") return; throw e; }
165
- for (const entry of entries) {
247
+ for (const entry of items) {
166
248
  const fullPath = path.join(dir, entry.name);
167
249
  if (entry.isDirectory()) { await walk(fullPath); continue; }
168
250
  if (!entry.name.endsWith(".md")) continue;
169
251
  try {
170
252
  const content = await fs.readFile(fullPath, "utf-8");
171
- const stat = await fs.stat(fullPath);
253
+ const stat = await fs.stat(fullPath);
172
254
  const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
173
- const key = relative.replace(/\//g, ":").replace(/\.md$/, "");
174
- freshIndex.add(key, content, "working", stat.mtime.toISOString());
175
- vaultCount++;
255
+ const key = relative.replace(/\//g, ":").replace(/\\/, ":").replace(/\.md$/, "");
256
+ entries.push({ key, content, tier: "working", updatedAt: stat.mtime.toISOString() });
176
257
  } catch (e) {
177
258
  console.error("Index build — vault read error:", fullPath, e.message);
178
259
  }
@@ -180,35 +261,41 @@ async function buildIndex() {
180
261
  }
181
262
  await walk(OBSIDIAN_VAULT_PATH);
182
263
 
183
- // Swap in new index atomically
184
- bm25.docs = freshIndex.docs;
185
- bm25.df = freshIndex.df;
186
- bm25.avgLen = freshIndex.avgLen;
187
- bm25.N = freshIndex.N;
264
+ // Build fresh index in bulk — O(N log N), no event-loop stall per doc
265
+ const fresh = new BM25Index();
266
+ fresh.bulkAdd(entries);
267
+
268
+ // Atomic field swap
269
+ bm25.docs = fresh.docs;
270
+ bm25.df = fresh.df;
271
+ bm25.avgLen = fresh.avgLen;
272
+ bm25.N = fresh.N;
273
+
274
+ // Re-apply writes/removes that occurred during the build
275
+ for (const op of pendingOps) {
276
+ if (op.op === "add") bm25.add(op.key, op.content, op.tier, op.updatedAt);
277
+ else if (op.op === "remove") bm25.remove(op.key);
278
+ }
279
+ pendingOps.length = 0;
280
+ isBuilding = false;
188
281
 
189
- console.log(`BM25 index built: ${redisCount} Redis keys + ${vaultCount} vault files = ${bm25.size} docs`);
282
+ console.log(`BM25 index built: ${bm25.size} docs (${entries.length} total entries scanned)`);
190
283
  }
191
284
 
192
285
  // ---------------------------------------------------------------------------
193
- // Obsidian Vault Helpers
286
+ // Obsidian vault helpers
194
287
  // ---------------------------------------------------------------------------
195
288
 
196
- function keyToObsidianPath(key) {
197
- const relativePath = key.replace(/:/g, "/") + ".md";
198
- return path.join(OBSIDIAN_VAULT_PATH, relativePath);
199
- }
200
-
201
289
  async function saveToObsidian(key, content, metadata) {
202
- const filePath = keyToObsidianPath(key);
290
+ const filePath = keyToObsidianPath(key); // throws on bad key
203
291
  await fs.mkdir(path.dirname(filePath), { recursive: true });
204
292
  let output = content;
205
293
  if (metadata && Object.keys(metadata).length > 0) {
206
- const frontmatter = ["---"];
207
- for (const [k, v] of Object.entries(metadata)) {
208
- frontmatter.push(`${k}: ${Array.isArray(v) ? `[${v.join(", ")}]` : v}`);
209
- }
210
- frontmatter.push("---", "");
211
- output = frontmatter.join("\n") + content;
294
+ const lines = ["---"];
295
+ for (const [k, v] of Object.entries(metadata))
296
+ lines.push(`${k}: ${Array.isArray(v) ? `[${v.join(", ")}]` : v}`);
297
+ lines.push("---", "");
298
+ output = lines.join("\n") + content;
212
299
  }
213
300
  await fs.writeFile(filePath, output, "utf-8");
214
301
  return filePath;
@@ -226,72 +313,74 @@ async function deleteFromObsidian(key) {
226
313
  catch (e) { if (e.code === "ENOENT") return false; throw e; }
227
314
  }
228
315
 
229
- async function searchObsidian(query) {
316
+ async function searchObsidian(query, namespace) {
230
317
  const results = [];
231
318
  async function walk(dir) {
232
- const entries = await fs.readdir(dir, { withFileTypes: true });
233
- for (const entry of entries) {
319
+ let items;
320
+ try { items = await fs.readdir(dir, { withFileTypes: true }); }
321
+ catch (e) { if (e.code === "ENOENT") return; throw e; }
322
+ for (const entry of items) {
234
323
  const fullPath = path.join(dir, entry.name);
235
324
  if (entry.isDirectory()) { await walk(fullPath); continue; }
236
325
  if (!entry.name.endsWith(".md")) continue;
237
326
  const content = await fs.readFile(fullPath, "utf-8");
238
- if (content.toLowerCase().includes(query.toLowerCase())) {
239
- const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
240
- const key = relative.replace(/\//g, ":").replace(/\.md$/, "");
241
- results.push({ key, content, path: relative });
242
- }
327
+ if (!content.toLowerCase().includes(query.toLowerCase())) continue;
328
+ const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
329
+ const key = relative.replace(/[\\/]/g, ":").replace(/\.md$/, "");
330
+ if (namespace && !key.startsWith(namespace + ":")) continue;
331
+ results.push({ key, content, path: relative });
243
332
  }
244
333
  }
245
- try { await walk(OBSIDIAN_VAULT_PATH); }
246
- catch (e) { if (e.code !== "ENOENT") throw e; }
334
+ await walk(OBSIDIAN_VAULT_PATH);
247
335
  return results;
248
336
  }
249
337
 
250
338
  async function listObsidian(prefix) {
251
339
  const results = [];
252
340
  async function walk(dir) {
253
- const entries = await fs.readdir(dir, { withFileTypes: true });
254
- for (const entry of entries) {
341
+ let items;
342
+ try { items = await fs.readdir(dir, { withFileTypes: true }); }
343
+ catch (e) { if (e.code === "ENOENT") return; throw e; }
344
+ for (const entry of items) {
255
345
  const fullPath = path.join(dir, entry.name);
256
346
  if (entry.isDirectory()) { await walk(fullPath); continue; }
257
347
  if (!entry.name.endsWith(".md")) continue;
258
348
  const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
259
- const key = relative.replace(/\//g, ":").replace(/\.md$/, "");
349
+ const key = relative.replace(/[\\/]/g, ":").replace(/\.md$/, "");
260
350
  if (!prefix || key.startsWith(prefix)) results.push({ key, path: relative });
261
351
  }
262
352
  }
263
- try { await walk(OBSIDIAN_VAULT_PATH); }
264
- catch (e) { if (e.code !== "ENOENT") throw e; }
353
+ await walk(OBSIDIAN_VAULT_PATH);
265
354
  return results;
266
355
  }
267
356
 
268
357
  // ---------------------------------------------------------------------------
269
- // MCP Server Factory
358
+ // MCP server factory
270
359
  // ---------------------------------------------------------------------------
271
360
 
272
361
  function createMcpServerInstance() {
273
- const server = new McpServer({
274
- name: "heurchain-mcp",
275
- version: "1.2.0"
276
- });
362
+ const server = new McpServer({ name: "heurchain-mcp", version: "1.2.1" });
277
363
 
278
364
  // --- Cache Tools ---
279
365
 
280
366
  server.tool("cache_set", "Store a key-value pair in Redis (longterm tier). Optionally scope to a namespace.", {
281
- key: z.string().describe("Cache key"),
282
- value: z.string().describe("Value to cache"),
283
- ttl: z.number().optional().describe("Time-to-live in seconds"),
367
+ key: z.string().describe("Cache key"),
368
+ value: z.string().describe("Value to cache"),
369
+ ttl: z.number().optional().describe("Time-to-live in seconds"),
284
370
  namespace: z.string().optional().describe("Optional namespace prefix, e.g. 'agent-hermes'. Key becomes namespace:key.")
285
371
  }, async ({ key, value, ttl, namespace }) => {
286
372
  const fullKey = namespace ? `${namespace}:${key}` : key;
373
+ try { validateKey(fullKey); } catch (e) {
374
+ return { content: [{ type: "text", text: JSON.stringify({ cached: false, error: e.message }) }] };
375
+ }
287
376
  if (ttl) await redis.setEx(fullKey, ttl, value);
288
377
  else await redis.set(fullKey, value);
289
- bm25.add(fullKey, value, "longterm", new Date().toISOString());
378
+ indexAdd(fullKey, value, "longterm", new Date().toISOString());
290
379
  return { content: [{ type: "text", text: JSON.stringify({ cached: true, key: fullKey }) }] };
291
380
  });
292
381
 
293
382
  server.tool("cache_get", "Retrieve a cached value from Redis by key", {
294
- key: z.string().describe("Cache key to retrieve"),
383
+ key: z.string().describe("Cache key to retrieve"),
295
384
  namespace: z.string().optional().describe("Namespace prefix used when storing")
296
385
  }, async ({ key, namespace }) => {
297
386
  const fullKey = namespace ? `${namespace}:${key}` : key;
@@ -301,12 +390,12 @@ function createMcpServerInstance() {
301
390
  });
302
391
 
303
392
  server.tool("cache_delete", "Delete a cached key from Redis", {
304
- key: z.string().describe("Cache key to delete"),
393
+ key: z.string().describe("Cache key to delete"),
305
394
  namespace: z.string().optional().describe("Namespace prefix used when storing")
306
395
  }, async ({ key, namespace }) => {
307
396
  const fullKey = namespace ? `${namespace}:${key}` : key;
308
397
  const deleted = await redis.del(fullKey);
309
- bm25.remove(fullKey);
398
+ indexRemove(fullKey);
310
399
  return { content: [{ type: "text", text: JSON.stringify({ deleted: deleted > 0, key: fullKey }) }] };
311
400
  });
312
401
 
@@ -319,41 +408,36 @@ function createMcpServerInstance() {
319
408
  const redisOk = redis.isReady;
320
409
  let obsidianOk = false;
321
410
  try { await fs.access(OBSIDIAN_VAULT_PATH); obsidianOk = true; } catch {}
322
- return {
323
- content: [{
324
- type: "text",
325
- text: JSON.stringify({
326
- status: (redisOk && obsidianOk) ? "healthy" : "degraded",
327
- redis: redisOk,
328
- obsidian: obsidianOk,
329
- vault_path: OBSIDIAN_VAULT_PATH,
330
- bm25_docs: bm25.size,
331
- uptime: process.uptime()
332
- })
333
- }]
334
- };
411
+ return { content: [{ type: "text", text: JSON.stringify({
412
+ status: (redisOk && obsidianOk) ? "healthy" : "degraded",
413
+ redis: redisOk, obsidian: obsidianOk,
414
+ vault_path: OBSIDIAN_VAULT_PATH,
415
+ bm25_docs: bm25.size,
416
+ uptime: process.uptime()
417
+ }) }] };
335
418
  });
336
419
 
337
- // --- Obsidian Vault Tools (Working Tier / Human-Readable Glacier) ---
420
+ // --- Obsidian Vault Tools ---
338
421
 
339
- server.tool("obsidian_write_note", "Write a markdown note to the Obsidian vault (working tier — human-readable glacier). Key colons become folder separators.", {
340
- key: z.string().describe("Note key (e.g. doc:proxmox:setup)"),
341
- content: z.string().describe("Markdown body"),
342
- metadata: z.record(z.string()).optional().describe("Optional frontmatter metadata"),
422
+ server.tool("obsidian_write_note", "Write a markdown note to the Obsidian vault (working tier). Key colons become folder separators.", {
423
+ key: z.string().describe("Note key (e.g. doc:proxmox:setup)"),
424
+ content: z.string().describe("Markdown body"),
425
+ metadata: z.record(z.string()).optional().describe("Optional frontmatter metadata"),
343
426
  namespace: z.string().optional().describe("Optional namespace prefix")
344
427
  }, async ({ key, content, metadata, namespace }) => {
345
428
  const fullKey = namespace ? `${namespace}:${key}` : key;
346
429
  try {
347
430
  const filePath = await saveToObsidian(fullKey, content, metadata);
348
- bm25.add(fullKey, content, "working", new Date().toISOString());
431
+ indexAdd(fullKey, content, "working", new Date().toISOString());
349
432
  return { content: [{ type: "text", text: JSON.stringify({ stored: true, key: fullKey, path: filePath, tier: "working" }) }] };
350
433
  } catch (e) {
351
- return { content: [{ type: "text", text: JSON.stringify({ stored: false, key: fullKey, error: e.message }) }] };
434
+ console.error(`obsidian_write_note error for key '${fullKey}':`, e);
435
+ return { content: [{ type: "text", text: JSON.stringify({ stored: false, key: fullKey, error: e.message.startsWith("invalid key") ? e.message : "write failed" }) }] };
352
436
  }
353
437
  });
354
438
 
355
439
  server.tool("obsidian_read_note", "Read a markdown note from the Obsidian vault by key", {
356
- key: z.string().describe("Note key"),
440
+ key: z.string().describe("Note key"),
357
441
  namespace: z.string().optional().describe("Namespace prefix used when storing")
358
442
  }, async ({ key, namespace }) => {
359
443
  const fullKey = namespace ? `${namespace}:${key}` : key;
@@ -362,39 +446,41 @@ function createMcpServerInstance() {
362
446
  if (content === null) return { content: [{ type: "text", text: JSON.stringify({ found: false, key: fullKey }) }] };
363
447
  return { content: [{ type: "text", text: JSON.stringify({ found: true, key: fullKey, content }) }] };
364
448
  } catch (e) {
365
- return { content: [{ type: "text", text: JSON.stringify({ found: false, key: fullKey, error: e.message }) }] };
449
+ console.error(`obsidian_read_note error for key '${fullKey}':`, e);
450
+ return { content: [{ type: "text", text: JSON.stringify({ found: false, key: fullKey, error: e.message.startsWith("invalid key") ? e.message : "read failed" }) }] };
366
451
  }
367
452
  });
368
453
 
369
454
  server.tool("obsidian_delete_note", "Delete a markdown note from the Obsidian vault by key", {
370
- key: z.string().describe("Note key to delete"),
455
+ key: z.string().describe("Note key to delete"),
371
456
  namespace: z.string().optional().describe("Namespace prefix used when storing")
372
457
  }, async ({ key, namespace }) => {
373
458
  const fullKey = namespace ? `${namespace}:${key}` : key;
374
459
  try {
375
460
  const deleted = await deleteFromObsidian(fullKey);
376
- bm25.remove(fullKey);
461
+ indexRemove(fullKey);
377
462
  return { content: [{ type: "text", text: JSON.stringify({ deleted, key: fullKey }) }] };
378
463
  } catch (e) {
379
- return { content: [{ type: "text", text: JSON.stringify({ deleted: false, key: fullKey, error: e.message }) }] };
464
+ console.error(`obsidian_delete_note error for key '${fullKey}':`, e);
465
+ return { content: [{ type: "text", text: JSON.stringify({ deleted: false, key: fullKey, error: e.message.startsWith("invalid key") ? e.message : "delete failed" }) }] };
380
466
  }
381
467
  });
382
468
 
383
- server.tool("obsidian_search_notes", "Search markdown notes in the Obsidian vault by keyword (substring match, vault only). Prefer heurchain_search for ranked results across all tiers.", {
384
- query: z.string().describe("Search term"),
385
- limit: z.number().optional().describe("Max results").default(10),
469
+ server.tool("obsidian_search_notes", "Search markdown notes in the Obsidian vault by keyword (substring, vault only). Prefer heurchain_search for ranked results across all tiers.", {
470
+ query: z.string().describe("Search term"),
471
+ limit: z.number().optional().describe("Max results (1–100, default 10)").default(10),
386
472
  namespace: z.string().optional().describe("Restrict to a namespace prefix")
387
473
  }, async ({ query, limit, namespace }) => {
474
+ const safeLimit = Math.max(1, Math.min(Number.isFinite(limit) ? Math.floor(limit) : 10, 100));
388
475
  try {
389
- let results = await searchObsidian(query);
390
- if (namespace) results = results.filter(r => r.key.startsWith(namespace + ":"));
391
- const sliced = results.slice(0, limit);
476
+ const results = await searchObsidian(query, namespace || null);
392
477
  return { content: [{ type: "text", text: JSON.stringify({
393
478
  count: results.length,
394
- results: sliced.map(r => ({ key: r.key, preview: r.content.substring(0, 200) }))
479
+ results: results.slice(0, safeLimit).map(r => ({ key: r.key, preview: r.content.substring(0, 200) }))
395
480
  }) }] };
396
481
  } catch (e) {
397
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
482
+ console.error("obsidian_search_notes error:", e);
483
+ return { content: [{ type: "text", text: JSON.stringify({ error: "search failed" }) }] };
398
484
  }
399
485
  });
400
486
 
@@ -405,20 +491,21 @@ function createMcpServerInstance() {
405
491
  const results = await listObsidian(prefix);
406
492
  return { content: [{ type: "text", text: JSON.stringify({ count: results.length, notes: results }) }] };
407
493
  } catch (e) {
408
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
494
+ console.error("obsidian_list_notes error:", e);
495
+ return { content: [{ type: "text", text: JSON.stringify({ error: "list failed" }) }] };
409
496
  }
410
497
  });
411
498
 
412
- // --- HeurChain BM25 Search (native, in-process) ---
499
+ // --- HeurChain BM25 Search ---
413
500
 
414
501
  server.tool("heurchain_search",
415
- "Search the full knowledge base using HeurChain's native BM25 ranked index. Covers all Redis keys (longterm tier) and Obsidian vault files (working tier) with relevance scoring. Preferred over obsidian_search_notes.", {
416
- query: z.string().describe("Search query"),
417
- limit: z.number().optional().describe("Max results (default 10, max 50)").default(10),
418
- tier: z.string().optional().describe("'all' | 'longterm' | 'working' (default: all)").default("all"),
419
- minScore: z.number().optional().describe("Minimum BM25 score threshold (default 0 = all results; try 0.5 to cut noise)").default(0),
420
- noiseFilter: z.boolean().optional().describe("Skip low-signal session metadata entries (default true)").default(true),
421
- namespace: z.string().optional().describe("Restrict search to a namespace, e.g. 'agent-hermes'")
502
+ "Search the full knowledge base using HeurChain's native BM25 ranked index. Covers all Redis keys (longterm) and Obsidian vault files (working). Preferred over obsidian_search_notes.", {
503
+ query: z.string().describe("Search query"),
504
+ limit: z.number().optional().describe("Max results (default 10, max 50)").default(10),
505
+ tier: z.string().optional().describe("'all' | 'longterm' | 'working' (default: all)").default("all"),
506
+ minScore: z.number().optional().describe("Minimum BM25 score (default 0; try 0.5 to reduce noise)").default(0),
507
+ noiseFilter: z.boolean().optional().describe("Skip low-signal session metadata (default true)").default(true),
508
+ namespace: z.string().optional().describe("Restrict to a namespace, e.g. 'agent-hermes'")
422
509
  }, async ({ query, limit, tier, minScore, noiseFilter, namespace }) => {
423
510
  try {
424
511
  const results = bm25.search(query, {
@@ -440,20 +527,23 @@ function createMcpServerInstance() {
440
527
  }))
441
528
  }) }] };
442
529
  } catch (e) {
443
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
530
+ console.error("heurchain_search error:", e);
531
+ return { content: [{ type: "text", text: JSON.stringify({ error: "search failed" }) }] };
444
532
  }
445
533
  });
446
534
 
447
535
  // --- heurchain_export (Glacier Sync) ---
448
536
 
449
537
  server.tool("heurchain_export",
450
- "Export Redis longterm-tier entries to Obsidian vault markdown files. Makes the Redis knowledge base human-readable and browsable. Idempotent — safe to run repeatedly.", {
451
- prefix: z.string().optional().describe("Only export keys matching this prefix (e.g. 'doc:', 'memory:'). Defaults to all keys."),
538
+ "Export Redis longterm-tier entries to Obsidian vault markdown files. Makes the Redis knowledge base human-readable. Idempotent — safe to run repeatedly.", {
539
+ prefix: z.string().optional().describe("Only export keys matching this prefix (e.g. 'doc:'). Defaults to all keys."),
452
540
  overwrite: z.boolean().optional().describe("Overwrite existing vault files (default false — skip if file exists)").default(false)
453
541
  }, async ({ prefix, overwrite }) => {
454
542
  let exported = 0, skipped = 0, errors = 0;
455
543
  try {
456
- for await (const key of redis.scanIterator({ MATCH: prefix ? `${prefix}*` : "*", COUNT: 100 })) {
544
+ for await (const key of redis.scanIterator({ MATCH: prefix ? `${prefix}*` : "*", COUNT: 100, TYPE: "string" })) {
545
+ // skip keys that would fail path validation
546
+ try { validateKey(key); } catch { skipped++; continue; }
457
547
  const val = await redis.get(key);
458
548
  if (!val) continue;
459
549
  const filePath = keyToObsidianPath(key);
@@ -462,18 +552,23 @@ function createMcpServerInstance() {
462
552
  }
463
553
  try {
464
554
  await fs.mkdir(path.dirname(filePath), { recursive: true });
465
- const header = `---\nkey: ${key}\nexported_at: ${new Date().toISOString()}\nsource: redis-longterm\n---\n\n`;
555
+ // avoid double-frontmatter if the Redis value already starts with ---
556
+ const hasFrontmatter = val.trimStart().startsWith("---");
557
+ const header = hasFrontmatter
558
+ ? `<!-- exported: key=${key} at ${new Date().toISOString()} -->\n\n`
559
+ : `---\nkey: ${key}\nexported_at: ${new Date().toISOString()}\nsource: redis-longterm\n---\n\n`;
466
560
  await fs.writeFile(filePath, header + val, "utf-8");
467
- bm25.add(key, val, "longterm", new Date().toISOString());
561
+ indexAdd(key, val, "longterm", new Date().toISOString());
468
562
  exported++;
469
563
  } catch (e) {
470
- console.error(`heurchain_export: failed to write ${key}:`, e.message);
564
+ console.error(`heurchain_export: failed to write '${key}':`, e.message);
471
565
  errors++;
472
566
  }
473
567
  }
474
568
  return { content: [{ type: "text", text: JSON.stringify({ exported, skipped, errors, vault_path: OBSIDIAN_VAULT_PATH }) }] };
475
569
  } catch (e) {
476
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message, exported, skipped, errors }) }] };
570
+ console.error("heurchain_export error:", e);
571
+ return { content: [{ type: "text", text: JSON.stringify({ error: "export failed", exported, skipped, errors }) }] };
477
572
  }
478
573
  });
479
574
 
@@ -489,7 +584,7 @@ function createMcpServerInstance() {
489
584
  }));
490
585
  return { content: [{ type: "text", text: JSON.stringify({ targets }) }] };
491
586
  } catch (e) {
492
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
587
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
493
588
  }
494
589
  });
495
590
 
@@ -500,7 +595,7 @@ function createMcpServerInstance() {
500
595
  const data = await response.json();
501
596
  return { content: [{ type: "text", text: JSON.stringify({ alerts: data.data.alerts }) }] };
502
597
  } catch (e) {
503
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
598
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
504
599
  }
505
600
  });
506
601
 
@@ -513,60 +608,68 @@ function createMcpServerInstance() {
513
608
  const data = await response.json();
514
609
  return { content: [{ type: "text", text: JSON.stringify(data.data) }] };
515
610
  } catch (e) {
516
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
611
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
517
612
  }
518
613
  });
519
614
 
520
- // --- Grafana Monitoring Tools ---
615
+ // --- Grafana Monitoring Tools — fail closed if creds not configured (#6) ---
616
+
617
+ const grafanaUser = process.env.GRAFANA_USER;
618
+ const grafanaPass = process.env.GRAFANA_PASSWORD;
619
+ const grafanaAuth = (grafanaUser && grafanaPass)
620
+ ? "Basic " + Buffer.from(`${grafanaUser}:${grafanaPass}`).toString("base64")
621
+ : null;
521
622
 
522
- const grafanaAuth = "Basic " + Buffer.from(`${process.env.GRAFANA_USER || "admin"}:${process.env.GRAFANA_PASSWORD || "admin"}`).toString("base64");
623
+ function grafanaHeaders() {
624
+ if (!grafanaAuth) throw new Error("Grafana credentials not configured (GRAFANA_USER / GRAFANA_PASSWORD not set)");
625
+ return { "Authorization": grafanaAuth };
626
+ }
523
627
 
524
628
  server.tool("grafana_get_health", "Check the health status of the Grafana server", {}, async () => {
525
629
  try {
526
- const response = await fetch("http://grafana:3000/api/health", { headers: { "Authorization": grafanaAuth } });
630
+ const response = await fetch("http://grafana:3000/api/health", { headers: grafanaHeaders() });
527
631
  if (!response.ok) return { content: [{ type: "text", text: JSON.stringify({ error: `HTTP ${response.status}` }) }] };
528
632
  return { content: [{ type: "text", text: JSON.stringify(await response.json()) }] };
529
633
  } catch (e) {
530
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
634
+ return { content: [{ type: "text", text: JSON.stringify({ error: e.message.includes("credentials") ? e.message : "request failed" }) }] };
531
635
  }
532
636
  });
533
637
 
534
638
  server.tool("grafana_list_dashboards", "List all available dashboards in Grafana", {}, async () => {
535
639
  try {
536
- const response = await fetch("http://grafana:3000/api/search?type=dash-db", { headers: { "Authorization": grafanaAuth } });
640
+ const response = await fetch("http://grafana:3000/api/search?type=dash-db", { headers: grafanaHeaders() });
537
641
  if (!response.ok) return { content: [{ type: "text", text: JSON.stringify({ error: `HTTP ${response.status}` }) }] };
538
642
  const dashboards = await response.json();
539
643
  return { content: [{ type: "text", text: JSON.stringify({ dashboards: dashboards.map(d => ({ title: d.title, url: d.url })) }) }] };
540
644
  } catch (e) {
541
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
645
+ return { content: [{ type: "text", text: JSON.stringify({ error: e.message.includes("credentials") ? e.message : "request failed" }) }] };
542
646
  }
543
647
  });
544
648
 
545
- // --- Proxmox Documentation Tools (Redis-backed) ---
649
+ // --- Proxmox Documentation Tools ---
546
650
 
547
651
  async function searchDocs(keyPattern, contentFilter) {
548
652
  const keys = [];
549
- for await (const key of redis.scanIterator({ MATCH: keyPattern, COUNT: 100 })) keys.push(key);
653
+ for await (const key of redis.scanIterator({ MATCH: keyPattern, COUNT: 100, TYPE: "string" })) keys.push(key);
550
654
  if (keys.length === 0) return [];
551
655
  const results = [];
552
656
  for (const key of keys) {
553
657
  const val = await redis.get(key);
554
- if (val && (!contentFilter || val.toLowerCase().includes(contentFilter.toLowerCase()))) {
658
+ if (val && (!contentFilter || val.toLowerCase().includes(contentFilter.toLowerCase())))
555
659
  results.push({ key, content: val });
556
- }
557
660
  }
558
661
  return results;
559
662
  }
560
663
 
561
664
  server.tool("proxmox_get_cluster_status", "Retrieve the Proxmox cluster status document from the knowledge base", {}, async () => {
562
665
  const results = await searchDocs("doc:proxmox:cluster-status*", null);
563
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: "No cluster status document found. Store one with key 'doc:proxmox:cluster-status' using cache_set." }) }] };
666
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No cluster status document found. Store one with key 'doc:proxmox:cluster-status' using cache_set." }) }] };
564
667
  return { content: [{ type: "text", text: results[0].content }] };
565
668
  });
566
669
 
567
670
  server.tool("proxmox_list_nodes", "List all Proxmox nodes documented in the knowledge base", {}, async () => {
568
671
  const results = await searchDocs("doc:proxmox:node:*", null);
569
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: "No node documents found. Store them with keys like 'doc:proxmox:node:pver430' using cache_set." }) }] };
672
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No node documents found." }) }] };
570
673
  return { content: [{ type: "text", text: JSON.stringify({ nodes: results.map(r => ({ key: r.key, title: r.key.split(":").pop() })) }) }] };
571
674
  });
572
675
 
@@ -574,33 +677,33 @@ function createMcpServerInstance() {
574
677
  vm_id_or_name: z.string().describe("VM ID or name to search for")
575
678
  }, async ({ vm_id_or_name }) => {
576
679
  let results = await searchDocs("doc:proxmox:vm:*", vm_id_or_name);
577
- if (results.length === 0) results = await searchDocs("doc:proxmox:ct:*", vm_id_or_name);
578
- if (results.length === 0) results = await searchDocs("doc:proxmox:*", vm_id_or_name);
579
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: `No VM or CT found matching "${vm_id_or_name}".` }) }] };
680
+ if (!results.length) results = await searchDocs("doc:proxmox:ct:*", vm_id_or_name);
681
+ if (!results.length) results = await searchDocs("doc:proxmox:*", vm_id_or_name);
682
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: `No VM or CT found matching "${vm_id_or_name}".` }) }] };
580
683
  return { content: [{ type: "text", text: results[0].content }] };
581
684
  });
582
685
 
583
- // --- Ceph Documentation Tools (Redis-backed) ---
686
+ // --- Ceph Documentation Tools ---
584
687
 
585
688
  server.tool("ceph_get_health_status", "Retrieve the latest Ceph cluster health status from the knowledge base", {}, async () => {
586
689
  const results = await searchDocs("doc:ceph:cluster-status*", null);
587
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: "No Ceph status document found. Store one with key 'doc:ceph:cluster-status' using cache_set." }) }] };
690
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No Ceph status document found." }) }] };
588
691
  return { content: [{ type: "text", text: results[0].content }] };
589
692
  });
590
693
 
591
694
  server.tool("ceph_list_osd_notes", "List all Ceph OSD documentation notes from the knowledge base", {}, async () => {
592
695
  const results = await searchDocs("doc:ceph:osd:*", null);
593
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: "No OSD documents found. Store them with keys like 'doc:ceph:osd:0' using cache_set." }) }] };
696
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No OSD documents found." }) }] };
594
697
  return { content: [{ type: "text", text: JSON.stringify({ osd_notes: results.map(r => r.key) }) }] };
595
698
  });
596
699
 
597
- // --- Network Documentation Tools (Redis-backed) ---
700
+ // --- Network Documentation Tools ---
598
701
 
599
702
  server.tool("network_search_docs", "Search across network and infrastructure documentation in the knowledge base", {
600
703
  search_query: z.string().describe("Search query to find relevant documentation")
601
704
  }, async ({ search_query }) => {
602
705
  const results = [...await searchDocs("doc:network:*", search_query), ...await searchDocs("doc:infrastructure:*", search_query)];
603
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ status: "No relevant documents found." }) }] };
706
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ status: "No relevant documents found." }) }] };
604
707
  return { content: [{ type: "text", text: JSON.stringify({ results: results.slice(0, 5).map(r => ({ key: r.key, preview: r.content.substring(0, 200) })) }) }] };
605
708
  });
606
709
 
@@ -608,13 +711,13 @@ function createMcpServerInstance() {
608
711
  topic: z.string().describe("Runbook topic to search for")
609
712
  }, async ({ topic }) => {
610
713
  const results = await searchDocs("doc:runbook:*", topic);
611
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: `No runbook found for topic: "${topic}". Store runbooks with keys like 'doc:runbook:topic-name' using cache_set.` }) }] };
714
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: `No runbook found for topic: "${topic}".` }) }] };
612
715
  return { content: [{ type: "text", text: results[0].content }] };
613
716
  });
614
717
 
615
- // --- User Context Tools (Redis-backed) ---
718
+ // --- User Context Tools ---
616
719
 
617
- const USER_HISTORY_TTL = 90 * 24 * 60 * 60; // 90 days
720
+ const USER_HISTORY_TTL = 90 * 24 * 60 * 60;
618
721
 
619
722
  server.tool("user_context_add_entry", "Add an entry to a user's daily interaction history log", {
620
723
  user_id: z.string().describe("User identifier"),
@@ -624,30 +727,29 @@ function createMcpServerInstance() {
624
727
  const key = `doc:users:${user_id}:history:${today}`;
625
728
  let existing = await redis.get(key);
626
729
  if (!existing) existing = `## User History for ${user_id} - ${today}\n\n`;
627
- const timestamp = new Date().toLocaleTimeString();
628
- const entry = `**[${timestamp}]**\n${content}\n\n---\n\n`;
730
+ const entry = `**[${new Date().toLocaleTimeString()}]**\n${content}\n\n---\n\n`;
629
731
  const updated = existing + entry;
630
732
  await redis.setEx(key, USER_HISTORY_TTL, updated);
631
- bm25.add(key, updated, "longterm", new Date().toISOString());
632
- return { content: [{ type: "text", text: JSON.stringify({ success: true, key, entry_added: entry }) }] };
733
+ indexAdd(key, updated, "longterm", new Date().toISOString());
734
+ return { content: [{ type: "text", text: JSON.stringify({ success: true, key }) }] };
633
735
  });
634
736
 
635
737
  server.tool("user_context_get_history", "Retrieve the full interaction history for a user on a specific date", {
636
738
  user_id: z.string().describe("User identifier"),
637
- date: z.string().describe("Date in YYYY-MM-DD format")
739
+ date: z.string().describe("Date in YYYY-MM-DD format")
638
740
  }, async ({ user_id, date }) => {
639
741
  const key = `doc:users:${user_id}:history:${date}`;
640
742
  const val = await redis.get(key);
641
- if (!val) return { content: [{ type: "text", text: JSON.stringify({ status: "Not Found", message: `No history found for user '${user_id}' on date '${date}'.` }) }] };
743
+ if (!val) return { content: [{ type: "text", text: JSON.stringify({ status: "Not Found", message: `No history for user '${user_id}' on '${date}'.` }) }] };
642
744
  return { content: [{ type: "text", text: JSON.stringify({ user_id, date, history: val }) }] };
643
745
  });
644
746
 
645
747
  server.tool("user_context_search_history", "Search across all of a user's history documents by keyword", {
646
748
  user_id: z.string().describe("User identifier"),
647
- query: z.string().describe("Search query")
749
+ query: z.string().describe("Search query")
648
750
  }, async ({ user_id, query }) => {
649
751
  const results = await searchDocs(`doc:users:${user_id}:history:*`, query);
650
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ status: "No matches found." }) }] };
752
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ status: "No matches found." }) }] };
651
753
  return { content: [{ type: "text", text: JSON.stringify({
652
754
  results: results.map(r => ({ date: r.key.split(":").pop(), match_preview: r.content.substring(0, 200) + "..." }))
653
755
  }) }] };
@@ -657,20 +759,40 @@ function createMcpServerInstance() {
657
759
  }
658
760
 
659
761
  // ---------------------------------------------------------------------------
660
- // SSE Transport
762
+ // SSE transport — fix #3: max session cap + cleanup on error/close
661
763
  // ---------------------------------------------------------------------------
662
764
 
765
+ const MAX_SESSIONS = 50;
663
766
  const transports = {};
664
767
 
665
- app.get("/sse", async (req, res) => {
768
+ app.get("/sse", requireAuth, async (req, res) => {
769
+ if (Object.keys(transports).length >= MAX_SESSIONS) {
770
+ return res.status(503).json({ error: "Max concurrent sessions reached" });
771
+ }
666
772
  const transport = new SSEServerTransport("/messages", res);
667
773
  const mcpServer = createMcpServerInstance();
668
- transports[transport.sessionId] = { transport, server: mcpServer };
669
- res.on("close", () => { mcpServer.close(); delete transports[transport.sessionId]; });
670
- await mcpServer.connect(transport);
774
+ const sessionId = transport.sessionId;
775
+ transports[sessionId] = { transport, server: mcpServer };
776
+
777
+ const cleanup = () => {
778
+ if (!transports[sessionId]) return;
779
+ mcpServer.close().catch(() => {});
780
+ delete transports[sessionId];
781
+ };
782
+
783
+ res.on("close", cleanup);
784
+ req.on("close", cleanup);
785
+
786
+ try {
787
+ await mcpServer.connect(transport);
788
+ } catch (e) {
789
+ cleanup();
790
+ console.error("SSE connect error:", e.message);
791
+ if (!res.headersSent) res.status(500).json({ error: "Connection failed" });
792
+ }
671
793
  });
672
794
 
673
- app.post("/messages", async (req, res) => {
795
+ app.post("/messages", requireAuth, async (req, res) => {
674
796
  const sessionId = req.query.sessionId;
675
797
  const entry = transports[sessionId];
676
798
  if (entry) await entry.transport.handlePostMessage(req, res);
@@ -678,7 +800,7 @@ app.post("/messages", async (req, res) => {
678
800
  });
679
801
 
680
802
  // ---------------------------------------------------------------------------
681
- // REST API (backwards compatibility)
803
+ // REST API (backwards compatibility) — all routes require auth except /health
682
804
  // ---------------------------------------------------------------------------
683
805
 
684
806
  const jsonParser = express.json();
@@ -689,15 +811,14 @@ app.get("/health", async (req, res) => {
689
811
  try { await fs.access(OBSIDIAN_VAULT_PATH); obsidianOk = true; } catch {}
690
812
  res.json({
691
813
  status: (redisOk && obsidianOk) ? "healthy" : "degraded",
692
- redis: redisOk,
693
- obsidian: obsidianOk,
814
+ redis: redisOk, obsidian: obsidianOk,
694
815
  vault_path: OBSIDIAN_VAULT_PATH,
695
816
  bm25_docs: bm25.size,
696
817
  uptime: process.uptime()
697
818
  });
698
819
  });
699
820
 
700
- app.get("/api/tools", (req, res) => {
821
+ app.get("/api/tools", requireAuth, (req, res) => {
701
822
  res.json({ tools: [
702
823
  "cache_set", "cache_get", "cache_delete", "redis_stats", "health_check",
703
824
  "obsidian_write_note", "obsidian_read_note", "obsidian_delete_note",
@@ -712,64 +833,68 @@ app.get("/api/tools", (req, res) => {
712
833
  ]});
713
834
  });
714
835
 
715
- app.post("/api/cache", jsonParser, async (req, res) => {
836
+ app.post("/api/cache", requireAuth, jsonParser, async (req, res) => {
716
837
  const { key, value, ttl } = req.body;
717
838
  if (ttl) await redis.setEx(key, ttl, JSON.stringify(value));
718
839
  else await redis.set(key, JSON.stringify(value));
719
840
  res.json({ cached: true });
720
841
  });
721
842
 
722
- app.get("/api/cache/:key", async (req, res) => {
843
+ app.get("/api/cache/:key", requireAuth, async (req, res) => {
723
844
  const val = await redis.get(req.params.key);
724
845
  if (val) res.json({ hit: true, data: JSON.parse(val) });
725
846
  else res.json({ hit: false });
726
847
  });
727
848
 
728
- app.get("/api/stats", async (req, res) => {
849
+ app.get("/api/stats", requireAuth, async (req, res) => {
729
850
  const info = await redis.info("stats");
730
851
  res.json({ redis_info: info, bm25_docs: bm25.size });
731
852
  });
732
853
 
733
- // --- Obsidian REST Endpoints ---
734
-
735
- app.get("/api/obsidian/notes", async (req, res) => {
854
+ app.get("/api/obsidian/notes", requireAuth, async (req, res) => {
736
855
  const { key, prefix } = req.query;
737
856
  if (key) {
738
- const content = await readFromObsidian(key);
739
- if (content === null) return res.status(404).json({ found: false, key });
740
- return res.json({ found: true, key, content });
857
+ try {
858
+ const content = await readFromObsidian(key);
859
+ if (content === null) return res.status(404).json({ found: false, key });
860
+ return res.json({ found: true, key, content });
861
+ } catch (e) {
862
+ return res.status(400).json({ error: e.message.startsWith("invalid key") ? e.message : "read failed" });
863
+ }
741
864
  }
742
865
  const notes = await listObsidian(prefix);
743
866
  res.json({ count: notes.length, notes });
744
867
  });
745
868
 
746
- app.post("/api/obsidian/notes", jsonParser, async (req, res) => {
869
+ app.post("/api/obsidian/notes", requireAuth, jsonParser, async (req, res) => {
747
870
  const { key, content, metadata } = req.body;
748
871
  if (!key || content === undefined) return res.status(400).json({ error: "key and content required" });
749
872
  try {
750
873
  const filePath = await saveToObsidian(key, content, metadata);
751
874
  res.json({ stored: true, key, path: filePath });
752
875
  } catch (e) {
753
- res.status(500).json({ stored: false, error: e.message });
876
+ res.status(e.message.startsWith("invalid key") ? 400 : 500)
877
+ .json({ error: e.message.startsWith("invalid key") ? e.message : "write failed" });
754
878
  }
755
879
  });
756
880
 
757
- app.delete("/api/obsidian/notes", async (req, res) => {
881
+ app.delete("/api/obsidian/notes", requireAuth, async (req, res) => {
758
882
  const { key } = req.query;
759
883
  if (!key) return res.status(400).json({ error: "key required" });
760
- const deleted = await deleteFromObsidian(key);
761
- res.json({ deleted, key });
884
+ try {
885
+ const deleted = await deleteFromObsidian(key);
886
+ res.json({ deleted, key });
887
+ } catch (e) {
888
+ res.status(400).json({ error: e.message.startsWith("invalid key") ? e.message : "delete failed" });
889
+ }
762
890
  });
763
891
 
764
- app.get("/api/obsidian/search", async (req, res) => {
892
+ app.get("/api/obsidian/search", requireAuth, async (req, res) => {
765
893
  const { q, limit } = req.query;
766
894
  if (!q) return res.status(400).json({ error: "q required" });
767
- const results = await searchObsidian(q);
768
- const max = parseInt(limit) || 10;
769
- res.json({
770
- count: results.length,
771
- results: results.slice(0, max).map(r => ({ key: r.key, path: r.path, preview: r.content.substring(0, 200) }))
772
- });
895
+ const max = Math.max(1, Math.min(parseInt(limit) || 10, 100));
896
+ const results = await searchObsidian(q, null);
897
+ res.json({ count: results.length, results: results.slice(0, max).map(r => ({ key: r.key, path: r.path, preview: r.content.substring(0, 200) })) });
773
898
  });
774
899
 
775
900
  // ---------------------------------------------------------------------------
@@ -779,8 +904,7 @@ app.get("/api/obsidian/search", async (req, res) => {
779
904
  (async () => {
780
905
  await redis.connect();
781
906
  await buildIndex();
782
- // Rebuild index hourly to catch external writes
783
- setInterval(buildIndex, 60 * 60 * 1000);
907
+ setInterval(buildIndex, 60 * 60 * 1000); // hourly rebuild
784
908
  const port = parseInt(process.env.MCP_PORT, 10) || 3010;
785
- app.listen(port, () => console.log(`HeurChain MCP v1.2.0 listening on port ${port} — ${bm25.size} docs indexed`));
909
+ app.listen(port, () => console.log(`HeurChain MCP v1.2.1 listening on port ${port} — ${bm25.size} docs indexed`));
786
910
  })();