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.
- package/README.md +2 -0
- package/package.json +1 -1
- 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
|
|
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
|
|
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
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
//
|
|
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
|
-
|
|
31
|
-
|
|
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
|
|
40
|
-
for (const [k, v] of Object.entries(metadata))
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
75
|
-
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
-
|
|
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
|
-
|
|
101
|
-
|
|
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
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
135
|
-
key:
|
|
136
|
-
value:
|
|
137
|
-
ttl:
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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:
|
|
146
|
-
|
|
147
|
-
|
|
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:
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
169
|
-
obsidianOk
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
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
|
|
420
|
+
// --- Obsidian Vault Tools ---
|
|
186
421
|
|
|
187
|
-
server.tool("obsidian_write_note", "Write
|
|
188
|
-
key:
|
|
189
|
-
content:
|
|
190
|
-
metadata:
|
|
191
|
-
|
|
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(
|
|
194
|
-
|
|
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
|
-
|
|
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:
|
|
202
|
-
|
|
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(
|
|
205
|
-
if (content === null) {
|
|
206
|
-
|
|
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
|
-
|
|
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:
|
|
216
|
-
|
|
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(
|
|
219
|
-
|
|
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
|
-
|
|
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
|
|
226
|
-
query:
|
|
227
|
-
limit:
|
|
228
|
-
|
|
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
|
-
|
|
232
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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",
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
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
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
381
|
-
if (results.length
|
|
382
|
-
if (results.length
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
413
|
-
|
|
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
|
|
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
|
|
718
|
+
// --- User Context Tools ---
|
|
431
719
|
|
|
432
|
-
const USER_HISTORY_TTL = 90 * 24 * 60 * 60;
|
|
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
|
|
443
|
-
const
|
|
444
|
-
await redis.setEx(key, USER_HISTORY_TTL,
|
|
445
|
-
|
|
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:
|
|
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:
|
|
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
|
|
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
|
-
//
|
|
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
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
-
|
|
540
|
-
|
|
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
|
-
|
|
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
|
-
|
|
562
|
-
|
|
563
|
-
|
|
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(
|
|
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
|
-
|
|
584
|
-
|
|
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
|
|
591
|
-
const
|
|
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
|
+
})();
|