@kalera/munin-runtime 1.2.6 → 1.2.9

package/.turbo/turbo-build.log

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

package/README.md

@@ -0,0 +1,58 @@
+# @kalera/munin-runtime
+
+MCP (Model Context Protocol) server runtime for Munin Context Core. Works with any MCP-compatible client (Claude Code, Cursor, etc.).
+
+## Install
+
+```bash
+npm install @kalera/munin-runtime
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `munin_store_memory` | Store or update a memory |
+| `munin_retrieve_memory` | Retrieve a memory by key |
+| `munin_search_memories` | Semantic/keyword search |
+| `munin_list_memories` | List all memories (paginated) |
+| `munin_recent_memories` | Most recently updated memories |
+| `munin_share_memory` | Share memories across projects |
+| `munin_get_project_info` | Get project metadata and E2EE status |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MUNIN_API_KEY` | Yes | Your Munin API key |
+| `MUNIN_PROJECT` | Yes* | Active project ID (*or pass as tool arg) |
+| `MUNIN_BASE_URL` | No | Default: `https://munin.kalera.dev` |
+| `MUNIN_TIMEOUT_MS` | No | Request timeout (default: 15000) |
+| `MUNIN_ENCRYPTION_KEY` | No | Encryption key for E2EE projects |
+
+## Usage as MCP Server
+
+```bash
+MUNIN_API_KEY=your-key MUNIN_PROJECT=your-project npx @kalera/munin-runtime
+```
+
+## Claude Code Integration
+
+Configure in your `~/.claude/settings.json`:
+
+```json
+{
+  "pluginConfigs": {
+    "munin": {
+      "command": "npx",
+      "args": ["@kalera/munin-runtime"]
+    }
+  }
+}
+```
+
+Set required env vars in your project's `.env` or `.env.local`.
+
+## License
+
+MIT

package/dist/env.d.ts

@@ -1,3 +1,5 @@
+export { parseCliArgs, loadCliEnv, resolveProjectId, executeWithRetry, safeError, } from "./index.js";
+export type { ParsedCliArgs, CliEnv } from "./index.js";
 export interface EnvVar {
     key: string;
     value: string;
@@ -13,25 +15,3 @@ export declare function resolveEncryptionKey(): string | undefined;
  * - 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

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
-const REDACT_KEYS = ["apiKey", "authorization", "token", "secret", "password"];
+// Re-export all shared utilities from index.ts (single source of truth)
+export { parseCliArgs, loadCliEnv, resolveProjectId, executeWithRetry, safeError, } from "./index.js";
 /**
  * Resolve the encryption key for E2EE projects from MUNIN_ENCRYPTION_KEY env var.
  */
@@ -62,140 +63,3 @@ export function writeEnvFile(filename, vars, cwd = process.cwd()) {
     }
     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.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 const REDACT_KEYS = ["apiKey", "authorization", "token", "secret", "password"];
 export function parseCliArgs(argv, usage) {
     const [action, payloadRaw] = argv;
@@ -38,8 +40,6 @@ function safeParseInt(envVal, defaultVal) {
  * 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) {

package/dist/mcp-server.js

@@ -14,7 +14,7 @@ export function createMcpServerInstance(env, opts) {
     });
     const server = new Server({
         name: "munin-mcp-server",
-        version: "1.0.0",
+        version: "1.2.9",
     }, {
         capabilities: {
             tools: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalera/munin-runtime",
-  "version": "1.2.6",
+  "version": "1.2.9",
   "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.6"
+    "@kalera/munin-sdk": "1.2.9"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/env.ts

@@ -1,13 +1,22 @@
 import * as fs from "fs";
 import * as path from "path";
 
+// Re-export all shared utilities from index.ts (single source of truth)
+export {
+  parseCliArgs,
+  loadCliEnv,
+  resolveProjectId,
+  executeWithRetry,
+  safeError,
+} from "./index.js";
+
+export type { ParsedCliArgs, CliEnv } from "./index.js";
+
 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.
  */
@@ -79,158 +88,3 @@ export function writeEnvFile(
 
   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

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import path from "node:path";
+
 export interface ParsedCliArgs {
   action: string;
   payload: Record<string, unknown>;
@@ -55,9 +58,6 @@ function safeParseInt(envVal: string | undefined, defaultVal: number): number {
  * 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 = "";
 
@@ -110,7 +110,6 @@ export function resolveProjectId(): string | undefined {
   return undefined;
 }
 
-
 export async function executeWithRetry<T>(
   task: () => Promise<T>,
   retries: number,
@@ -155,5 +154,6 @@ function redactText(text: string): string {
 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

@@ -26,7 +26,7 @@ export function createMcpServerInstance(
   const server = new Server(
     {
       name: "munin-mcp-server",
-      version: "1.0.0",
+      version: "1.2.9",
     },
     {
       capabilities: {