heurchain 1.1.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 +578 -269
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.1.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,35 +13,289 @@ 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";
17
- const HEURCHAIN_URL = process.env.HEURCHAIN_URL || "http://host.docker.internal:3012";
16
+ const OBSIDIAN_VAULT_PATH = path.resolve(process.env.OBSIDIAN_VAULT_PATH || "/opt/obsidian-vault");
17
+ const VAULT_ROOT = OBSIDIAN_VAULT_PATH + path.sep;
18
18
 
19
- (async () => {
20
- await redis.connect();
21
- const port = parseInt(process.env.MCP_PORT, 10) || 3010;
22
- app.listen(port, () => console.log("MCP server listening on port " + port));
23
- })();
19
+ // ---------------------------------------------------------------------------
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
+ }
24
37
 
25
38
  // ---------------------------------------------------------------------------
26
- // Obsidian Vault Helpers
39
+ // Key validation & path resolution — #1 path traversal fix
27
40
  // ---------------------------------------------------------------------------
28
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
+
29
58
  function keyToObsidianPath(key) {
30
- const relativePath = key.replace(/:/g, "/") + ".md";
31
- return path.join(OBSIDIAN_VAULT_PATH, relativePath);
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)
70
+ // ---------------------------------------------------------------------------
71
+
72
+ const STOPWORDS = new Set([
73
+ "a","an","the","and","or","but","in","on","at","to","for","of","with",
74
+ "by","from","as","is","was","are","were","be","been","being","have",
75
+ "has","had","do","does","did","will","would","could","should","may",
76
+ "might","shall","can","not","no","nor","so","yet","both","either",
77
+ "than","then","when","where","which","who","that","this","these","those",
78
+ "it","its","i","me","my","we","our","you","your","he","she","they","them",
79
+ "his","her","their","what","how","all","each","any","more","also","just",
80
+ "if","up","out","about","into","through","over","after","before","between"
81
+ ]);
82
+
83
+ const VALID_TIERS = new Set(["all", "longterm", "working"]);
84
+
85
+ const NOISE_KEY_PATTERNS = [/session-summary/, /agent-end/, /heartbeat/];
86
+ const NOISE_CONTENT_PATTERNS = [
87
+ /^\d+ user turns,\s*\d+ total messages/i,
88
+ /^openclaw session on [a-z0-9-]+:/i,
89
+ /^session ended\./i
90
+ ];
91
+
92
+ function isSessionNoise(key, content) {
93
+ if (NOISE_KEY_PATTERNS.some(p => p.test(key))) return true;
94
+ return NOISE_CONTENT_PATTERNS.some(p => p.test((content || "").trim()));
32
95
  }
33
96
 
97
+ class BM25Index {
98
+ constructor(k1 = 1.5, b = 0.75) {
99
+ this.k1 = k1;
100
+ this.b = b;
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
104
+ this.avgLen = 0;
105
+ this.N = 0;
106
+ }
107
+
108
+ tokenize(text) {
109
+ return (text || "")
110
+ .toLowerCase()
111
+ .replace(/[^a-z0-9\s]/g, " ")
112
+ .split(/\s+/)
113
+ .filter(t => t.length > 1 && !STOPWORDS.has(t));
114
+ }
115
+
116
+ // Single-doc add — used for incremental updates; calls _recalcStats each time
117
+ add(key, content, tier, updatedAt) {
118
+ if (this.docs.has(key)) this._removeFromIndex(key);
119
+ const tokens = this.tokenize(content);
120
+ const tf = new Map();
121
+ for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
122
+ this.docs.set(key, { tf, dl: tokens.length, content, tier, updatedAt });
123
+ for (const term of tf.keys()) this.df.set(term, (this.df.get(term) || 0) + 1);
124
+ this._recalcStats();
125
+ }
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
+
140
+ remove(key) {
141
+ if (!this.docs.has(key)) return;
142
+ this._removeFromIndex(key);
143
+ this._recalcStats();
144
+ }
145
+
146
+ _removeFromIndex(key) {
147
+ const doc = this.docs.get(key);
148
+ if (!doc) return;
149
+ for (const term of doc.tf.keys()) {
150
+ const c = this.df.get(term) || 0;
151
+ if (c <= 1) this.df.delete(term);
152
+ else this.df.set(term, c - 1);
153
+ }
154
+ this.docs.delete(key);
155
+ }
156
+
157
+ _recalcStats() {
158
+ this.N = this.docs.size;
159
+ if (this.N === 0) { this.avgLen = 0; return; }
160
+ let total = 0;
161
+ for (const doc of this.docs.values()) total += doc.dl;
162
+ this.avgLen = total / this.N;
163
+ }
164
+
165
+ _scoreDoc(queryTokens, docKey) {
166
+ const doc = this.docs.get(docKey);
167
+ if (!doc) return 0;
168
+ const lenNorm = this.avgLen > 0 ? doc.dl / this.avgLen : 1;
169
+ let score = 0;
170
+ for (const term of queryTokens) {
171
+ const tf = doc.tf.get(term) || 0;
172
+ if (tf === 0) continue;
173
+ const df = this.df.get(term) || 0;
174
+ const idf = Math.log((this.N - df + 0.5) / (df + 0.5) + 1);
175
+ const tfn = (tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + this.b * lenNorm));
176
+ score += idf * tfn;
177
+ }
178
+ return score;
179
+ }
180
+
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));
184
+ const queryTokens = this.tokenize(query);
185
+ if (queryTokens.length === 0) return [];
186
+ const results = [];
187
+ for (const [key, doc] of this.docs.entries()) {
188
+ if (safeTier !== "all" && doc.tier !== safeTier) continue;
189
+ if (namespace && !key.startsWith(namespace + ":")) continue;
190
+ if (noiseFilter && isSessionNoise(key, doc.content)) continue;
191
+ const score = this._scoreDoc(queryTokens, key);
192
+ if (score > minScore) results.push({ key, score, tier: doc.tier, content: doc.content, updated_at: doc.updatedAt });
193
+ }
194
+ return results.sort((a, b) => b.score - a.score).slice(0, safeLimit);
195
+ }
196
+
197
+ get size() { return this.N; }
198
+ }
199
+
200
+ const bm25 = new BM25Index();
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
+
217
+ // ---------------------------------------------------------------------------
218
+ // Index build
219
+ // ---------------------------------------------------------------------------
220
+
221
+ async function buildIndex() {
222
+ if (isBuilding) return; // skip if already running
223
+ isBuilding = true;
224
+ pendingOps.length = 0;
225
+
226
+ const entries = [];
227
+
228
+ // Scan Redis — use TYPE: "string" to skip hashes/lists/sets
229
+ try {
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}`);
236
+ }
237
+ }
238
+ } catch (e) {
239
+ console.error("Index build — Redis scan error:", e.message);
240
+ }
241
+
242
+ // Walk Obsidian vault
243
+ async function walk(dir) {
244
+ let items;
245
+ try { items = await fs.readdir(dir, { withFileTypes: true }); }
246
+ catch (e) { if (e.code === "ENOENT") return; throw e; }
247
+ for (const entry of items) {
248
+ const fullPath = path.join(dir, entry.name);
249
+ if (entry.isDirectory()) { await walk(fullPath); continue; }
250
+ if (!entry.name.endsWith(".md")) continue;
251
+ try {
252
+ const content = await fs.readFile(fullPath, "utf-8");
253
+ const stat = await fs.stat(fullPath);
254
+ const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
255
+ const key = relative.replace(/\//g, ":").replace(/\\/, ":").replace(/\.md$/, "");
256
+ entries.push({ key, content, tier: "working", updatedAt: stat.mtime.toISOString() });
257
+ } catch (e) {
258
+ console.error("Index build — vault read error:", fullPath, e.message);
259
+ }
260
+ }
261
+ }
262
+ await walk(OBSIDIAN_VAULT_PATH);
263
+
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;
281
+
282
+ console.log(`BM25 index built: ${bm25.size} docs (${entries.length} total entries scanned)`);
283
+ }
284
+
285
+ // ---------------------------------------------------------------------------
286
+ // Obsidian vault helpers
287
+ // ---------------------------------------------------------------------------
288
+
34
289
  async function saveToObsidian(key, content, metadata) {
35
- const filePath = keyToObsidianPath(key);
290
+ const filePath = keyToObsidianPath(key); // throws on bad key
36
291
  await fs.mkdir(path.dirname(filePath), { recursive: true });
37
292
  let output = content;
38
293
  if (metadata && Object.keys(metadata).length > 0) {
39
- const frontmatter = ["---"];
40
- for (const [k, v] of Object.entries(metadata)) {
41
- frontmatter.push(`${k}: ${Array.isArray(v) ? `[${v.join(", ")}]` : v}`);
42
- }
43
- frontmatter.push("---", "");
44
- 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;
45
299
  }
46
300
  await fs.writeFile(filePath, output, "utf-8");
47
301
  return filePath;
@@ -49,111 +303,100 @@ async function saveToObsidian(key, content, metadata) {
49
303
 
50
304
  async function readFromObsidian(key) {
51
305
  const filePath = keyToObsidianPath(key);
52
- try {
53
- return await fs.readFile(filePath, "utf-8");
54
- } catch (e) {
55
- if (e.code === "ENOENT") return null;
56
- throw e;
57
- }
306
+ try { return await fs.readFile(filePath, "utf-8"); }
307
+ catch (e) { if (e.code === "ENOENT") return null; throw e; }
58
308
  }
59
309
 
60
310
  async function deleteFromObsidian(key) {
61
311
  const filePath = keyToObsidianPath(key);
62
- try {
63
- await fs.unlink(filePath);
64
- return true;
65
- } catch (e) {
66
- if (e.code === "ENOENT") return false;
67
- throw e;
68
- }
312
+ try { await fs.unlink(filePath); return true; }
313
+ catch (e) { if (e.code === "ENOENT") return false; throw e; }
69
314
  }
70
315
 
71
- async function searchObsidian(query) {
316
+ async function searchObsidian(query, namespace) {
72
317
  const results = [];
73
318
  async function walk(dir) {
74
- const entries = await fs.readdir(dir, { withFileTypes: true });
75
- 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) {
76
323
  const fullPath = path.join(dir, entry.name);
77
- if (entry.isDirectory()) {
78
- await walk(fullPath);
79
- } else if (entry.name.endsWith(".md")) {
80
- const content = await fs.readFile(fullPath, "utf-8");
81
- if (content.toLowerCase().includes(query.toLowerCase())) {
82
- const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
83
- const key = relative.replace(/\//g, ":").replace(/\.md$/, "");
84
- results.push({ key, content, path: relative });
85
- }
86
- }
324
+ if (entry.isDirectory()) { await walk(fullPath); continue; }
325
+ if (!entry.name.endsWith(".md")) continue;
326
+ const content = await fs.readFile(fullPath, "utf-8");
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 });
87
332
  }
88
333
  }
89
- try {
90
- await walk(OBSIDIAN_VAULT_PATH);
91
- } catch (e) {
92
- if (e.code !== "ENOENT") throw e;
93
- }
334
+ await walk(OBSIDIAN_VAULT_PATH);
94
335
  return results;
95
336
  }
96
337
 
97
338
  async function listObsidian(prefix) {
98
339
  const results = [];
99
340
  async function walk(dir) {
100
- const entries = await fs.readdir(dir, { withFileTypes: true });
101
- 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) {
102
345
  const fullPath = path.join(dir, entry.name);
103
- if (entry.isDirectory()) {
104
- await walk(fullPath);
105
- } else if (entry.name.endsWith(".md")) {
106
- const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
107
- const key = relative.replace(/\//g, ":").replace(/\.md$/, "");
108
- if (!prefix || key.startsWith(prefix)) {
109
- results.push({ key, path: relative });
110
- }
111
- }
346
+ if (entry.isDirectory()) { await walk(fullPath); continue; }
347
+ if (!entry.name.endsWith(".md")) continue;
348
+ const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
349
+ const key = relative.replace(/[\\/]/g, ":").replace(/\.md$/, "");
350
+ if (!prefix || key.startsWith(prefix)) results.push({ key, path: relative });
112
351
  }
113
352
  }
114
- try {
115
- await walk(OBSIDIAN_VAULT_PATH);
116
- } catch (e) {
117
- if (e.code !== "ENOENT") throw e;
118
- }
353
+ await walk(OBSIDIAN_VAULT_PATH);
119
354
  return results;
120
355
  }
121
356
 
122
357
  // ---------------------------------------------------------------------------
123
- // MCP Server Factory
358
+ // MCP server factory
124
359
  // ---------------------------------------------------------------------------
125
360
 
126
361
  function createMcpServerInstance() {
127
- const server = new McpServer({
128
- name: "heurchain-mcp",
129
- version: "1.1.0"
130
- });
362
+ const server = new McpServer({ name: "heurchain-mcp", version: "1.2.1" });
131
363
 
132
364
  // --- Cache Tools ---
133
365
 
134
- server.tool("cache_set", "Store a key-value pair in Redis cache with optional TTL", {
135
- key: z.string().describe("Cache key"),
136
- value: z.string().describe("Value to cache"),
137
- ttl: z.number().optional().describe("Time-to-live in seconds")
138
- }, async ({ key, value, ttl }) => {
139
- if (ttl) await redis.setEx(key, ttl, value);
140
- else await redis.set(key, value);
141
- return { content: [{ type: "text", text: JSON.stringify({ cached: true, key }) }] };
366
+ server.tool("cache_set", "Store a key-value pair in Redis (longterm tier). Optionally scope to a namespace.", {
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"),
370
+ namespace: z.string().optional().describe("Optional namespace prefix, e.g. 'agent-hermes'. Key becomes namespace:key.")
371
+ }, async ({ key, value, ttl, namespace }) => {
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
+ }
376
+ if (ttl) await redis.setEx(fullKey, ttl, value);
377
+ else await redis.set(fullKey, value);
378
+ indexAdd(fullKey, value, "longterm", new Date().toISOString());
379
+ return { content: [{ type: "text", text: JSON.stringify({ cached: true, key: fullKey }) }] };
142
380
  });
143
381
 
144
382
  server.tool("cache_get", "Retrieve a cached value from Redis by key", {
145
- key: z.string().describe("Cache key to retrieve")
146
- }, async ({ key }) => {
147
- const val = await redis.get(key);
383
+ key: z.string().describe("Cache key to retrieve"),
384
+ namespace: z.string().optional().describe("Namespace prefix used when storing")
385
+ }, async ({ key, namespace }) => {
386
+ const fullKey = namespace ? `${namespace}:${key}` : key;
387
+ const val = await redis.get(fullKey);
148
388
  if (val) return { content: [{ type: "text", text: val }] };
149
389
  return { content: [{ type: "text", text: JSON.stringify({ hit: false }) }] };
150
390
  });
151
391
 
152
392
  server.tool("cache_delete", "Delete a cached key from Redis", {
153
- key: z.string().describe("Cache key to delete")
154
- }, async ({ key }) => {
155
- const deleted = await redis.del(key);
156
- return { content: [{ type: "text", text: JSON.stringify({ deleted: deleted > 0, key }) }] };
393
+ key: z.string().describe("Cache key to delete"),
394
+ namespace: z.string().optional().describe("Namespace prefix used when storing")
395
+ }, async ({ key, namespace }) => {
396
+ const fullKey = namespace ? `${namespace}:${key}` : key;
397
+ const deleted = await redis.del(fullKey);
398
+ indexRemove(fullKey);
399
+ return { content: [{ type: "text", text: JSON.stringify({ deleted: deleted > 0, key: fullKey }) }] };
157
400
  });
158
401
 
159
402
  server.tool("redis_stats", "Get Redis server statistics and memory info", {}, async () => {
@@ -164,105 +407,168 @@ function createMcpServerInstance() {
164
407
  server.tool("health_check", "Check the health of the MCP server, Redis, and Obsidian vault", {}, async () => {
165
408
  const redisOk = redis.isReady;
166
409
  let obsidianOk = false;
167
- try {
168
- await fs.access(OBSIDIAN_VAULT_PATH);
169
- obsidianOk = true;
170
- } catch {}
171
- return {
172
- content: [{
173
- type: "text",
174
- text: JSON.stringify({
175
- status: (redisOk && obsidianOk) ? "healthy" : "degraded",
176
- redis: redisOk,
177
- obsidian: obsidianOk,
178
- vault_path: OBSIDIAN_VAULT_PATH,
179
- uptime: process.uptime()
180
- })
181
- }]
182
- };
410
+ try { await fs.access(OBSIDIAN_VAULT_PATH); obsidianOk = true; } catch {}
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
+ }) }] };
183
418
  });
184
419
 
185
- // --- Obsidian Vault Tools (Long-Term MD Storage) ---
420
+ // --- Obsidian Vault Tools ---
186
421
 
187
- server.tool("obsidian_write_note", "Write or overwrite a markdown note in the Obsidian vault for long-term storage", {
188
- key: z.string().describe("Note key (colons become folder separators, e.g., doc:proxmox:setup)"),
189
- content: z.string().describe("Markdown body"),
190
- metadata: z.record(z.string()).optional().describe("Optional frontmatter metadata (key-value pairs)")
191
- }, async ({ key, content, 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"),
426
+ namespace: z.string().optional().describe("Optional namespace prefix")
427
+ }, async ({ key, content, metadata, namespace }) => {
428
+ const fullKey = namespace ? `${namespace}:${key}` : key;
192
429
  try {
193
- const filePath = await saveToObsidian(key, content, metadata);
194
- return { content: [{ type: "text", text: JSON.stringify({ stored: true, key, path: filePath, tier: "reference" }) }] };
430
+ const filePath = await saveToObsidian(fullKey, content, metadata);
431
+ indexAdd(fullKey, content, "working", new Date().toISOString());
432
+ return { content: [{ type: "text", text: JSON.stringify({ stored: true, key: fullKey, path: filePath, tier: "working" }) }] };
195
433
  } catch (e) {
196
- return { content: [{ type: "text", text: JSON.stringify({ stored: false, key, 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" }) }] };
197
436
  }
198
437
  });
199
438
 
200
439
  server.tool("obsidian_read_note", "Read a markdown note from the Obsidian vault by key", {
201
- key: z.string().describe("Note key")
202
- }, async ({ key }) => {
440
+ key: z.string().describe("Note key"),
441
+ namespace: z.string().optional().describe("Namespace prefix used when storing")
442
+ }, async ({ key, namespace }) => {
443
+ const fullKey = namespace ? `${namespace}:${key}` : key;
203
444
  try {
204
- const content = await readFromObsidian(key);
205
- if (content === null) {
206
- return { content: [{ type: "text", text: JSON.stringify({ found: false, key }) }] };
207
- }
208
- return { content: [{ type: "text", text: JSON.stringify({ found: true, key, content }) }] };
445
+ const content = await readFromObsidian(fullKey);
446
+ if (content === null) return { content: [{ type: "text", text: JSON.stringify({ found: false, key: fullKey }) }] };
447
+ return { content: [{ type: "text", text: JSON.stringify({ found: true, key: fullKey, content }) }] };
209
448
  } catch (e) {
210
- return { content: [{ type: "text", text: JSON.stringify({ found: false, key, 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" }) }] };
211
451
  }
212
452
  });
213
453
 
214
454
  server.tool("obsidian_delete_note", "Delete a markdown note from the Obsidian vault by key", {
215
- key: z.string().describe("Note key to delete")
216
- }, async ({ key }) => {
455
+ key: z.string().describe("Note key to delete"),
456
+ namespace: z.string().optional().describe("Namespace prefix used when storing")
457
+ }, async ({ key, namespace }) => {
458
+ const fullKey = namespace ? `${namespace}:${key}` : key;
217
459
  try {
218
- const deleted = await deleteFromObsidian(key);
219
- return { content: [{ type: "text", text: JSON.stringify({ deleted, key }) }] };
460
+ const deleted = await deleteFromObsidian(fullKey);
461
+ indexRemove(fullKey);
462
+ return { content: [{ type: "text", text: JSON.stringify({ deleted, key: fullKey }) }] };
220
463
  } catch (e) {
221
- return { content: [{ type: "text", text: JSON.stringify({ deleted: false, key, 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" }) }] };
222
466
  }
223
467
  });
224
468
 
225
- server.tool("obsidian_search_notes", "Search all markdown notes in the Obsidian vault by keyword", {
226
- query: z.string().describe("Search term"),
227
- limit: z.number().optional().describe("Max results to return").default(10)
228
- }, async ({ query, limit }) => {
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),
472
+ namespace: z.string().optional().describe("Restrict to a namespace prefix")
473
+ }, async ({ query, limit, namespace }) => {
474
+ const safeLimit = Math.max(1, Math.min(Number.isFinite(limit) ? Math.floor(limit) : 10, 100));
229
475
  try {
230
- const results = await searchObsidian(query);
231
- const sliced = results.slice(0, limit);
232
- return { content: [{ type: "text", text: JSON.stringify({ count: results.length, results: sliced.map(r => ({ key: r.key, preview: r.content.substring(0, 200) })) }) }] };
476
+ const results = await searchObsidian(query, namespace || null);
477
+ return { content: [{ type: "text", text: JSON.stringify({
478
+ count: results.length,
479
+ results: results.slice(0, safeLimit).map(r => ({ key: r.key, preview: r.content.substring(0, 200) }))
480
+ }) }] };
233
481
  } catch (e) {
234
- 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" }) }] };
235
484
  }
236
485
  });
237
486
 
238
487
  server.tool("obsidian_list_notes", "List all markdown notes in the Obsidian vault, optionally filtered by prefix", {
239
- prefix: z.string().optional().describe("Key prefix filter, e.g., doc:proxmox:")
488
+ prefix: z.string().optional().describe("Key prefix filter, e.g. doc:proxmox:")
240
489
  }, async ({ prefix }) => {
241
490
  try {
242
491
  const results = await listObsidian(prefix);
243
492
  return { content: [{ type: "text", text: JSON.stringify({ count: results.length, notes: results }) }] };
244
493
  } catch (e) {
245
- 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" }) }] };
246
496
  }
247
497
  });
248
498
 
249
499
  // --- HeurChain BM25 Search ---
250
500
 
251
- server.tool("heurchain_search", "Search the full knowledge base using HeurChain's BM25 ranked index (preferred over obsidian_search_notes — covers all 460+ Redis keys with relevance scoring)", {
252
- query: z.string().describe("Search query"),
253
- limit: z.number().optional().describe("Max results (default 10, max 50)").default(10),
254
- tier: z.string().optional().describe("'all' | 'longterm' | 'working' (default: all)").default("all")
255
- }, async ({ query, limit, tier }) => {
501
+ server.tool("heurchain_search",
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'")
509
+ }, async ({ query, limit, tier, minScore, noiseFilter, namespace }) => {
510
+ try {
511
+ const results = bm25.search(query, {
512
+ limit: Math.min(limit, 50),
513
+ tier,
514
+ minScore,
515
+ noiseFilter,
516
+ namespace: namespace || null
517
+ });
518
+ return { content: [{ type: "text", text: JSON.stringify({
519
+ count: results.length,
520
+ index_size: bm25.size,
521
+ results: results.map(r => ({
522
+ key: r.key,
523
+ score: Math.round(r.score * 1000) / 1000,
524
+ tier: r.tier,
525
+ preview: (r.content || "").substring(0, 300),
526
+ updated_at: r.updated_at
527
+ }))
528
+ }) }] };
529
+ } catch (e) {
530
+ console.error("heurchain_search error:", e);
531
+ return { content: [{ type: "text", text: JSON.stringify({ error: "search failed" }) }] };
532
+ }
533
+ });
534
+
535
+ // --- heurchain_export (Glacier Sync) ---
536
+
537
+ server.tool("heurchain_export",
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."),
540
+ overwrite: z.boolean().optional().describe("Overwrite existing vault files (default false — skip if file exists)").default(false)
541
+ }, async ({ prefix, overwrite }) => {
542
+ let exported = 0, skipped = 0, errors = 0;
256
543
  try {
257
- const url = `${HEURCHAIN_URL}/search?q=${encodeURIComponent(query)}&limit=${limit}&tier=${tier}`;
258
- const response = await fetch(url);
259
- if (!response.ok) {
260
- return { content: [{ type: "text", text: JSON.stringify({ error: `HeurChain returned HTTP ${response.status}` }) }] };
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; }
547
+ const val = await redis.get(key);
548
+ if (!val) continue;
549
+ const filePath = keyToObsidianPath(key);
550
+ if (!overwrite) {
551
+ try { await fs.access(filePath); skipped++; continue; } catch {}
552
+ }
553
+ try {
554
+ await fs.mkdir(path.dirname(filePath), { recursive: true });
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`;
560
+ await fs.writeFile(filePath, header + val, "utf-8");
561
+ indexAdd(key, val, "longterm", new Date().toISOString());
562
+ exported++;
563
+ } catch (e) {
564
+ console.error(`heurchain_export: failed to write '${key}':`, e.message);
565
+ errors++;
566
+ }
261
567
  }
262
- const results = await response.json();
263
- return { content: [{ type: "text", text: JSON.stringify({ count: results.length, results: results.map(r => ({ key: r.key, score: r.score, tier: r.tier, preview: (r.content || "").substring(0, 300), updated_at: r.updated_at })) }) }] };
568
+ return { content: [{ type: "text", text: JSON.stringify({ exported, skipped, errors, vault_path: OBSIDIAN_VAULT_PATH }) }] };
264
569
  } catch (e) {
265
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
570
+ console.error("heurchain_export error:", e);
571
+ return { content: [{ type: "text", text: JSON.stringify({ error: "export failed", exported, skipped, errors }) }] };
266
572
  }
267
573
  });
268
574
 
@@ -274,14 +580,11 @@ function createMcpServerInstance() {
274
580
  if (!response.ok) return { content: [{ type: "text", text: JSON.stringify({ error: `HTTP ${response.status}` }) }] };
275
581
  const data = await response.json();
276
582
  const targets = data.data.activeTargets.map(t => ({
277
- job: t.labels.job,
278
- instance: t.labels.instance,
279
- health: t.health,
280
- last_scrape: t.lastScrape
583
+ job: t.labels.job, instance: t.labels.instance, health: t.health, last_scrape: t.lastScrape
281
584
  }));
282
585
  return { content: [{ type: "text", text: JSON.stringify({ targets }) }] };
283
586
  } catch (e) {
284
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
587
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
285
588
  }
286
589
  });
287
590
 
@@ -292,7 +595,7 @@ function createMcpServerInstance() {
292
595
  const data = await response.json();
293
596
  return { content: [{ type: "text", text: JSON.stringify({ alerts: data.data.alerts }) }] };
294
597
  } catch (e) {
295
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
598
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
296
599
  }
297
600
  });
298
601
 
@@ -305,71 +608,68 @@ function createMcpServerInstance() {
305
608
  const data = await response.json();
306
609
  return { content: [{ type: "text", text: JSON.stringify(data.data) }] };
307
610
  } catch (e) {
308
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
611
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
309
612
  }
310
613
  });
311
614
 
312
- // --- 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;
313
622
 
314
- 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
+ }
315
627
 
316
628
  server.tool("grafana_get_health", "Check the health status of the Grafana server", {}, async () => {
317
629
  try {
318
- const response = await fetch("http://grafana:3000/api/health", {
319
- headers: { "Authorization": grafanaAuth }
320
- });
630
+ const response = await fetch("http://grafana:3000/api/health", { headers: grafanaHeaders() });
321
631
  if (!response.ok) return { content: [{ type: "text", text: JSON.stringify({ error: `HTTP ${response.status}` }) }] };
322
- const data = await response.json();
323
- return { content: [{ type: "text", text: JSON.stringify(data) }] };
632
+ return { content: [{ type: "text", text: JSON.stringify(await response.json()) }] };
324
633
  } catch (e) {
325
- 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" }) }] };
326
635
  }
327
636
  });
328
637
 
329
638
  server.tool("grafana_list_dashboards", "List all available dashboards in Grafana", {}, async () => {
330
639
  try {
331
- const response = await fetch("http://grafana:3000/api/search?type=dash-db", {
332
- headers: { "Authorization": grafanaAuth }
333
- });
640
+ const response = await fetch("http://grafana:3000/api/search?type=dash-db", { headers: grafanaHeaders() });
334
641
  if (!response.ok) return { content: [{ type: "text", text: JSON.stringify({ error: `HTTP ${response.status}` }) }] };
335
642
  const dashboards = await response.json();
336
643
  return { content: [{ type: "text", text: JSON.stringify({ dashboards: dashboards.map(d => ({ title: d.title, url: d.url })) }) }] };
337
644
  } catch (e) {
338
- 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" }) }] };
339
646
  }
340
647
  });
341
648
 
342
- // --- Proxmox Documentation Tools (Redis-backed) ---
649
+ // --- Proxmox Documentation Tools ---
343
650
 
344
651
  async function searchDocs(keyPattern, contentFilter) {
345
652
  const keys = [];
346
- for await (const key of redis.scanIterator({ MATCH: keyPattern, COUNT: 100 })) {
347
- keys.push(key);
348
- }
653
+ for await (const key of redis.scanIterator({ MATCH: keyPattern, COUNT: 100, TYPE: "string" })) keys.push(key);
349
654
  if (keys.length === 0) return [];
350
655
  const results = [];
351
656
  for (const key of keys) {
352
657
  const val = await redis.get(key);
353
- if (val && (!contentFilter || val.toLowerCase().includes(contentFilter.toLowerCase()))) {
658
+ if (val && (!contentFilter || val.toLowerCase().includes(contentFilter.toLowerCase())))
354
659
  results.push({ key, content: val });
355
- }
356
660
  }
357
661
  return results;
358
662
  }
359
663
 
360
664
  server.tool("proxmox_get_cluster_status", "Retrieve the Proxmox cluster status document from the knowledge base", {}, async () => {
361
665
  const results = await searchDocs("doc:proxmox:cluster-status*", null);
362
- if (results.length === 0) {
363
- return { content: [{ type: "text", text: JSON.stringify({ error: "No cluster status document found. Store one with key 'doc:proxmox:cluster-status' using cache_set." }) }] };
364
- }
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." }) }] };
365
667
  return { content: [{ type: "text", text: results[0].content }] };
366
668
  });
367
669
 
368
670
  server.tool("proxmox_list_nodes", "List all Proxmox nodes documented in the knowledge base", {}, async () => {
369
671
  const results = await searchDocs("doc:proxmox:node:*", null);
370
- if (results.length === 0) {
371
- return { content: [{ type: "text", text: JSON.stringify({ error: "No node documents found. Store them with keys like 'doc:proxmox:node:pver430' using cache_set." }) }] };
372
- }
672
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No node documents found." }) }] };
373
673
  return { content: [{ type: "text", text: JSON.stringify({ nodes: results.map(r => ({ key: r.key, title: r.key.split(":").pop() })) }) }] };
374
674
  });
375
675
 
@@ -377,59 +677,47 @@ function createMcpServerInstance() {
377
677
  vm_id_or_name: z.string().describe("VM ID or name to search for")
378
678
  }, async ({ vm_id_or_name }) => {
379
679
  let results = await searchDocs("doc:proxmox:vm:*", vm_id_or_name);
380
- if (results.length === 0) results = await searchDocs("doc:proxmox:ct:*", vm_id_or_name);
381
- if (results.length === 0) results = await searchDocs("doc:proxmox:*", vm_id_or_name);
382
- if (results.length === 0) {
383
- return { content: [{ type: "text", text: JSON.stringify({ error: `No VM or CT found matching "${vm_id_or_name}".` }) }] };
384
- }
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}".` }) }] };
385
683
  return { content: [{ type: "text", text: results[0].content }] };
386
684
  });
387
685
 
388
- // --- Ceph Documentation Tools (Redis-backed) ---
686
+ // --- Ceph Documentation Tools ---
389
687
 
390
688
  server.tool("ceph_get_health_status", "Retrieve the latest Ceph cluster health status from the knowledge base", {}, async () => {
391
689
  const results = await searchDocs("doc:ceph:cluster-status*", null);
392
- if (results.length === 0) {
393
- return { content: [{ type: "text", text: JSON.stringify({ error: "No Ceph status document found. Store one with key 'doc:ceph:cluster-status' using cache_set." }) }] };
394
- }
690
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No Ceph status document found." }) }] };
395
691
  return { content: [{ type: "text", text: results[0].content }] };
396
692
  });
397
693
 
398
694
  server.tool("ceph_list_osd_notes", "List all Ceph OSD documentation notes from the knowledge base", {}, async () => {
399
695
  const results = await searchDocs("doc:ceph:osd:*", null);
400
- if (results.length === 0) {
401
- return { content: [{ type: "text", text: JSON.stringify({ error: "No OSD documents found. Store them with keys like 'doc:ceph:osd:0' using cache_set." }) }] };
402
- }
696
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No OSD documents found." }) }] };
403
697
  return { content: [{ type: "text", text: JSON.stringify({ osd_notes: results.map(r => r.key) }) }] };
404
698
  });
405
699
 
406
- // --- Network Documentation Tools (Redis-backed) ---
700
+ // --- Network Documentation Tools ---
407
701
 
408
702
  server.tool("network_search_docs", "Search across network and infrastructure documentation in the knowledge base", {
409
703
  search_query: z.string().describe("Search query to find relevant documentation")
410
704
  }, async ({ search_query }) => {
411
- const results = await searchDocs("doc:network:*", search_query);
412
- const infraResults = await searchDocs("doc:infrastructure:*", search_query);
413
- const all = [...results, ...infraResults];
414
- if (all.length === 0) {
415
- return { content: [{ type: "text", text: JSON.stringify({ status: "No relevant documents found." }) }] };
416
- }
417
- return { content: [{ type: "text", text: JSON.stringify({ results: all.slice(0, 5).map(r => ({ key: r.key, preview: r.content.substring(0, 200) })) }) }] };
705
+ const results = [...await searchDocs("doc:network:*", search_query), ...await searchDocs("doc:infrastructure:*", search_query)];
706
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ status: "No relevant documents found." }) }] };
707
+ return { content: [{ type: "text", text: JSON.stringify({ results: results.slice(0, 5).map(r => ({ key: r.key, preview: r.content.substring(0, 200) })) }) }] };
418
708
  });
419
709
 
420
710
  server.tool("network_get_runbook", "Retrieve a specific network runbook by topic from the knowledge base", {
421
711
  topic: z.string().describe("Runbook topic to search for")
422
712
  }, async ({ topic }) => {
423
713
  const results = await searchDocs("doc:runbook:*", topic);
424
- if (results.length === 0) {
425
- 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.` }) }] };
426
- }
714
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: `No runbook found for topic: "${topic}".` }) }] };
427
715
  return { content: [{ type: "text", text: results[0].content }] };
428
716
  });
429
717
 
430
- // --- User Context Tools (Redis-backed) ---
718
+ // --- User Context Tools ---
431
719
 
432
- const USER_HISTORY_TTL = 90 * 24 * 60 * 60; // 90 days
720
+ const USER_HISTORY_TTL = 90 * 24 * 60 * 60;
433
721
 
434
722
  server.tool("user_context_add_entry", "Add an entry to a user's daily interaction history log", {
435
723
  user_id: z.string().describe("User identifier"),
@@ -439,92 +727,103 @@ function createMcpServerInstance() {
439
727
  const key = `doc:users:${user_id}:history:${today}`;
440
728
  let existing = await redis.get(key);
441
729
  if (!existing) existing = `## User History for ${user_id} - ${today}\n\n`;
442
- const timestamp = new Date().toLocaleTimeString();
443
- const entry = `**[${timestamp}]**\n${content}\n\n---\n\n`;
444
- await redis.setEx(key, USER_HISTORY_TTL, existing + entry);
445
- return { content: [{ type: "text", text: JSON.stringify({ success: true, key, entry_added: entry }) }] };
730
+ const entry = `**[${new Date().toLocaleTimeString()}]**\n${content}\n\n---\n\n`;
731
+ const updated = existing + entry;
732
+ await redis.setEx(key, USER_HISTORY_TTL, updated);
733
+ indexAdd(key, updated, "longterm", new Date().toISOString());
734
+ return { content: [{ type: "text", text: JSON.stringify({ success: true, key }) }] };
446
735
  });
447
736
 
448
737
  server.tool("user_context_get_history", "Retrieve the full interaction history for a user on a specific date", {
449
738
  user_id: z.string().describe("User identifier"),
450
- date: z.string().describe("Date in YYYY-MM-DD format")
739
+ date: z.string().describe("Date in YYYY-MM-DD format")
451
740
  }, async ({ user_id, date }) => {
452
741
  const key = `doc:users:${user_id}:history:${date}`;
453
742
  const val = await redis.get(key);
454
- if (!val) {
455
- return { content: [{ type: "text", text: JSON.stringify({ status: "Not Found", message: `No history found for user '${user_id}' on date '${date}'.` }) }] };
456
- }
743
+ if (!val) return { content: [{ type: "text", text: JSON.stringify({ status: "Not Found", message: `No history for user '${user_id}' on '${date}'.` }) }] };
457
744
  return { content: [{ type: "text", text: JSON.stringify({ user_id, date, history: val }) }] };
458
745
  });
459
746
 
460
747
  server.tool("user_context_search_history", "Search across all of a user's history documents by keyword", {
461
748
  user_id: z.string().describe("User identifier"),
462
- query: z.string().describe("Search query")
749
+ query: z.string().describe("Search query")
463
750
  }, async ({ user_id, query }) => {
464
751
  const results = await searchDocs(`doc:users:${user_id}:history:*`, query);
465
- if (results.length === 0) {
466
- return { content: [{ type: "text", text: JSON.stringify({ status: "No matches found." }) }] };
467
- }
752
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ status: "No matches found." }) }] };
468
753
  return { content: [{ type: "text", text: JSON.stringify({
469
- results: results.map(r => ({
470
- date: r.key.split(":").pop(),
471
- match_preview: r.content.substring(0, 200) + "..."
472
- }))
754
+ results: results.map(r => ({ date: r.key.split(":").pop(), match_preview: r.content.substring(0, 200) + "..." }))
473
755
  }) }] };
474
756
  });
475
757
 
476
758
  return server;
477
759
  }
478
760
 
479
- // SSE transport management
761
+ // ---------------------------------------------------------------------------
762
+ // SSE transport — fix #3: max session cap + cleanup on error/close
763
+ // ---------------------------------------------------------------------------
764
+
765
+ const MAX_SESSIONS = 50;
480
766
  const transports = {};
481
767
 
482
- 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
+ }
483
772
  const transport = new SSEServerTransport("/messages", res);
484
773
  const mcpServer = createMcpServerInstance();
485
- transports[transport.sessionId] = { transport, server: mcpServer };
486
- res.on("close", () => {
487
- mcpServer.close();
488
- delete transports[transport.sessionId];
489
- });
490
- 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
+ }
491
793
  });
492
794
 
493
- app.post("/messages", async (req, res) => {
795
+ app.post("/messages", requireAuth, async (req, res) => {
494
796
  const sessionId = req.query.sessionId;
495
797
  const entry = transports[sessionId];
496
- if (entry) {
497
- await entry.transport.handlePostMessage(req, res);
498
- } else {
499
- res.status(400).json({ error: "No transport found for sessionId" });
500
- }
798
+ if (entry) await entry.transport.handlePostMessage(req, res);
799
+ else res.status(400).json({ error: "No transport found for sessionId" });
501
800
  });
502
801
 
503
- // --- REST API (backwards compatibility) ---
802
+ // ---------------------------------------------------------------------------
803
+ // REST API (backwards compatibility) — all routes require auth except /health
804
+ // ---------------------------------------------------------------------------
805
+
504
806
  const jsonParser = express.json();
505
807
 
506
808
  app.get("/health", async (req, res) => {
507
809
  const redisOk = redis.isReady;
508
810
  let obsidianOk = false;
509
- try {
510
- await fs.access(OBSIDIAN_VAULT_PATH);
511
- obsidianOk = true;
512
- } catch {}
811
+ try { await fs.access(OBSIDIAN_VAULT_PATH); obsidianOk = true; } catch {}
513
812
  res.json({
514
813
  status: (redisOk && obsidianOk) ? "healthy" : "degraded",
515
- redis: redisOk,
516
- obsidian: obsidianOk,
814
+ redis: redisOk, obsidian: obsidianOk,
517
815
  vault_path: OBSIDIAN_VAULT_PATH,
816
+ bm25_docs: bm25.size,
518
817
  uptime: process.uptime()
519
818
  });
520
819
  });
521
820
 
522
- app.get("/api/tools", (req, res) => {
821
+ app.get("/api/tools", requireAuth, (req, res) => {
523
822
  res.json({ tools: [
524
823
  "cache_set", "cache_get", "cache_delete", "redis_stats", "health_check",
525
824
  "obsidian_write_note", "obsidian_read_note", "obsidian_delete_note",
526
825
  "obsidian_search_notes", "obsidian_list_notes",
527
- "heurchain_search",
826
+ "heurchain_search", "heurchain_export",
528
827
  "prometheus_get_targets", "prometheus_get_alerts", "prometheus_query",
529
828
  "grafana_get_health", "grafana_list_dashboards",
530
829
  "proxmox_get_cluster_status", "proxmox_list_nodes", "proxmox_find_vm",
@@ -534,68 +833,78 @@ app.get("/api/tools", (req, res) => {
534
833
  ]});
535
834
  });
536
835
 
537
- app.post("/api/cache", jsonParser, async (req, res) => {
836
+ app.post("/api/cache", requireAuth, jsonParser, async (req, res) => {
538
837
  const { key, value, ttl } = req.body;
539
- const stored = typeof value === "string" ? value : JSON.stringify(value);
540
- if (ttl) await redis.setEx(key, ttl, stored);
541
- else await redis.set(key, stored);
838
+ if (ttl) await redis.setEx(key, ttl, JSON.stringify(value));
839
+ else await redis.set(key, JSON.stringify(value));
542
840
  res.json({ cached: true });
543
841
  });
544
842
 
545
- app.get("/api/cache/:key", async (req, res) => {
843
+ app.get("/api/cache/:key", requireAuth, async (req, res) => {
546
844
  const val = await redis.get(req.params.key);
547
- if (val) res.json({ hit: true, data: val });
845
+ if (val) res.json({ hit: true, data: JSON.parse(val) });
548
846
  else res.json({ hit: false });
549
847
  });
550
848
 
551
- app.get("/api/stats", async (req, res) => {
849
+ app.get("/api/stats", requireAuth, async (req, res) => {
552
850
  const info = await redis.info("stats");
553
- res.json({ redis_info: info });
851
+ res.json({ redis_info: info, bm25_docs: bm25.size });
554
852
  });
555
853
 
556
- // --- Obsidian REST Endpoints ---
557
-
558
- app.get("/api/obsidian/notes", async (req, res) => {
854
+ app.get("/api/obsidian/notes", requireAuth, async (req, res) => {
559
855
  const { key, prefix } = req.query;
560
856
  if (key) {
561
- const content = await readFromObsidian(key);
562
- if (content === null) return res.status(404).json({ found: false, key });
563
- 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
+ }
564
864
  }
565
865
  const notes = await listObsidian(prefix);
566
866
  res.json({ count: notes.length, notes });
567
867
  });
568
868
 
569
- app.post("/api/obsidian/notes", jsonParser, async (req, res) => {
869
+ app.post("/api/obsidian/notes", requireAuth, jsonParser, async (req, res) => {
570
870
  const { key, content, metadata } = req.body;
571
871
  if (!key || content === undefined) return res.status(400).json({ error: "key and content required" });
572
872
  try {
573
873
  const filePath = await saveToObsidian(key, content, metadata);
574
874
  res.json({ stored: true, key, path: filePath });
575
875
  } catch (e) {
576
- 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" });
577
878
  }
578
879
  });
579
880
 
580
- app.delete("/api/obsidian/notes", async (req, res) => {
881
+ app.delete("/api/obsidian/notes", requireAuth, async (req, res) => {
581
882
  const { key } = req.query;
582
883
  if (!key) return res.status(400).json({ error: "key required" });
583
- const deleted = await deleteFromObsidian(key);
584
- 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
+ }
585
890
  });
586
891
 
587
- app.get("/api/obsidian/search", async (req, res) => {
892
+ app.get("/api/obsidian/search", requireAuth, async (req, res) => {
588
893
  const { q, limit } = req.query;
589
894
  if (!q) return res.status(400).json({ error: "q required" });
590
- const results = await searchObsidian(q);
591
- const max = parseInt(limit) || 10;
592
- res.json({
593
- count: results.length,
594
- results: results.slice(0, max).map(r => ({
595
- key: r.key,
596
- path: r.path,
597
- preview: r.content.substring(0, 200)
598
- }))
599
- });
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) })) });
600
898
  });
601
899
 
900
+ // ---------------------------------------------------------------------------
901
+ // Startup
902
+ // ---------------------------------------------------------------------------
903
+
904
+ (async () => {
905
+ await redis.connect();
906
+ await buildIndex();
907
+ setInterval(buildIndex, 60 * 60 * 1000); // hourly rebuild
908
+ const port = parseInt(process.env.MCP_PORT, 10) || 3010;
909
+ app.listen(port, () => console.log(`HeurChain MCP v1.2.1 listening on port ${port} — ${bm25.size} docs indexed`));
910
+ })();