@kalera/munin-runtime 1.2.0 → 1.2.5

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @kalera/munin-runtime@1.2.0 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
+> @kalera/munin-runtime@1.2.5 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
 > tsc -p tsconfig.json
 

package/dist/env.d.ts

@@ -0,0 +1,14 @@
+export interface EnvVar {
+    key: string;
+    value: string;
+}
+/**
+ * Resolve the encryption key for E2EE projects from MUNIN_ENCRYPTION_KEY env var.
+ */
+export declare function resolveEncryptionKey(): string | undefined;
+/**
+ * Upsert key=value pairs into a .env file.
+ * - Existing keys are replaced.
+ * - New keys are appended.
+ */
+export declare function writeEnvFile(filename: string, vars: EnvVar[], cwd?: string): void;

package/dist/env.js

@@ -0,0 +1,34 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Resolve the encryption key for E2EE projects from MUNIN_ENCRYPTION_KEY env var.
+ */
+export function resolveEncryptionKey() {
+    return process.env.MUNIN_ENCRYPTION_KEY;
+}
+/**
+ * Upsert key=value pairs into a .env file.
+ * - Existing keys are replaced.
+ * - New keys are appended.
+ */
+export function writeEnvFile(filename, vars, cwd = process.cwd()) {
+    const filePath = path.resolve(cwd, filename);
+    let lines = [];
+    if (fs.existsSync(filePath)) {
+        lines = fs.readFileSync(filePath, "utf8").split("\n");
+    }
+    for (const { key, value } of vars) {
+        const escapedValue = value.replace(/"/g, '\\"');
+        const newLine = `${key}="${escapedValue}"`;
+        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const regex = new RegExp(`^${escapedKey}\\s*=.+$`, "m");
+        const idx = lines.findIndex((l) => regex.test(l));
+        if (idx !== -1) {
+            lines[idx] = newLine;
+        }
+        else {
+            lines.push(newLine);
+        }
+    }
+    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+}

package/dist/index.d.ts

@@ -11,6 +11,14 @@ export interface CliEnv {
 }
 export declare function parseCliArgs(argv: string[], usage: string): ParsedCliArgs;
 export declare function loadCliEnv(): CliEnv;
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in current working directory
+ * 3. .env in current working directory
+ */
+export declare function resolveProjectId(): string | undefined;
 export declare function executeWithRetry<T>(task: () => Promise<T>, retries: number, backoffMs: number): Promise<T>;
 export declare function safeError(error: unknown): Record<string, unknown>;
 export * from "./mcp-server.js";
+export * from "./env.js";

package/dist/index.js

@@ -19,13 +19,55 @@ export function parseCliArgs(argv, usage) {
 }
 export function loadCliEnv() {
     return {
-        baseUrl: "https://munin.kalera.dev",
+        baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
         apiKey: process.env.MUNIN_API_KEY,
         timeoutMs: Number(process.env.MUNIN_TIMEOUT_MS ?? 15000),
         retries: Number(process.env.MUNIN_RETRIES ?? 3),
         backoffMs: Number(process.env.MUNIN_BACKOFF_MS ?? 300),
     };
 }
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in current working directory
+ * 3. .env in current working directory
+ */
+export function resolveProjectId() {
+    // 1. Explicit env var (highest priority)
+    if (process.env.MUNIN_PROJECT) {
+        return process.env.MUNIN_PROJECT;
+    }
+    // 2. .env.local in CWD
+    const envLocal = resolveEnvFile(".env.local");
+    if (envLocal)
+        return envLocal;
+    // 3. .env in CWD
+    const envFile = resolveEnvFile(".env");
+    if (envFile)
+        return envFile;
+    return undefined;
+}
+/**
+ * Read a .env file and extract MUNIN_PROJECT value.
+ * Returns undefined if file doesn't exist or value not found.
+ */
+function resolveEnvFile(filename) {
+    try {
+        const path = `${process.cwd()}/${filename}`;
+        const fs = require("fs");
+        if (!fs.existsSync(path))
+            return undefined;
+        const content = fs.readFileSync(path, "utf8");
+        const match = content.match(/^MUNIN_PROJECT\s*=\s*(.+)$/m);
+        if (match) {
+            return match[1].trim();
+        }
+    }
+    catch {
+        // Ignore errors — file might be unreadable
+    }
+    return undefined;
+}
 export async function executeWithRetry(task, retries, backoffMs) {
     let attempt = 0;
     let lastError;
@@ -64,3 +106,4 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 export * from "./mcp-server.js";
+export * from "./env.js";

package/dist/mcp-server.d.ts

@@ -1 +1,37 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { loadCliEnv } from "./index.js";
+export declare function createMcpServerInstance(env: ReturnType<typeof loadCliEnv>): Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
 export declare function startMcpServer(): Promise<void>;

package/dist/mcp-server.js

@@ -2,12 +2,11 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { MuninClient } from "@kalera/munin-sdk";
-import { loadCliEnv, safeError } from "./index.js";
-export async function startMcpServer() {
-    const env = loadCliEnv();
+import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
+export function createMcpServerInstance(env) {
     const client = new MuninClient({
         baseUrl: env.baseUrl,
-        apiKey: env.apiKey,
+        apiKey: env.apiKey || 'test-key',
         timeoutMs: env.timeoutMs,
     });
     const server = new Server({
@@ -54,27 +53,29 @@ export async function startMcpServer() {
                 },
                 {
                     name: "munin_search_memories",
-                    description: "Search for memories using semantic search or keywords. Returns formatted, token-efficient GraphRAG context. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
+                    description: "Search for memories using semantic search or keywords. Returns formatted, token-efficient GraphRAG context. Supports pagination with topK/offset and optional total count. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             projectId: { type: "string", description: "Optional. The Munin Context Core ID." },
                             query: { type: "string", description: "Search query" },
                             tags: { type: "array", items: { type: "string" } },
-                            limit: { type: "number", description: "Max results (default: 10)" },
+                            topK: { type: "number", description: "Max results to return (default: 10, max: 50)" },
+                            offset: { type: "number", description: "Pagination offset for fetching more results (default: 0)" },
+                            includeTotal: { type: "boolean", description: "If true, includes total count in response (default: false)" },
                         },
                         required: ["query"],
                     },
                 },
                 {
                     name: "munin_list_memories",
-                    description: "List all memories with pagination. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
+                    description: "List all memories with pagination support. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             projectId: { type: "string", description: "Optional. The Munin Context Core ID." },
-                            limit: { type: "number" },
-                            offset: { type: "number" },
+                            limit: { type: "number", description: "Max results to return (default: 10, max: 100)" },
+                            offset: { type: "number", description: "Pagination offset (default: 0)" },
                         },
                         required: [],
                     },
@@ -91,35 +92,83 @@ export async function startMcpServer() {
                         required: [],
                     },
                 },
+                {
+                    name: "munin_share_memory",
+                    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. Requires Pro or Elite tier. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            projectId: { type: "string", description: "Optional. The source project ID." },
+                            memoryIds: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Array of memory IDs to share",
+                            },
+                            targetProjectIds: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Array of target project IDs to share memories into",
+                            },
+                        },
+                        required: ["memoryIds", "targetProjectIds"],
+                    },
+                },
+                {
+                    name: "munin_get_project_info",
+                    description: "Get current project metadata including E2EE status, tier features, and limits. CRITICAL: Before storing or retrieving memories in an E2EE project, verify the encryption key is set correctly. Shows whether MUNIN_ENCRYPTION_KEY is configured. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            projectId: { type: "string", description: "Optional. Defaults to active project." },
+                        },
+                        required: [],
+                    },
+                },
             ],
         };
     });
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         try {
             const args = request.params.arguments || {};
-            const projectId = args.projectId || process.env.MUNIN_PROJECT;
+            // Priority: explicit arg > env var > CWD .env file
+            const projectId = args.projectId || resolveProjectId();
             if (!projectId) {
-                throw new Error("projectId is required in arguments or MUNIN_PROJECT environment variable");
+                throw new Error("projectId is required. Ensure MUNIN_PROJECT is set in .env or .env.local in your project directory, or passed as an argument.");
             }
             // Remove projectId from args before sending as payload
             const { projectId: _ignored, ...payload } = args;
+            // Auto-inject encryptionKey from env if not explicitly provided
+            const encryptionKey = args.encryptionKey || resolveEncryptionKey();
+            const enrichedPayload = encryptionKey ? { ...payload, encryptionKey } : payload;
             let result;
             switch (request.params.name) {
                 case "munin_store_memory":
-                    result = await client.store(projectId, payload);
+                    result = await client.store(projectId, enrichedPayload);
                     break;
                 case "munin_retrieve_memory":
-                    result = await client.retrieve(projectId, payload);
+                    result = await client.retrieve(projectId, enrichedPayload);
                     break;
                 case "munin_search_memories":
-                    result = await client.search(projectId, payload);
+                    result = await client.search(projectId, enrichedPayload);
                     break;
                 case "munin_list_memories":
-                    result = await client.list(projectId, payload);
+                    result = await client.list(projectId, enrichedPayload);
                     break;
                 case "munin_recent_memories":
-                    result = await client.recent(projectId, payload);
+                    result = await client.recent(projectId, enrichedPayload);
+                    break;
+                case "munin_share_memory":
+                    result = await client.invoke(projectId, "share", enrichedPayload);
+                    break;
+                case "munin_get_project_info": {
+                    const caps = await client.capabilities();
+                    result = {
+                        ok: true,
+                        encryptionKeyConfigured: !!encryptionKey,
+                        ...caps,
+                    };
                     break;
+                }
                 default:
                     throw new Error(`Unknown tool: ${request.params.name}`);
             }
@@ -145,6 +194,11 @@ export async function startMcpServer() {
             };
         }
     });
+    return server;
+}
+export async function startMcpServer() {
+    const env = loadCliEnv();
+    const server = createMcpServerInstance(env);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Munin MCP Server running on stdio");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalera/munin-runtime",
-  "version": "1.2.0",
+  "version": "1.2.5",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@kalera/munin-sdk": "1.2.0"
+    "@kalera/munin-sdk": "1.2.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/env.ts

@@ -0,0 +1,48 @@
+import * as fs from "fs";
+import * as path from "path";
+
+export interface EnvVar {
+  key: string;
+  value: string;
+}
+
+/**
+ * Resolve the encryption key for E2EE projects from MUNIN_ENCRYPTION_KEY env var.
+ */
+export function resolveEncryptionKey(): string | undefined {
+  return process.env.MUNIN_ENCRYPTION_KEY;
+}
+
+/**
+ * Upsert key=value pairs into a .env file.
+ * - Existing keys are replaced.
+ * - New keys are appended.
+ */
+export function writeEnvFile(
+  filename: string,
+  vars: EnvVar[],
+  cwd: string = process.cwd(),
+): void {
+  const filePath = path.resolve(cwd, filename);
+  let lines: string[] = [];
+
+  if (fs.existsSync(filePath)) {
+    lines = fs.readFileSync(filePath, "utf8").split("\n");
+  }
+
+  for (const { key, value } of vars) {
+    const escapedValue = value.replace(/"/g, '\\"');
+    const newLine = `${key}="${escapedValue}"`;
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^${escapedKey}\\s*=.+$`, "m");
+
+    const idx = lines.findIndex((l) => regex.test(l));
+    if (idx !== -1) {
+      lines[idx] = newLine;
+    } else {
+      lines.push(newLine);
+    }
+  }
+
+  fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+}

package/src/index.ts

@@ -35,7 +35,7 @@ export function parseCliArgs(argv: string[], usage: string): ParsedCliArgs {
 
 export function loadCliEnv(): CliEnv {
   return {
-    baseUrl: "https://munin.kalera.dev",
+    baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
     apiKey: process.env.MUNIN_API_KEY,
     timeoutMs: Number(process.env.MUNIN_TIMEOUT_MS ?? 15000),
     retries: Number(process.env.MUNIN_RETRIES ?? 3),
@@ -43,6 +43,50 @@ export function loadCliEnv(): CliEnv {
   };
 }
 
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in current working directory
+ * 3. .env in current working directory
+ */
+export function resolveProjectId(): string | undefined {
+  // 1. Explicit env var (highest priority)
+  if (process.env.MUNIN_PROJECT) {
+    return process.env.MUNIN_PROJECT;
+  }
+
+  // 2. .env.local in CWD
+  const envLocal = resolveEnvFile(".env.local");
+  if (envLocal) return envLocal;
+
+  // 3. .env in CWD
+  const envFile = resolveEnvFile(".env");
+  if (envFile) return envFile;
+
+  return undefined;
+}
+
+/**
+ * Read a .env file and extract MUNIN_PROJECT value.
+ * Returns undefined if file doesn't exist or value not found.
+ */
+function resolveEnvFile(filename: string): string | undefined {
+  try {
+    const path = `${process.cwd()}/${filename}`;
+    const fs = require("fs") as typeof import("fs");
+    if (!fs.existsSync(path)) return undefined;
+
+    const content = fs.readFileSync(path, "utf8");
+    const match = content.match(/^MUNIN_PROJECT\s*=\s*(.+)$/m);
+    if (match) {
+      return match[1].trim();
+    }
+  } catch {
+    // Ignore errors — file might be unreadable
+  }
+  return undefined;
+}
+
 export async function executeWithRetry<T>(
   task: () => Promise<T>,
   retries: number,
@@ -90,3 +134,4 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 export * from "./mcp-server.js";
+export * from "./env.js";

package/src/mcp-server.ts

@@ -5,14 +5,12 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { MuninClient } from "@kalera/munin-sdk";
-import { loadCliEnv, safeError } from "./index.js";
-
-export async function startMcpServer() {
-  const env = loadCliEnv();
+import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
 
+export function createMcpServerInstance(env: ReturnType<typeof loadCliEnv>) {
   const client = new MuninClient({
     baseUrl: env.baseUrl,
-    apiKey: env.apiKey,
+    apiKey: env.apiKey || 'test-key',
     timeoutMs: env.timeoutMs,
   });
 
@@ -64,27 +62,29 @@ export async function startMcpServer() {
         },
         {
           name: "munin_search_memories",
-          description: "Search for memories using semantic search or keywords. Returns formatted, token-efficient GraphRAG context. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
+          description: "Search for memories using semantic search or keywords. Returns formatted, token-efficient GraphRAG context. Supports pagination with topK/offset and optional total count. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
           inputSchema: {
             type: "object",
             properties: {
               projectId: { type: "string", description: "Optional. The Munin Context Core ID." },
               query: { type: "string", description: "Search query" },
               tags: { type: "array", items: { type: "string" } },
-              limit: { type: "number", description: "Max results (default: 10)" },
+              topK: { type: "number", description: "Max results to return (default: 10, max: 50)" },
+              offset: { type: "number", description: "Pagination offset for fetching more results (default: 0)" },
+              includeTotal: { type: "boolean", description: "If true, includes total count in response (default: false)" },
             },
             required: ["query"],
           },
         },
         {
           name: "munin_list_memories",
-          description: "List all memories with pagination. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
+          description: "List all memories with pagination support. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
           inputSchema: {
             type: "object",
             properties: {
               projectId: { type: "string", description: "Optional. The Munin Context Core ID." },
-              limit: { type: "number" },
-              offset: { type: "number" },
+              limit: { type: "number", description: "Max results to return (default: 10, max: 100)" },
+              offset: { type: "number", description: "Pagination offset (default: 0)" },
             },
             required: [],
           },
@@ -101,6 +101,38 @@ export async function startMcpServer() {
             required: [],
           },
         },
+        {
+          name: "munin_share_memory",
+          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. Requires Pro or Elite tier. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              projectId: { type: "string", description: "Optional. The source project ID." },
+              memoryIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of memory IDs to share",
+              },
+              targetProjectIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of target project IDs to share memories into",
+              },
+            },
+            required: ["memoryIds", "targetProjectIds"],
+          },
+        },
+        {
+          name: "munin_get_project_info",
+          description: "Get current project metadata including E2EE status, tier features, and limits. CRITICAL: Before storing or retrieving memories in an E2EE project, verify the encryption key is set correctly. Shows whether MUNIN_ENCRYPTION_KEY is configured. IMPORTANT: Call this as an MCP tool, NOT as a shell command.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              projectId: { type: "string", description: "Optional. Defaults to active project." },
+            },
+            required: [],
+          },
+        },
       ],
     };
   });
@@ -108,33 +140,52 @@ export async function startMcpServer() {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
       const args = request.params.arguments || {};
-      const projectId = (args.projectId as string) || process.env.MUNIN_PROJECT;
-      
+      // Priority: explicit arg > env var > CWD .env file
+      const projectId = (args.projectId as string) || resolveProjectId();
+
       if (!projectId) {
-        throw new Error("projectId is required in arguments or MUNIN_PROJECT environment variable");
+        throw new Error(
+          "projectId is required. Ensure MUNIN_PROJECT is set in .env or .env.local in your project directory, or passed as an argument."
+        );
       }
 
       // Remove projectId from args before sending as payload
       const { projectId: _ignored, ...payload } = args;
 
+      // Auto-inject encryptionKey from env if not explicitly provided
+      const encryptionKey = (args.encryptionKey as string) || resolveEncryptionKey();
+      const enrichedPayload = encryptionKey ? { ...payload, encryptionKey } : payload;
+
       let result;
 
       switch (request.params.name) {
         case "munin_store_memory":
-          result = await client.store(projectId, payload);
+          result = await client.store(projectId, enrichedPayload);
           break;
         case "munin_retrieve_memory":
-          result = await client.retrieve(projectId, payload);
+          result = await client.retrieve(projectId, enrichedPayload);
           break;
         case "munin_search_memories":
-          result = await client.search(projectId, payload);
+          result = await client.search(projectId, enrichedPayload);
           break;
         case "munin_list_memories":
-          result = await client.list(projectId, payload);
+          result = await client.list(projectId, enrichedPayload);
           break;
         case "munin_recent_memories":
-          result = await client.recent(projectId, payload);
+          result = await client.recent(projectId, enrichedPayload);
           break;
+        case "munin_share_memory":
+          result = await client.invoke(projectId, "share", enrichedPayload);
+          break;
+        case "munin_get_project_info": {
+          const caps = await client.capabilities();
+          result = {
+            ok: true,
+            encryptionKeyConfigured: !!encryptionKey,
+            ...caps,
+          };
+          break;
+        }
         default:
           throw new Error(`Unknown tool: ${request.params.name}`);
       }
@@ -161,6 +212,13 @@ export async function startMcpServer() {
     }
   });
 
+  return server;
+}
+
+export async function startMcpServer() {
+  const env = loadCliEnv();
+  const server = createMcpServerInstance(env);
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error("Munin MCP Server running on stdio");