@kalera/munin-runtime 1.2.9 → 1.4.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/.turbo/turbo-build.log +1 -1
- package/dist/index.d.ts +5 -0
- package/dist/index.js +29 -10
- package/dist/mcp-server.js +152 -10
- package/package.json +3 -2
- package/src/index.ts +32 -10
- package/src/mcp-server.ts +155 -13
package/.turbo/turbo-build.log
CHANGED
package/dist/index.d.ts
CHANGED
|
@@ -10,6 +10,11 @@ export interface CliEnv {
|
|
|
10
10
|
backoffMs: number;
|
|
11
11
|
}
|
|
12
12
|
export declare function parseCliArgs(argv: string[], usage: string): ParsedCliArgs;
|
|
13
|
+
/**
|
|
14
|
+
* Resolve MUNIN_API_KEY — reads from process.env first, then walks up from CWD
|
|
15
|
+
* for .env.local / .env files. This mirrors the MUNIN_PROJECT resolution pattern.
|
|
16
|
+
*/
|
|
17
|
+
export declare function resolveApiKey(): string | undefined;
|
|
13
18
|
export declare function loadCliEnv(): CliEnv;
|
|
14
19
|
/**
|
|
15
20
|
* Resolve MUNIN_PROJECT from multiple sources, in priority order:
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import fs from "
|
|
2
|
-
import path from "
|
|
1
|
+
import * as fs from "fs";
|
|
2
|
+
import * as path from "path";
|
|
3
3
|
const REDACT_KEYS = ["apiKey", "authorization", "token", "secret", "password"];
|
|
4
4
|
export function parseCliArgs(argv, usage) {
|
|
5
5
|
const [action, payloadRaw] = argv;
|
|
@@ -19,10 +19,27 @@ export function parseCliArgs(argv, usage) {
|
|
|
19
19
|
throw new Error("Payload must be valid JSON");
|
|
20
20
|
}
|
|
21
21
|
}
|
|
22
|
+
/**
|
|
23
|
+
* Resolve MUNIN_API_KEY — reads from process.env first, then walks up from CWD
|
|
24
|
+
* for .env.local / .env files. This mirrors the MUNIN_PROJECT resolution pattern.
|
|
25
|
+
*/
|
|
26
|
+
export function resolveApiKey() {
|
|
27
|
+
if (process.env.MUNIN_API_KEY) {
|
|
28
|
+
return process.env.MUNIN_API_KEY;
|
|
29
|
+
}
|
|
30
|
+
// Walk upward from CWD — find .env.local first, then .env
|
|
31
|
+
const fromLocal = resolveEnvFileUpward(".env.local", "MUNIN_API_KEY");
|
|
32
|
+
if (fromLocal)
|
|
33
|
+
return fromLocal;
|
|
34
|
+
const fromEnv = resolveEnvFileUpward(".env", "MUNIN_API_KEY");
|
|
35
|
+
if (fromEnv)
|
|
36
|
+
return fromEnv;
|
|
37
|
+
return undefined;
|
|
38
|
+
}
|
|
22
39
|
export function loadCliEnv() {
|
|
23
40
|
return {
|
|
24
41
|
baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
|
|
25
|
-
apiKey:
|
|
42
|
+
apiKey: resolveApiKey(),
|
|
26
43
|
timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
|
|
27
44
|
retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
|
|
28
45
|
backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
|
|
@@ -36,10 +53,11 @@ function safeParseInt(envVal, defaultVal) {
|
|
|
36
53
|
}
|
|
37
54
|
/**
|
|
38
55
|
* Walk up the directory tree from `startDir` (default CWD) toward root,
|
|
39
|
-
* searching each ancestor for `
|
|
40
|
-
* Stops at filesystem root or when a `.git` dir is found
|
|
56
|
+
* searching each ancestor for a .env file containing `key=`. Returns the value
|
|
57
|
+
* of the first match. Stops at filesystem root or when a `.git` dir is found
|
|
58
|
+
* (project boundary).
|
|
41
59
|
*/
|
|
42
|
-
function resolveEnvFileUpward(filename, startDir) {
|
|
60
|
+
function resolveEnvFileUpward(filename, key, startDir) {
|
|
43
61
|
let current = startDir ?? process.cwd();
|
|
44
62
|
let last = "";
|
|
45
63
|
while (current !== last) {
|
|
@@ -48,11 +66,12 @@ function resolveEnvFileUpward(filename, startDir) {
|
|
|
48
66
|
try {
|
|
49
67
|
if (fs.existsSync(filePath)) {
|
|
50
68
|
const content = fs.readFileSync(filePath, "utf8");
|
|
69
|
+
const prefix = `${key}=`;
|
|
51
70
|
for (const line of content.split("\n")) {
|
|
52
71
|
const trimmed = line.trim();
|
|
53
|
-
if (!trimmed.startsWith(
|
|
72
|
+
if (!trimmed.startsWith(prefix))
|
|
54
73
|
continue;
|
|
55
|
-
return trimmed.slice(
|
|
74
|
+
return trimmed.slice(prefix.length).trim();
|
|
56
75
|
}
|
|
57
76
|
}
|
|
58
77
|
}
|
|
@@ -80,11 +99,11 @@ export function resolveProjectId() {
|
|
|
80
99
|
return process.env.MUNIN_PROJECT;
|
|
81
100
|
}
|
|
82
101
|
// 2. Walk upward from CWD — find .env.local in any ancestor dir
|
|
83
|
-
const fromLocal = resolveEnvFileUpward(".env.local");
|
|
102
|
+
const fromLocal = resolveEnvFileUpward(".env.local", "MUNIN_PROJECT");
|
|
84
103
|
if (fromLocal)
|
|
85
104
|
return fromLocal;
|
|
86
105
|
// 3. Walk upward from CWD — find .env in any ancestor dir
|
|
87
|
-
const fromEnv = resolveEnvFileUpward(".env");
|
|
106
|
+
const fromEnv = resolveEnvFileUpward(".env", "MUNIN_PROJECT");
|
|
88
107
|
if (fromEnv)
|
|
89
108
|
return fromEnv;
|
|
90
109
|
return undefined;
|
package/dist/mcp-server.js
CHANGED
|
@@ -5,7 +5,7 @@ import { MuninClient } from "@kalera/munin-sdk";
|
|
|
5
5
|
import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
|
|
6
6
|
export function createMcpServerInstance(env, opts) {
|
|
7
7
|
if (!env.apiKey && !opts?.allowMissingApiKey) {
|
|
8
|
-
throw new Error("MUNIN_API_KEY is required. Set it in your environment or .env file.");
|
|
8
|
+
throw new Error("MUNIN_API_KEY is required. Set it in your environment, or in a .env.local / .env file in your project directory (walked up automatically).");
|
|
9
9
|
}
|
|
10
10
|
const client = new MuninClient({
|
|
11
11
|
baseUrl: env.baseUrl,
|
|
@@ -14,7 +14,7 @@ export function createMcpServerInstance(env, opts) {
|
|
|
14
14
|
});
|
|
15
15
|
const server = new Server({
|
|
16
16
|
name: "munin-mcp-server",
|
|
17
|
-
version: "1.
|
|
17
|
+
version: "1.4.1",
|
|
18
18
|
}, {
|
|
19
19
|
capabilities: {
|
|
20
20
|
tools: {},
|
|
@@ -25,21 +25,51 @@ export function createMcpServerInstance(env, opts) {
|
|
|
25
25
|
tools: [
|
|
26
26
|
{
|
|
27
27
|
name: "munin_store_memory",
|
|
28
|
-
description: "Store or update
|
|
28
|
+
description: "Store or update one or more memories in Munin Context Core. Auto-uses active project if projectId omitted. BATCH MODE: pass `memories: [...]` (up to 50 items per call) to save many memories in a single call — drastically reduces API quota usage at session end / /compact. When `memories` is provided, single-memory params (key/content/...) are ignored. TIPS for better recall later: (1) Set `validFrom`/`validTo` for time-bound facts so search auto-filters stale memories; (2) Pin durable identity facts via `isPinned: true`. IMPORTANT: Call as MCP tool, not shell command.",
|
|
29
29
|
inputSchema: {
|
|
30
30
|
type: "object",
|
|
31
31
|
properties: {
|
|
32
32
|
projectId: { type: "string", description: "Optional. Only use if cross-saving to a different Context Core ID." },
|
|
33
|
-
key: { type: "string", description: "Unique identifier for this memory" },
|
|
34
|
-
content: { type: "string", description: "The content to remember" },
|
|
33
|
+
key: { type: "string", description: "Unique identifier for this memory (single-memory mode)" },
|
|
34
|
+
content: { type: "string", description: "The content to remember (single-memory mode)" },
|
|
35
35
|
title: { type: "string", description: "Optional title" },
|
|
36
36
|
tags: {
|
|
37
37
|
type: "array",
|
|
38
38
|
items: { type: "string" },
|
|
39
39
|
description: "List of tags, e.g. ['planning', 'frontend']"
|
|
40
|
+
},
|
|
41
|
+
validFrom: {
|
|
42
|
+
type: "string",
|
|
43
|
+
description: "Optional ISO-8601 date — memory is hidden from search before this date. Use for facts that take effect later (e.g., new policy). Omit for always-valid memories."
|
|
44
|
+
},
|
|
45
|
+
validTo: {
|
|
46
|
+
type: "string",
|
|
47
|
+
description: "Optional ISO-8601 date — memory expires from search after this date. Use for time-bound facts (deadlines, sprint goals, expiring promotions). Omit for never-expiring."
|
|
48
|
+
},
|
|
49
|
+
isPinned: {
|
|
50
|
+
type: "boolean",
|
|
51
|
+
description: "Mark as pinned to boost in search ranking. Reserve for high-importance identity/anchor facts (project name, user role, key constraints)."
|
|
52
|
+
},
|
|
53
|
+
memories: {
|
|
54
|
+
type: "array",
|
|
55
|
+
description: "OPTIONAL. For batch storing up to 50 memories in one call (saves API quota at /compact / session end). Each item has same shape as single-memory params (key, content, tags, title, validFrom, validTo, isPinned). When provided, single-memory params (key/content/...) are ignored. Returns per-item success/error in `data.results`.",
|
|
56
|
+
maxItems: 50,
|
|
57
|
+
items: {
|
|
58
|
+
type: "object",
|
|
59
|
+
properties: {
|
|
60
|
+
key: { type: "string" },
|
|
61
|
+
content: { type: "string" },
|
|
62
|
+
title: { type: "string" },
|
|
63
|
+
tags: { type: "array", items: { type: "string" } },
|
|
64
|
+
validFrom: { type: "string" },
|
|
65
|
+
validTo: { type: "string" },
|
|
66
|
+
isPinned: { type: "boolean" }
|
|
67
|
+
},
|
|
68
|
+
required: ["key", "content"]
|
|
69
|
+
}
|
|
40
70
|
}
|
|
41
71
|
},
|
|
42
|
-
required: [
|
|
72
|
+
required: [],
|
|
43
73
|
},
|
|
44
74
|
},
|
|
45
75
|
{
|
|
@@ -56,13 +86,22 @@ export function createMcpServerInstance(env, opts) {
|
|
|
56
86
|
},
|
|
57
87
|
{
|
|
58
88
|
name: "munin_search_memories",
|
|
59
|
-
description: "
|
|
89
|
+
description: "Hybrid 6-signal search (keyword + semantic + named-entity + quoted-phrase + recency + pinned). QUERY TIPS to lift recall: (1) Wrap exact strings in double quotes — e.g., `\"Project Munin v1.3\"` — to trigger quoted-phrase boost (+0.25); (2) Include capitalized names (people, products, places) for name-entity boost (+0.15); (3) Use `filters.since`/`before` for temporal scoping (relative strings supported: 'yesterday', 'last week', '7 days ago'). Returns token-efficient GraphRAG context with mermaid graph. IMPORTANT: Call as MCP tool.",
|
|
60
90
|
inputSchema: {
|
|
61
91
|
type: "object",
|
|
62
92
|
properties: {
|
|
63
93
|
projectId: { type: "string", description: "Optional. The Munin Context Core ID." },
|
|
64
|
-
query: { type: "string", description: "Search query" },
|
|
65
|
-
tags: { type: "array", items: { type: "string" } },
|
|
94
|
+
query: { type: "string", description: "Search query. Tip: wrap exact phrases in quotes for boost; capitalize entity names." },
|
|
95
|
+
tags: { type: "array", items: { type: "string" }, description: "Filter results to memories containing these tags" },
|
|
96
|
+
tagMode: { type: "string", enum: ["or", "and"], description: "Tag combination: 'or' (any match) or 'and' (all match). Default: 'or'." },
|
|
97
|
+
filters: {
|
|
98
|
+
type: "object",
|
|
99
|
+
description: "Temporal filter on memory createdAt. Supports ISO-8601 dates AND relative strings: 'yesterday', 'last week', 'last month', 'last year', '7 days ago', '3 weeks ago', etc.",
|
|
100
|
+
properties: {
|
|
101
|
+
since: { type: "string", description: "Memories created on/after this date (e.g., 'last week', '2026-04-01')" },
|
|
102
|
+
before: { type: "string", description: "Memories created on/before this date" }
|
|
103
|
+
}
|
|
104
|
+
},
|
|
66
105
|
topK: { type: "number", description: "Max results to return (default: 10, max: 50)" },
|
|
67
106
|
offset: { type: "number", description: "Pagination offset for fetching more results (default: 0)" },
|
|
68
107
|
includeTotal: { type: "boolean", description: "If true, includes total count in response (default: false)" },
|
|
@@ -97,7 +136,7 @@ export function createMcpServerInstance(env, opts) {
|
|
|
97
136
|
},
|
|
98
137
|
{
|
|
99
138
|
name: "munin_share_memory",
|
|
100
|
-
description: "Share one or more memories to other projects owned by the same user. The target project must share the same Hash Key to read encrypted content.
|
|
139
|
+
description: "Share one or more memories to other projects owned by the same user. The target project must share the same Hash Key to read encrypted content. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
101
140
|
inputSchema: {
|
|
102
141
|
type: "object",
|
|
103
142
|
properties: {
|
|
@@ -127,6 +166,82 @@ export function createMcpServerInstance(env, opts) {
|
|
|
127
166
|
required: [],
|
|
128
167
|
},
|
|
129
168
|
},
|
|
169
|
+
{
|
|
170
|
+
name: "munin_versions",
|
|
171
|
+
description: "List all versions of a memory (version history). Use this to review past changes before rolling back. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
172
|
+
inputSchema: {
|
|
173
|
+
type: "object",
|
|
174
|
+
properties: {
|
|
175
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
176
|
+
key: { type: "string", description: "Memory key (provide this OR id, not both)" },
|
|
177
|
+
id: { type: "string", description: "Memory ID (provide this OR key, not both)" },
|
|
178
|
+
},
|
|
179
|
+
oneOf: [
|
|
180
|
+
{ required: ["key"] },
|
|
181
|
+
{ required: ["id"] },
|
|
182
|
+
],
|
|
183
|
+
},
|
|
184
|
+
},
|
|
185
|
+
{
|
|
186
|
+
name: "munin_rollback",
|
|
187
|
+
description: "Rollback a memory to a previous version. Run munin_versions first to find the version number. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
188
|
+
inputSchema: {
|
|
189
|
+
type: "object",
|
|
190
|
+
properties: {
|
|
191
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
192
|
+
key: { type: "string", description: "Memory key (provide this OR id, not both)" },
|
|
193
|
+
id: { type: "string", description: "Memory ID (provide this OR key, not both)" },
|
|
194
|
+
version: { type: "number", description: "The version number to rollback to (required)" },
|
|
195
|
+
},
|
|
196
|
+
required: ["version"],
|
|
197
|
+
oneOf: [
|
|
198
|
+
{ required: ["key"] },
|
|
199
|
+
{ required: ["id"] },
|
|
200
|
+
],
|
|
201
|
+
},
|
|
202
|
+
},
|
|
203
|
+
{
|
|
204
|
+
name: "munin_diff_memory",
|
|
205
|
+
description: "Compare two specific versions of the same memory. Returns a diff showing what changed between v1 and v2. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
206
|
+
inputSchema: {
|
|
207
|
+
type: "object",
|
|
208
|
+
properties: {
|
|
209
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
210
|
+
key: { type: "string", description: "Memory key" },
|
|
211
|
+
v1: { type: "number", description: "First version number" },
|
|
212
|
+
v2: { type: "number", description: "Second version number" },
|
|
213
|
+
},
|
|
214
|
+
required: ["key", "v1", "v2"],
|
|
215
|
+
},
|
|
216
|
+
},
|
|
217
|
+
{
|
|
218
|
+
name: "munin_delete_memory",
|
|
219
|
+
description: "Permanently delete a memory by key or id from the current Munin Context Core. This action is destructive and cannot be undone — the memory and all its version history are removed. Use with caution. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
220
|
+
inputSchema: {
|
|
221
|
+
type: "object",
|
|
222
|
+
properties: {
|
|
223
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
224
|
+
key: { type: "string", description: "Memory key (provide this OR id, not both)" },
|
|
225
|
+
id: { type: "string", description: "Memory ID (provide this OR key, not both)" }
|
|
226
|
+
},
|
|
227
|
+
oneOf: [
|
|
228
|
+
{ required: ["key"] },
|
|
229
|
+
{ required: ["id"] }
|
|
230
|
+
]
|
|
231
|
+
}
|
|
232
|
+
},
|
|
233
|
+
{
|
|
234
|
+
name: "munin_acknowledge_setup",
|
|
235
|
+
description: "Acknowledge that you have read the latest Munin setup guide. Call this AFTER reading the setup guide URL provided in any ERR_STALE_PROTOCOL response. Subsequent write actions (store, share) will then proceed without setup-version errors. Pass the version exactly as shown in the remediation hint.",
|
|
236
|
+
inputSchema: {
|
|
237
|
+
type: "object",
|
|
238
|
+
properties: {
|
|
239
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
240
|
+
version: { type: "string", description: "Setup version in ISO date format (YYYY-MM-DD), exactly as shown in the ERR_STALE_PROTOCOL remediation hint." }
|
|
241
|
+
},
|
|
242
|
+
required: ["version"]
|
|
243
|
+
}
|
|
244
|
+
},
|
|
130
245
|
],
|
|
131
246
|
};
|
|
132
247
|
});
|
|
@@ -163,6 +278,9 @@ export function createMcpServerInstance(env, opts) {
|
|
|
163
278
|
case "munin_share_memory":
|
|
164
279
|
result = await client.invoke(projectId, "share", enrichedPayload);
|
|
165
280
|
break;
|
|
281
|
+
case "munin_diff_memory":
|
|
282
|
+
result = await client.invoke(projectId, "diff", enrichedPayload);
|
|
283
|
+
break;
|
|
166
284
|
case "munin_get_project_info": {
|
|
167
285
|
const caps = await client.capabilities();
|
|
168
286
|
result = {
|
|
@@ -172,6 +290,30 @@ export function createMcpServerInstance(env, opts) {
|
|
|
172
290
|
};
|
|
173
291
|
break;
|
|
174
292
|
}
|
|
293
|
+
case "munin_versions":
|
|
294
|
+
if (!args.key && !args.id) {
|
|
295
|
+
throw new Error("munin_versions requires either 'key' or 'id' to identify the target memory.");
|
|
296
|
+
}
|
|
297
|
+
result = await client.invoke(projectId, "versions", { key: args.key, id: args.id });
|
|
298
|
+
break;
|
|
299
|
+
case "munin_rollback":
|
|
300
|
+
if (!args.key && !args.id) {
|
|
301
|
+
throw new Error("munin_rollback requires either 'key' or 'id' to identify the target memory.");
|
|
302
|
+
}
|
|
303
|
+
if (typeof args.version !== "number") {
|
|
304
|
+
throw new Error("munin_rollback requires a numeric 'version' to roll back to.");
|
|
305
|
+
}
|
|
306
|
+
result = await client.invoke(projectId, "rollback", { key: args.key, id: args.id, version: args.version });
|
|
307
|
+
break;
|
|
308
|
+
case "munin_delete_memory":
|
|
309
|
+
if (!args.key && !args.id) {
|
|
310
|
+
throw new Error("munin_delete_memory requires either 'key' or 'id' to identify the target memory.");
|
|
311
|
+
}
|
|
312
|
+
result = await client.invoke(projectId, "delete", { key: args.key, id: args.id });
|
|
313
|
+
break;
|
|
314
|
+
case "munin_acknowledge_setup":
|
|
315
|
+
result = await client.invoke(projectId, "acknowledge_setup", { version: args.version });
|
|
316
|
+
break;
|
|
175
317
|
default:
|
|
176
318
|
throw new Error(`Unknown tool: ${request.params.name}`);
|
|
177
319
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kalera/munin-runtime",
|
|
3
|
-
"version": "1.2.9",
|
|
4
3
|
"type": "module",
|
|
5
4
|
"main": "dist/index.js",
|
|
6
5
|
"types": "dist/index.d.ts",
|
|
@@ -8,12 +7,14 @@
|
|
|
8
7
|
".": "./dist/index.js"
|
|
9
8
|
},
|
|
10
9
|
"devDependencies": {
|
|
10
|
+
"@types/node": "^24.3.0",
|
|
11
11
|
"typescript": "^5.9.2"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
14
|
"@modelcontextprotocol/sdk": "^1.27.1",
|
|
15
|
-
"@kalera/munin-sdk": "1.
|
|
15
|
+
"@kalera/munin-sdk": "1.4.1"
|
|
16
16
|
},
|
|
17
|
+
"version": "1.4.1",
|
|
17
18
|
"scripts": {
|
|
18
19
|
"build": "tsc -p tsconfig.json",
|
|
19
20
|
"lint": "tsc -p tsconfig.json --noEmit",
|
package/src/index.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import fs from "
|
|
2
|
-
import path from "
|
|
1
|
+
import * as fs from "fs";
|
|
2
|
+
import * as path from "path";
|
|
3
3
|
|
|
4
4
|
export interface ParsedCliArgs {
|
|
5
5
|
action: string;
|
|
@@ -36,10 +36,26 @@ export function parseCliArgs(argv: string[], usage: string): ParsedCliArgs {
|
|
|
36
36
|
}
|
|
37
37
|
}
|
|
38
38
|
|
|
39
|
+
/**
|
|
40
|
+
* Resolve MUNIN_API_KEY — reads from process.env first, then walks up from CWD
|
|
41
|
+
* for .env.local / .env files. This mirrors the MUNIN_PROJECT resolution pattern.
|
|
42
|
+
*/
|
|
43
|
+
export function resolveApiKey(): string | undefined {
|
|
44
|
+
if (process.env.MUNIN_API_KEY) {
|
|
45
|
+
return process.env.MUNIN_API_KEY;
|
|
46
|
+
}
|
|
47
|
+
// Walk upward from CWD — find .env.local first, then .env
|
|
48
|
+
const fromLocal = resolveEnvFileUpward(".env.local", "MUNIN_API_KEY");
|
|
49
|
+
if (fromLocal) return fromLocal;
|
|
50
|
+
const fromEnv = resolveEnvFileUpward(".env", "MUNIN_API_KEY");
|
|
51
|
+
if (fromEnv) return fromEnv;
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
|
|
39
55
|
export function loadCliEnv(): CliEnv {
|
|
40
56
|
return {
|
|
41
57
|
baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
|
|
42
|
-
apiKey:
|
|
58
|
+
apiKey: resolveApiKey(),
|
|
43
59
|
timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
|
|
44
60
|
retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
|
|
45
61
|
backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
|
|
@@ -54,10 +70,15 @@ function safeParseInt(envVal: string | undefined, defaultVal: number): number {
|
|
|
54
70
|
|
|
55
71
|
/**
|
|
56
72
|
* Walk up the directory tree from `startDir` (default CWD) toward root,
|
|
57
|
-
* searching each ancestor for `
|
|
58
|
-
* Stops at filesystem root or when a `.git` dir is found
|
|
73
|
+
* searching each ancestor for a .env file containing `key=`. Returns the value
|
|
74
|
+
* of the first match. Stops at filesystem root or when a `.git` dir is found
|
|
75
|
+
* (project boundary).
|
|
59
76
|
*/
|
|
60
|
-
function resolveEnvFileUpward(
|
|
77
|
+
function resolveEnvFileUpward(
|
|
78
|
+
filename: string,
|
|
79
|
+
key: string,
|
|
80
|
+
startDir?: string,
|
|
81
|
+
): string | undefined {
|
|
61
82
|
let current = startDir ?? process.cwd();
|
|
62
83
|
let last = "";
|
|
63
84
|
|
|
@@ -67,10 +88,11 @@ function resolveEnvFileUpward(filename: string, startDir?: string): string | und
|
|
|
67
88
|
try {
|
|
68
89
|
if (fs.existsSync(filePath)) {
|
|
69
90
|
const content = fs.readFileSync(filePath, "utf8");
|
|
91
|
+
const prefix = `${key}=`;
|
|
70
92
|
for (const line of content.split("\n")) {
|
|
71
93
|
const trimmed = line.trim();
|
|
72
|
-
if (!trimmed.startsWith(
|
|
73
|
-
return trimmed.slice(
|
|
94
|
+
if (!trimmed.startsWith(prefix)) continue;
|
|
95
|
+
return trimmed.slice(prefix.length).trim();
|
|
74
96
|
}
|
|
75
97
|
}
|
|
76
98
|
} catch (error) {
|
|
@@ -100,11 +122,11 @@ export function resolveProjectId(): string | undefined {
|
|
|
100
122
|
}
|
|
101
123
|
|
|
102
124
|
// 2. Walk upward from CWD — find .env.local in any ancestor dir
|
|
103
|
-
const fromLocal = resolveEnvFileUpward(".env.local");
|
|
125
|
+
const fromLocal = resolveEnvFileUpward(".env.local", "MUNIN_PROJECT");
|
|
104
126
|
if (fromLocal) return fromLocal;
|
|
105
127
|
|
|
106
128
|
// 3. Walk upward from CWD — find .env in any ancestor dir
|
|
107
|
-
const fromEnv = resolveEnvFileUpward(".env");
|
|
129
|
+
const fromEnv = resolveEnvFileUpward(".env", "MUNIN_PROJECT");
|
|
108
130
|
if (fromEnv) return fromEnv;
|
|
109
131
|
|
|
110
132
|
return undefined;
|
package/src/mcp-server.ts
CHANGED
|
@@ -13,7 +13,7 @@ export function createMcpServerInstance(
|
|
|
13
13
|
) {
|
|
14
14
|
if (!env.apiKey && !opts?.allowMissingApiKey) {
|
|
15
15
|
throw new Error(
|
|
16
|
-
"MUNIN_API_KEY is required. Set it in your environment or .env file.",
|
|
16
|
+
"MUNIN_API_KEY is required. Set it in your environment, or in a .env.local / .env file in your project directory (walked up automatically).",
|
|
17
17
|
);
|
|
18
18
|
}
|
|
19
19
|
|
|
@@ -26,7 +26,7 @@ export function createMcpServerInstance(
|
|
|
26
26
|
const server = new Server(
|
|
27
27
|
{
|
|
28
28
|
name: "munin-mcp-server",
|
|
29
|
-
version: "1.
|
|
29
|
+
version: "1.4.1",
|
|
30
30
|
},
|
|
31
31
|
{
|
|
32
32
|
capabilities: {
|
|
@@ -40,21 +40,51 @@ export function createMcpServerInstance(
|
|
|
40
40
|
tools: [
|
|
41
41
|
{
|
|
42
42
|
name: "munin_store_memory",
|
|
43
|
-
description: "Store or update
|
|
43
|
+
description: "Store or update one or more memories in Munin Context Core. Auto-uses active project if projectId omitted. BATCH MODE: pass `memories: [...]` (up to 50 items per call) to save many memories in a single call — drastically reduces API quota usage at session end / /compact. When `memories` is provided, single-memory params (key/content/...) are ignored. TIPS for better recall later: (1) Set `validFrom`/`validTo` for time-bound facts so search auto-filters stale memories; (2) Pin durable identity facts via `isPinned: true`. IMPORTANT: Call as MCP tool, not shell command.",
|
|
44
44
|
inputSchema: {
|
|
45
45
|
type: "object",
|
|
46
46
|
properties: {
|
|
47
47
|
projectId: { type: "string", description: "Optional. Only use if cross-saving to a different Context Core ID." },
|
|
48
|
-
key: { type: "string", description: "Unique identifier for this memory" },
|
|
49
|
-
content: { type: "string", description: "The content to remember" },
|
|
48
|
+
key: { type: "string", description: "Unique identifier for this memory (single-memory mode)" },
|
|
49
|
+
content: { type: "string", description: "The content to remember (single-memory mode)" },
|
|
50
50
|
title: { type: "string", description: "Optional title" },
|
|
51
|
-
tags: {
|
|
52
|
-
type: "array",
|
|
53
|
-
items: { type: "string" },
|
|
51
|
+
tags: {
|
|
52
|
+
type: "array",
|
|
53
|
+
items: { type: "string" },
|
|
54
54
|
description: "List of tags, e.g. ['planning', 'frontend']"
|
|
55
|
+
},
|
|
56
|
+
validFrom: {
|
|
57
|
+
type: "string",
|
|
58
|
+
description: "Optional ISO-8601 date — memory is hidden from search before this date. Use for facts that take effect later (e.g., new policy). Omit for always-valid memories."
|
|
59
|
+
},
|
|
60
|
+
validTo: {
|
|
61
|
+
type: "string",
|
|
62
|
+
description: "Optional ISO-8601 date — memory expires from search after this date. Use for time-bound facts (deadlines, sprint goals, expiring promotions). Omit for never-expiring."
|
|
63
|
+
},
|
|
64
|
+
isPinned: {
|
|
65
|
+
type: "boolean",
|
|
66
|
+
description: "Mark as pinned to boost in search ranking. Reserve for high-importance identity/anchor facts (project name, user role, key constraints)."
|
|
67
|
+
},
|
|
68
|
+
memories: {
|
|
69
|
+
type: "array",
|
|
70
|
+
description: "OPTIONAL. For batch storing up to 50 memories in one call (saves API quota at /compact / session end). Each item has same shape as single-memory params (key, content, tags, title, validFrom, validTo, isPinned). When provided, single-memory params (key/content/...) are ignored. Returns per-item success/error in `data.results`.",
|
|
71
|
+
maxItems: 50,
|
|
72
|
+
items: {
|
|
73
|
+
type: "object",
|
|
74
|
+
properties: {
|
|
75
|
+
key: { type: "string" },
|
|
76
|
+
content: { type: "string" },
|
|
77
|
+
title: { type: "string" },
|
|
78
|
+
tags: { type: "array", items: { type: "string" } },
|
|
79
|
+
validFrom: { type: "string" },
|
|
80
|
+
validTo: { type: "string" },
|
|
81
|
+
isPinned: { type: "boolean" }
|
|
82
|
+
},
|
|
83
|
+
required: ["key", "content"]
|
|
84
|
+
}
|
|
55
85
|
}
|
|
56
86
|
},
|
|
57
|
-
required: [
|
|
87
|
+
required: [],
|
|
58
88
|
},
|
|
59
89
|
},
|
|
60
90
|
{
|
|
@@ -71,13 +101,22 @@ export function createMcpServerInstance(
|
|
|
71
101
|
},
|
|
72
102
|
{
|
|
73
103
|
name: "munin_search_memories",
|
|
74
|
-
description: "
|
|
104
|
+
description: "Hybrid 6-signal search (keyword + semantic + named-entity + quoted-phrase + recency + pinned). QUERY TIPS to lift recall: (1) Wrap exact strings in double quotes — e.g., `\"Project Munin v1.3\"` — to trigger quoted-phrase boost (+0.25); (2) Include capitalized names (people, products, places) for name-entity boost (+0.15); (3) Use `filters.since`/`before` for temporal scoping (relative strings supported: 'yesterday', 'last week', '7 days ago'). Returns token-efficient GraphRAG context with mermaid graph. IMPORTANT: Call as MCP tool.",
|
|
75
105
|
inputSchema: {
|
|
76
106
|
type: "object",
|
|
77
107
|
properties: {
|
|
78
108
|
projectId: { type: "string", description: "Optional. The Munin Context Core ID." },
|
|
79
|
-
query: { type: "string", description: "Search query" },
|
|
80
|
-
tags: { type: "array", items: { type: "string" } },
|
|
109
|
+
query: { type: "string", description: "Search query. Tip: wrap exact phrases in quotes for boost; capitalize entity names." },
|
|
110
|
+
tags: { type: "array", items: { type: "string" }, description: "Filter results to memories containing these tags" },
|
|
111
|
+
tagMode: { type: "string", enum: ["or", "and"], description: "Tag combination: 'or' (any match) or 'and' (all match). Default: 'or'." },
|
|
112
|
+
filters: {
|
|
113
|
+
type: "object",
|
|
114
|
+
description: "Temporal filter on memory createdAt. Supports ISO-8601 dates AND relative strings: 'yesterday', 'last week', 'last month', 'last year', '7 days ago', '3 weeks ago', etc.",
|
|
115
|
+
properties: {
|
|
116
|
+
since: { type: "string", description: "Memories created on/after this date (e.g., 'last week', '2026-04-01')" },
|
|
117
|
+
before: { type: "string", description: "Memories created on/before this date" }
|
|
118
|
+
}
|
|
119
|
+
},
|
|
81
120
|
topK: { type: "number", description: "Max results to return (default: 10, max: 50)" },
|
|
82
121
|
offset: { type: "number", description: "Pagination offset for fetching more results (default: 0)" },
|
|
83
122
|
includeTotal: { type: "boolean", description: "If true, includes total count in response (default: false)" },
|
|
@@ -112,7 +151,7 @@ export function createMcpServerInstance(
|
|
|
112
151
|
},
|
|
113
152
|
{
|
|
114
153
|
name: "munin_share_memory",
|
|
115
|
-
description: "Share one or more memories to other projects owned by the same user. The target project must share the same Hash Key to read encrypted content.
|
|
154
|
+
description: "Share one or more memories to other projects owned by the same user. The target project must share the same Hash Key to read encrypted content. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
116
155
|
inputSchema: {
|
|
117
156
|
type: "object",
|
|
118
157
|
properties: {
|
|
@@ -142,6 +181,82 @@ export function createMcpServerInstance(
|
|
|
142
181
|
required: [],
|
|
143
182
|
},
|
|
144
183
|
},
|
|
184
|
+
{
|
|
185
|
+
name: "munin_versions",
|
|
186
|
+
description: "List all versions of a memory (version history). Use this to review past changes before rolling back. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
187
|
+
inputSchema: {
|
|
188
|
+
type: "object",
|
|
189
|
+
properties: {
|
|
190
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
191
|
+
key: { type: "string", description: "Memory key (provide this OR id, not both)" },
|
|
192
|
+
id: { type: "string", description: "Memory ID (provide this OR key, not both)" },
|
|
193
|
+
},
|
|
194
|
+
oneOf: [
|
|
195
|
+
{ required: ["key"] },
|
|
196
|
+
{ required: ["id"] },
|
|
197
|
+
],
|
|
198
|
+
},
|
|
199
|
+
},
|
|
200
|
+
{
|
|
201
|
+
name: "munin_rollback",
|
|
202
|
+
description: "Rollback a memory to a previous version. Run munin_versions first to find the version number. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
203
|
+
inputSchema: {
|
|
204
|
+
type: "object",
|
|
205
|
+
properties: {
|
|
206
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
207
|
+
key: { type: "string", description: "Memory key (provide this OR id, not both)" },
|
|
208
|
+
id: { type: "string", description: "Memory ID (provide this OR key, not both)" },
|
|
209
|
+
version: { type: "number", description: "The version number to rollback to (required)" },
|
|
210
|
+
},
|
|
211
|
+
required: ["version"],
|
|
212
|
+
oneOf: [
|
|
213
|
+
{ required: ["key"] },
|
|
214
|
+
{ required: ["id"] },
|
|
215
|
+
],
|
|
216
|
+
},
|
|
217
|
+
},
|
|
218
|
+
{
|
|
219
|
+
name: "munin_diff_memory",
|
|
220
|
+
description: "Compare two specific versions of the same memory. Returns a diff showing what changed between v1 and v2. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
221
|
+
inputSchema: {
|
|
222
|
+
type: "object",
|
|
223
|
+
properties: {
|
|
224
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
225
|
+
key: { type: "string", description: "Memory key" },
|
|
226
|
+
v1: { type: "number", description: "First version number" },
|
|
227
|
+
v2: { type: "number", description: "Second version number" },
|
|
228
|
+
},
|
|
229
|
+
required: ["key", "v1", "v2"],
|
|
230
|
+
},
|
|
231
|
+
},
|
|
232
|
+
{
|
|
233
|
+
name: "munin_delete_memory",
|
|
234
|
+
description: "Permanently delete a memory by key or id from the current Munin Context Core. This action is destructive and cannot be undone — the memory and all its version history are removed. Use with caution. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
|
|
235
|
+
inputSchema: {
|
|
236
|
+
type: "object",
|
|
237
|
+
properties: {
|
|
238
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
239
|
+
key: { type: "string", description: "Memory key (provide this OR id, not both)" },
|
|
240
|
+
id: { type: "string", description: "Memory ID (provide this OR key, not both)" }
|
|
241
|
+
},
|
|
242
|
+
oneOf: [
|
|
243
|
+
{ required: ["key"] },
|
|
244
|
+
{ required: ["id"] }
|
|
245
|
+
]
|
|
246
|
+
}
|
|
247
|
+
},
|
|
248
|
+
{
|
|
249
|
+
name: "munin_acknowledge_setup",
|
|
250
|
+
description: "Acknowledge that you have read the latest Munin setup guide. Call this AFTER reading the setup guide URL provided in any ERR_STALE_PROTOCOL response. Subsequent write actions (store, share) will then proceed without setup-version errors. Pass the version exactly as shown in the remediation hint.",
|
|
251
|
+
inputSchema: {
|
|
252
|
+
type: "object",
|
|
253
|
+
properties: {
|
|
254
|
+
projectId: { type: "string", description: "Optional. Defaults to active project." },
|
|
255
|
+
version: { type: "string", description: "Setup version in ISO date format (YYYY-MM-DD), exactly as shown in the ERR_STALE_PROTOCOL remediation hint." }
|
|
256
|
+
},
|
|
257
|
+
required: ["version"]
|
|
258
|
+
}
|
|
259
|
+
},
|
|
145
260
|
],
|
|
146
261
|
};
|
|
147
262
|
});
|
|
@@ -186,6 +301,9 @@ export function createMcpServerInstance(
|
|
|
186
301
|
case "munin_share_memory":
|
|
187
302
|
result = await client.invoke(projectId, "share", enrichedPayload);
|
|
188
303
|
break;
|
|
304
|
+
case "munin_diff_memory":
|
|
305
|
+
result = await client.invoke(projectId, "diff", enrichedPayload);
|
|
306
|
+
break;
|
|
189
307
|
case "munin_get_project_info": {
|
|
190
308
|
const caps = await client.capabilities();
|
|
191
309
|
result = {
|
|
@@ -195,6 +313,30 @@ export function createMcpServerInstance(
|
|
|
195
313
|
};
|
|
196
314
|
break;
|
|
197
315
|
}
|
|
316
|
+
case "munin_versions":
|
|
317
|
+
if (!args.key && !args.id) {
|
|
318
|
+
throw new Error("munin_versions requires either 'key' or 'id' to identify the target memory.");
|
|
319
|
+
}
|
|
320
|
+
result = await client.invoke(projectId, "versions", { key: args.key, id: args.id });
|
|
321
|
+
break;
|
|
322
|
+
case "munin_rollback":
|
|
323
|
+
if (!args.key && !args.id) {
|
|
324
|
+
throw new Error("munin_rollback requires either 'key' or 'id' to identify the target memory.");
|
|
325
|
+
}
|
|
326
|
+
if (typeof args.version !== "number") {
|
|
327
|
+
throw new Error("munin_rollback requires a numeric 'version' to roll back to.");
|
|
328
|
+
}
|
|
329
|
+
result = await client.invoke(projectId, "rollback", { key: args.key, id: args.id, version: args.version });
|
|
330
|
+
break;
|
|
331
|
+
case "munin_delete_memory":
|
|
332
|
+
if (!args.key && !args.id) {
|
|
333
|
+
throw new Error("munin_delete_memory requires either 'key' or 'id' to identify the target memory.");
|
|
334
|
+
}
|
|
335
|
+
result = await client.invoke(projectId, "delete", { key: args.key, id: args.id });
|
|
336
|
+
break;
|
|
337
|
+
case "munin_acknowledge_setup":
|
|
338
|
+
result = await client.invoke(projectId, "acknowledge_setup", { version: args.version });
|
|
339
|
+
break;
|
|
198
340
|
default:
|
|
199
341
|
throw new Error(`Unknown tool: ${request.params.name}`);
|
|
200
342
|
}
|