@kalera/munin-runtime 1.2.0 → 1.2.6

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.6 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
 > tsc -p tsconfig.json
 

package/dist/env.d.ts

@@ -0,0 +1,37 @@
+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.
+ * - Keys are matched via string split (not regex) to prevent injection.
+ */
+export declare function writeEnvFile(filename: string, vars: EnvVar[], cwd?: string): void;
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+export declare function resolveProjectId(): string | undefined;
+export interface CliEnv {
+    baseUrl: string;
+    apiKey: string | undefined;
+    timeoutMs: number;
+    retries: number;
+    backoffMs: number;
+}
+export declare function loadCliEnv(): CliEnv;
+export declare function executeWithRetry<T>(task: () => Promise<T>, retries: number, backoffMs: number): Promise<T>;
+export declare function safeError(error: unknown): Record<string, unknown>;
+export declare function parseCliArgs(argv: string[], usage: string): {
+    action: string;
+    payload: Record<string, unknown>;
+};
+export * from "./mcp-server.js";

package/dist/env.js

@@ -0,0 +1,201 @@
+import * as fs from "fs";
+import * as path from "path";
+const REDACT_KEYS = ["apiKey", "authorization", "token", "secret", "password"];
+/**
+ * Resolve the encryption key for E2EE projects from MUNIN_ENCRYPTION_KEY env var.
+ */
+export function resolveEncryptionKey() {
+    return process.env.MUNIN_ENCRYPTION_KEY;
+}
+/**
+ * Escape shell/metacharacters that could inject into a .env value.
+ * Escapes: $, backticks, \, and newlines — in addition to double quotes.
+ */
+function escapeEnvValue(value) {
+    return value
+        .replace(/\\/g, "\\\\") // escape backslashes first
+        .replace(/\n/g, "\\n") // escape newlines
+        .replace(/\r/g, "\\r") // escape carriage returns
+        .replace(/`/g, "\\`") // escape backticks
+        .replace(/\$/g, "\\$") // escape dollar signs
+        .replace(/"/g, '\\"'); // escape double quotes
+}
+/**
+ * Parse a .env line, returning { key, value } or null if not a valid assignment.
+ * Uses a string-based split instead of regex to avoid injection from .env content.
+ */
+function parseEnvLine(line) {
+    // Skip empty lines and comments
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1)
+        return null;
+    const key = trimmed.slice(0, eqIndex).trim();
+    // Value is everything after the first '=' (unquoted, no regex)
+    const rawValue = trimmed.slice(eqIndex + 1);
+    return { key, value: rawValue };
+}
+/**
+ * Upsert key=value pairs into a .env file.
+ * - Existing keys are replaced.
+ * - New keys are appended.
+ * - Keys are matched via string split (not regex) to prevent injection.
+ */
+export function writeEnvFile(filename, vars, cwd = process.cwd()) {
+    const filePath = path.resolve(cwd, filename);
+    const lines = [];
+    if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, "utf8");
+        for (const line of content.split("\n")) {
+            const parsed = parseEnvLine(line);
+            // Remove lines that match any key we're about to upsert
+            if (parsed && vars.some((v) => v.key === parsed.key))
+                continue;
+            lines.push(line);
+        }
+    }
+    for (const { key, value } of vars) {
+        const escapedValue = escapeEnvValue(value);
+        lines.push(`${key}="${escapedValue}"`);
+    }
+    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+}
+/**
+ * Safe numeric env parser: returns defaultVal if value is missing or NaN.
+ */
+function safeParseInt(envVal, defaultVal) {
+    if (envVal === undefined)
+        return defaultVal;
+    const parsed = Number(envVal);
+    if (isNaN(parsed))
+        return defaultVal;
+    return parsed;
+}
+/**
+ * Walk up the directory tree from `startDir` (default CWD) toward root,
+ * searching each ancestor for `filename`. Returns the value of the first match.
+ * Stops at filesystem root or when a `.git` dir is found (project boundary).
+ */
+function resolveEnvFileUpward(filename, startDir) {
+    let current = startDir ?? process.cwd();
+    let last = "";
+    while (current !== last) {
+        last = current;
+        const filePath = path.join(current, filename);
+        try {
+            if (fs.existsSync(filePath)) {
+                const content = fs.readFileSync(filePath, "utf8");
+                for (const line of content.split("\n")) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith("MUNIN_PROJECT="))
+                        continue;
+                    return trimmed.slice("MUNIN_PROJECT=".length).trim();
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                console.error(`[munin-runtime] Failed to read ${filePath}:`, error);
+            }
+        }
+        // Stop at git root (project boundary)
+        if (fs.existsSync(path.join(current, ".git")))
+            break;
+        current = path.dirname(current);
+    }
+    return undefined;
+}
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+export function resolveProjectId() {
+    // 1. Explicit env var (highest priority)
+    if (process.env.MUNIN_PROJECT) {
+        return process.env.MUNIN_PROJECT;
+    }
+    // 2. Walk upward from CWD — find .env.local in any ancestor dir
+    const fromLocal = resolveEnvFileUpward(".env.local");
+    if (fromLocal)
+        return fromLocal;
+    // 3. Walk upward from CWD — find .env in any ancestor dir
+    const fromEnv = resolveEnvFileUpward(".env");
+    if (fromEnv)
+        return fromEnv;
+    return undefined;
+}
+export function loadCliEnv() {
+    return {
+        baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
+        apiKey: process.env.MUNIN_API_KEY,
+        timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
+        retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
+        backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
+    };
+}
+export async function executeWithRetry(task, retries, backoffMs) {
+    let attempt = 0;
+    let lastError;
+    while (attempt < retries) {
+        try {
+            return await task();
+        }
+        catch (error) {
+            lastError = error;
+            attempt += 1;
+            if (attempt >= retries)
+                break;
+            const jitter = Math.floor(Math.random() * 100);
+            await sleep(backoffMs * 2 ** attempt + jitter);
+        }
+    }
+    throw lastError;
+}
+export function safeError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: redactText(error.message),
+        };
+    }
+    return { message: redactText(String(error)) };
+}
+function redactText(text) {
+    return REDACT_KEYS.reduce((acc, key) => {
+        // Replace key=value patterns with key=[REDACTED] using simple string split
+        let result = acc;
+        let idx = result.indexOf(`${key}=`);
+        while (idx !== -1) {
+            const endIdx = result.indexOf(/[\s,;]/.test(result[idx + key.length + 1] ?? "")
+                ? result[idx + key.length + 1]
+                : "");
+            const end = endIdx === -1 ? result.length : endIdx;
+            const before = result.slice(0, idx + key.length + 1);
+            const after = result.slice(end);
+            result = `${before}[REDACTED]${after}`;
+            idx = result.indexOf(`${key}=`, idx + key.length + 1);
+        }
+        return result;
+    }, text);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function parseCliArgs(argv, usage) {
+    const [action, payloadRaw] = argv;
+    if (!action)
+        throw new Error(usage);
+    if (!payloadRaw)
+        return { action, payload: {} };
+    try {
+        return { action, payload: JSON.parse(payloadRaw) };
+    }
+    catch {
+        throw new Error("Payload must be valid JSON");
+    }
+}
+export * from "./mcp-server.js";

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 any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+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,28 +19,90 @@ 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),
+        timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
+        retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
+        backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
     };
 }
+function safeParseInt(envVal, defaultVal) {
+    if (envVal === undefined)
+        return defaultVal;
+    const parsed = Number(envVal);
+    return isNaN(parsed) ? defaultVal : parsed;
+}
+/**
+ * Walk up the directory tree from `startDir` (default CWD) toward root,
+ * searching each ancestor for `filename`. Returns the value of the first match.
+ * Stops at filesystem root or when a `.git` dir is found (project boundary).
+ */
+function resolveEnvFileUpward(filename, startDir) {
+    const fs = require("fs");
+    const path = require("path");
+    let current = startDir ?? process.cwd();
+    let last = "";
+    while (current !== last) {
+        last = current;
+        const filePath = path.join(current, filename);
+        try {
+            if (fs.existsSync(filePath)) {
+                const content = fs.readFileSync(filePath, "utf8");
+                for (const line of content.split("\n")) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith("MUNIN_PROJECT="))
+                        continue;
+                    return trimmed.slice("MUNIN_PROJECT=".length).trim();
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                console.error(`[munin-runtime] Failed to read ${filePath}:`, error);
+            }
+        }
+        // Stop at git root (project boundary)
+        if (fs.existsSync(path.join(current, ".git")))
+            break;
+        current = path.dirname(current);
+    }
+    return undefined;
+}
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+export function resolveProjectId() {
+    // 1. Explicit env var (highest priority)
+    if (process.env.MUNIN_PROJECT) {
+        return process.env.MUNIN_PROJECT;
+    }
+    // 2. Walk upward from CWD — find .env.local in any ancestor dir
+    const fromLocal = resolveEnvFileUpward(".env.local");
+    if (fromLocal)
+        return fromLocal;
+    // 3. Walk upward from CWD — find .env in any ancestor dir
+    const fromEnv = resolveEnvFileUpward(".env");
+    if (fromEnv)
+        return fromEnv;
+    return undefined;
+}
 export async function executeWithRetry(task, retries, backoffMs) {
     let attempt = 0;
     let lastError;
-    while (attempt <= retries) {
+    while (attempt < retries) {
         try {
             return await task();
         }
         catch (error) {
             lastError = error;
-            if (attempt === retries) {
+            attempt += 1;
+            if (attempt >= retries)
                 break;
-            }
             const jitter = Math.floor(Math.random() * 100);
             await sleep(backoffMs * 2 ** attempt + jitter);
-            attempt += 1;
         }
     }
     throw lastError;
@@ -64,3 +126,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,39 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { loadCliEnv } from "./index.js";
+export declare function createMcpServerInstance(env: ReturnType<typeof loadCliEnv>, opts?: {
+    allowMissingApiKey?: boolean;
+}): 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,9 +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, opts) {
+    if (!env.apiKey && !opts?.allowMissingApiKey) {
+        throw new Error("MUNIN_API_KEY is required. Set it in your environment or .env file.");
+    }
     const client = new MuninClient({
         baseUrl: env.baseUrl,
         apiKey: env.apiKey,
@@ -54,27 +56,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 +95,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 +197,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.6",
   "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.6"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/env.ts

@@ -0,0 +1,236 @@
+import * as fs from "fs";
+import * as path from "path";
+
+export interface EnvVar {
+  key: string;
+  value: string;
+}
+
+const REDACT_KEYS = ["apiKey", "authorization", "token", "secret", "password"];
+
+/**
+ * Resolve the encryption key for E2EE projects from MUNIN_ENCRYPTION_KEY env var.
+ */
+export function resolveEncryptionKey(): string | undefined {
+  return process.env.MUNIN_ENCRYPTION_KEY;
+}
+
+/**
+ * Escape shell/metacharacters that could inject into a .env value.
+ * Escapes: $, backticks, \, and newlines — in addition to double quotes.
+ */
+function escapeEnvValue(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")       // escape backslashes first
+    .replace(/\n/g, "\\n")       // escape newlines
+    .replace(/\r/g, "\\r")       // escape carriage returns
+    .replace(/`/g, "\\`")        // escape backticks
+    .replace(/\$/g, "\\$")       // escape dollar signs
+    .replace(/"/g, '\\"');       // escape double quotes
+}
+
+/**
+ * Parse a .env line, returning { key, value } or null if not a valid assignment.
+ * Uses a string-based split instead of regex to avoid injection from .env content.
+ */
+function parseEnvLine(line: string): EnvVar | null {
+  // Skip empty lines and comments
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+
+  const eqIndex = trimmed.indexOf("=");
+  if (eqIndex === -1) return null;
+
+  const key = trimmed.slice(0, eqIndex).trim();
+  // Value is everything after the first '=' (unquoted, no regex)
+  const rawValue = trimmed.slice(eqIndex + 1);
+
+  return { key, value: rawValue };
+}
+
+/**
+ * Upsert key=value pairs into a .env file.
+ * - Existing keys are replaced.
+ * - New keys are appended.
+ * - Keys are matched via string split (not regex) to prevent injection.
+ */
+export function writeEnvFile(
+  filename: string,
+  vars: EnvVar[],
+  cwd: string = process.cwd(),
+): void {
+  const filePath = path.resolve(cwd, filename);
+  const lines: string[] = [];
+
+  if (fs.existsSync(filePath)) {
+    const content = fs.readFileSync(filePath, "utf8");
+    for (const line of content.split("\n")) {
+      const parsed = parseEnvLine(line);
+      // Remove lines that match any key we're about to upsert
+      if (parsed && vars.some((v) => v.key === parsed.key)) continue;
+      lines.push(line);
+    }
+  }
+
+  for (const { key, value } of vars) {
+    const escapedValue = escapeEnvValue(value);
+    lines.push(`${key}="${escapedValue}"`);
+  }
+
+  fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+}
+
+/**
+ * Safe numeric env parser: returns defaultVal if value is missing or NaN.
+ */
+function safeParseInt(envVal: string | undefined, defaultVal: number): number {
+  if (envVal === undefined) return defaultVal;
+  const parsed = Number(envVal);
+  if (isNaN(parsed)) return defaultVal;
+  return parsed;
+}
+
+/**
+ * Walk up the directory tree from `startDir` (default CWD) toward root,
+ * searching each ancestor for `filename`. Returns the value of the first match.
+ * Stops at filesystem root or when a `.git` dir is found (project boundary).
+ */
+function resolveEnvFileUpward(filename: string, startDir?: string): string | undefined {
+  let current = startDir ?? process.cwd();
+  let last = "";
+
+  while (current !== last) {
+    last = current;
+    const filePath = path.join(current, filename);
+    try {
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, "utf8");
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("MUNIN_PROJECT=")) continue;
+          return trimmed.slice("MUNIN_PROJECT=".length).trim();
+        }
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        console.error(`[munin-runtime] Failed to read ${filePath}:`, error);
+      }
+    }
+
+    // Stop at git root (project boundary)
+    if (fs.existsSync(path.join(current, ".git"))) break;
+
+    current = path.dirname(current);
+  }
+  return undefined;
+}
+
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+export function resolveProjectId(): string | undefined {
+  // 1. Explicit env var (highest priority)
+  if (process.env.MUNIN_PROJECT) {
+    return process.env.MUNIN_PROJECT;
+  }
+
+  // 2. Walk upward from CWD — find .env.local in any ancestor dir
+  const fromLocal = resolveEnvFileUpward(".env.local");
+  if (fromLocal) return fromLocal;
+
+  // 3. Walk upward from CWD — find .env in any ancestor dir
+  const fromEnv = resolveEnvFileUpward(".env");
+  if (fromEnv) return fromEnv;
+
+  return undefined;
+}
+
+export interface CliEnv {
+  baseUrl: string;
+  apiKey: string | undefined;
+  timeoutMs: number;
+  retries: number;
+  backoffMs: number;
+}
+
+export function loadCliEnv(): CliEnv {
+  return {
+    baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
+    apiKey: process.env.MUNIN_API_KEY,
+    timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
+    retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
+    backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
+  };
+}
+
+export async function executeWithRetry<T>(
+  task: () => Promise<T>,
+  retries: number,
+  backoffMs: number,
+): Promise<T> {
+  let attempt = 0;
+  let lastError: unknown;
+
+  while (attempt < retries) {
+    try {
+      return await task();
+    } catch (error) {
+      lastError = error;
+      attempt += 1;
+      if (attempt >= retries) break;
+      const jitter = Math.floor(Math.random() * 100);
+      await sleep(backoffMs * 2 ** attempt + jitter);
+    }
+  }
+
+  throw lastError;
+}
+
+export function safeError(error: unknown): Record<string, unknown> {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: redactText(error.message),
+    };
+  }
+  return { message: redactText(String(error)) };
+}
+
+function redactText(text: string): string {
+  return REDACT_KEYS.reduce((acc, key) => {
+    // Replace key=value patterns with key=[REDACTED] using simple string split
+    let result = acc;
+    let idx = result.indexOf(`${key}=`);
+    while (idx !== -1) {
+      const endIdx = result.indexOf(/[\s,;]/.test(result[idx + key.length + 1] ?? "")
+        ? result[idx + key.length + 1]
+        : "");
+      const end = endIdx === -1 ? result.length : endIdx;
+      const before = result.slice(0, idx + key.length + 1);
+      const after = result.slice(end);
+      result = `${before}[REDACTED]${after}`;
+      idx = result.indexOf(`${key}=`, idx + key.length + 1);
+    }
+    return result;
+  }, text);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function parseCliArgs(argv: string[], usage: string): { action: string; payload: Record<string, unknown> } {
+  const [action, payloadRaw] = argv;
+  if (!action) throw new Error(usage);
+  if (!payloadRaw) return { action, payload: {} };
+  try {
+    return { action, payload: JSON.parse(payloadRaw) as Record<string, unknown> };
+  } catch {
+    throw new Error("Payload must be valid JSON");
+  }
+}
+
+export * from "./mcp-server.js";

package/src/index.ts

@@ -35,14 +35,82 @@ 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),
-    backoffMs: Number(process.env.MUNIN_BACKOFF_MS ?? 300),
+    timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
+    retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
+    backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
   };
 }
 
+function safeParseInt(envVal: string | undefined, defaultVal: number): number {
+  if (envVal === undefined) return defaultVal;
+  const parsed = Number(envVal);
+  return isNaN(parsed) ? defaultVal : parsed;
+}
+
+/**
+ * Walk up the directory tree from `startDir` (default CWD) toward root,
+ * searching each ancestor for `filename`. Returns the value of the first match.
+ * Stops at filesystem root or when a `.git` dir is found (project boundary).
+ */
+function resolveEnvFileUpward(filename: string, startDir?: string): string | undefined {
+  const fs = require("fs") as typeof import("fs");
+  const path = require("path") as typeof import("path");
+
+  let current = startDir ?? process.cwd();
+  let last = "";
+
+  while (current !== last) {
+    last = current;
+    const filePath = path.join(current, filename);
+    try {
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, "utf8");
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("MUNIN_PROJECT=")) continue;
+          return trimmed.slice("MUNIN_PROJECT=".length).trim();
+        }
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        console.error(`[munin-runtime] Failed to read ${filePath}:`, error);
+      }
+    }
+
+    // Stop at git root (project boundary)
+    if (fs.existsSync(path.join(current, ".git"))) break;
+
+    current = path.dirname(current);
+  }
+  return undefined;
+}
+
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+export function resolveProjectId(): string | undefined {
+  // 1. Explicit env var (highest priority)
+  if (process.env.MUNIN_PROJECT) {
+    return process.env.MUNIN_PROJECT;
+  }
+
+  // 2. Walk upward from CWD — find .env.local in any ancestor dir
+  const fromLocal = resolveEnvFileUpward(".env.local");
+  if (fromLocal) return fromLocal;
+
+  // 3. Walk upward from CWD — find .env in any ancestor dir
+  const fromEnv = resolveEnvFileUpward(".env");
+  if (fromEnv) return fromEnv;
+
+  return undefined;
+}
+
+
 export async function executeWithRetry<T>(
   task: () => Promise<T>,
   retries: number,
@@ -51,17 +119,15 @@ export async function executeWithRetry<T>(
   let attempt = 0;
   let lastError: unknown;
 
-  while (attempt <= retries) {
+  while (attempt < retries) {
     try {
       return await task();
     } catch (error) {
       lastError = error;
-      if (attempt === retries) {
-        break;
-      }
+      attempt += 1;
+      if (attempt >= retries) break;
       const jitter = Math.floor(Math.random() * 100);
       await sleep(backoffMs * 2 ** attempt + jitter);
-      attempt += 1;
     }
   }
 
@@ -90,3 +156,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,10 +5,17 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { MuninClient } from "@kalera/munin-sdk";
-import { loadCliEnv, safeError } from "./index.js";
+import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
 
-export async function startMcpServer() {
-  const env = loadCliEnv();
+export function createMcpServerInstance(
+  env: ReturnType<typeof loadCliEnv>,
+  opts?: { allowMissingApiKey?: boolean },
+) {
+  if (!env.apiKey && !opts?.allowMissingApiKey) {
+    throw new Error(
+      "MUNIN_API_KEY is required. Set it in your environment or .env file.",
+    );
+  }
 
   const client = new MuninClient({
     baseUrl: env.baseUrl,
@@ -64,27 +71,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 +110,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 +149,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 +221,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");