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.
- package/README.md +2 -0
- package/package.json +1 -1
- 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.
|
|
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
|
-
//
|
|
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
|
-
|
|
34
|
-
|
|
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
|
-
|
|
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
|
-
|
|
52
|
-
this.
|
|
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
|
|
86
|
-
if (
|
|
87
|
-
else this.df.set(term,
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
112
|
-
score += idf *
|
|
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 (
|
|
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,
|
|
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
|
|
218
|
+
// Index build
|
|
140
219
|
// ---------------------------------------------------------------------------
|
|
141
220
|
|
|
142
221
|
async function buildIndex() {
|
|
143
|
-
|
|
222
|
+
if (isBuilding) return; // skip if already running
|
|
223
|
+
isBuilding = true;
|
|
224
|
+
pendingOps.length = 0;
|
|
225
|
+
|
|
226
|
+
const entries = [];
|
|
144
227
|
|
|
145
|
-
// Scan
|
|
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
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
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
|
|
163
|
-
try {
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
//
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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: ${
|
|
282
|
+
console.log(`BM25 index built: ${bm25.size} docs (${entries.length} total entries scanned)`);
|
|
190
283
|
}
|
|
191
284
|
|
|
192
285
|
// ---------------------------------------------------------------------------
|
|
193
|
-
// Obsidian
|
|
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
|
|
207
|
-
for (const [k, v] of Object.entries(metadata))
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
-
|
|
233
|
-
|
|
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
|
-
|
|
240
|
-
|
|
241
|
-
|
|
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
|
-
|
|
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
|
-
|
|
254
|
-
|
|
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(
|
|
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
|
-
|
|
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
|
|
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:
|
|
282
|
-
value:
|
|
283
|
-
ttl:
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
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
|
|
420
|
+
// --- Obsidian Vault Tools ---
|
|
338
421
|
|
|
339
|
-
server.tool("obsidian_write_note", "Write a markdown note to the Obsidian vault (working tier
|
|
340
|
-
key:
|
|
341
|
-
content:
|
|
342
|
-
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
|
-
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
461
|
+
indexRemove(fullKey);
|
|
377
462
|
return { content: [{ type: "text", text: JSON.stringify({ deleted, key: fullKey }) }] };
|
|
378
463
|
} catch (e) {
|
|
379
|
-
|
|
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
|
|
384
|
-
query:
|
|
385
|
-
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),
|
|
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
|
-
|
|
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:
|
|
479
|
+
results: results.slice(0, safeLimit).map(r => ({ key: r.key, preview: r.content.substring(0, 200) }))
|
|
395
480
|
}) }] };
|
|
396
481
|
} catch (e) {
|
|
397
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
416
|
-
query:
|
|
417
|
-
limit:
|
|
418
|
-
tier:
|
|
419
|
-
minScore:
|
|
420
|
-
noiseFilter: z.boolean().optional().describe("Skip low-signal session metadata
|
|
421
|
-
namespace:
|
|
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
|
-
|
|
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
|
|
451
|
-
prefix:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
578
|
-
if (results.length
|
|
579
|
-
if (results.length
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
718
|
+
// --- User Context Tools ---
|
|
616
719
|
|
|
617
|
-
const USER_HISTORY_TTL = 90 * 24 * 60 * 60;
|
|
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
|
|
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
|
-
|
|
632
|
-
return { content: [{ type: "text", text: JSON.stringify({ success: true, key
|
|
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:
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
-
|
|
669
|
-
|
|
670
|
-
|
|
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
|
-
|
|
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
|
-
|
|
739
|
-
|
|
740
|
-
|
|
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(
|
|
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
|
-
|
|
761
|
-
|
|
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
|
|
768
|
-
const
|
|
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
|
-
|
|
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.
|
|
909
|
+
app.listen(port, () => console.log(`HeurChain MCP v1.2.1 listening on port ${port} — ${bm25.size} docs indexed`));
|
|
786
910
|
})();
|