frinus-mcp 3.1.0 → 3.2.1

package/README.md

@@ -307,6 +307,47 @@ Reusable behaviours assigned to agents.
 | `skill_remove` | Detach a skill from an agent. |
 | `skill_agent_list` | List the skills owned by a given agent. |
 
+### Credential Vault (5) — `credential_exec` broker
+
+Encrypted credentials stored in the Control Plane, referenced from memories via
+`credential_ref`.
+
+| Tool | Description |
+|------|-------------|
+| `credential_store` | Store an encrypted credential under a ref (e.g. `mysql_x`). |
+| `credential_get` | Inspect **non-secret metadata only** (host/user/db/port + the env vars `credential_exec` will inject). Never returns the value. |
+| `credential_exec` | **Run a command with the credential injected into the child process ENV.** Returns only stdout/stderr/exit_code — the secret never reaches the model, screen, or disk. |
+| `credential_list` | List stored credential refs (no secret data). |
+| `credential_delete` | Delete a stored credential. |
+
+**Secret-handling principle — server-side broker, never by value.** The model
+never receives a secret value: no plaintext, no temp files, no shell snippets that
+carry the secret. To *use* a credential you call **`credential_exec`**. The MCP
+server (already running locally via `npx -y frinus-mcp@latest`) fetches the
+credential from the vault, injects its fields into the **environment** of a child
+process — never into argv, never into any text the model sees — runs the command
+with `shell:false` (no shell injection), and returns only the output.
+
+```jsonc
+// MYSQL_PWD / MYSQL_USER / MYSQL_HOST are pre-injected → standard clients just work
+credential_exec(ref="mysql_prod", argv=["mysql", "-e", "SELECT 1"])
+credential_exec(ref="pg_prod",    argv=["psql",  "-c", "SELECT 1"])
+
+// For anything else, read the injected vars inside an explicit shell:
+credential_exec(ref="jira_x", argv=["sh","-c",
+  "curl -sS -H \"Authorization: Bearer $CRED_TOKEN\" \"$CRED_BASE_URL/whoami\""])
+```
+
+Injected env vars (when present in the credential): password/secret/token →
+`MYSQL_PWD`, `PGPASSWORD`, `CRED_PASSWORD`; `user`/`username` → `CRED_USER`,
+`MYSQL_USER`, `PGUSER`; `host` → `CRED_HOST`, `MYSQL_HOST`, `PGHOST`; `port` →
+`CRED_PORT`, `MYSQL_TCP_PORT`, `PGPORT`; `database` → `CRED_DATABASE`,
+`PGDATABASE`; any other scalar → `CRED_<UPPER_SNAKE>` (e.g. `base_url` →
+`CRED_BASE_URL`). `argv` must be an array of strings (no shell command string;
+use `["sh","-c","..."]` if you really need a shell). 30s timeout, 256 KiB output
+cap. Everything ships in the npm package — **the user installs nothing, edits no
+PATH, and runs no extra command**; an up-to-date MCP is all that's required.
+
 ## Memory Types
 
 | Type | Use Case | Example |

package/dist/client/memory-client.d.ts

@@ -39,6 +39,7 @@ export declare class MemoryClient implements MemoryClientInterface {
         metadata?: Record<string, unknown>;
         context_id?: string;
         credential_ref?: string;
+        universe_id?: string;
     }): Promise<any>;
     searchMemories(data: {
         query_text: string;

package/dist/client/memory-client.js

@@ -86,10 +86,12 @@ export class MemoryClient {
             agent_id: data.agent_id,
             content: data.content,
             memory_type: data.memory_type || "episodic",
-            scope: data.scope || "organization",
             importance: data.importance || 0.5,
             metadata: data.metadata,
         };
+        // The handler is the source of truth for scope; only send it when defined.
+        if (data.scope)
+            payload.scope = data.scope;
         if (data.user_id)
             payload.user_id = data.user_id;
         if (data.created_by_user_id)
@@ -98,6 +100,8 @@ export class MemoryClient {
             payload.context_id = data.context_id;
         if (data.credential_ref)
             payload.credential_ref = data.credential_ref;
+        if (data.universe_id)
+            payload.universe_id = data.universe_id;
         const response = await this.client.post("/memories", payload);
         return response.data;
     }

package/dist/tools/definitions.js

@@ -38,7 +38,7 @@ Scopes:
                 scope: {
                     type: "string",
                     enum: ["user", "agent", "universe", "organization"],
-                    description: "Visibility scope: user (private), agent (agent-only), universe (department), organization (org-wide). Default: organization",
+                    description: "Visibility scope. Padrão: a memória é associada ao universo do agente (contexto). 'organization' (org-wide) e 'user' (private) só são usados quando explicitamente definidos; 'agent' (agent-only) é o fallback automático quando não há universo identificável.",
                 },
                 importance: {
                     type: "number",
@@ -56,6 +56,10 @@ Scopes:
                     type: "object",
                     description: "Metadata adicional (tags, universe, idioma, etc.)",
                 },
+                universe_id: {
+                    type: "string",
+                    description: "UUID do universo/contexto ao qual associar a memória. Se omitido, a memória é associada automaticamente ao universo do agente.",
+                },
                 context_id: {
                     type: "string",
                     description: "Optional UUID of a hierarchy node (universe, concept, theme, topic, or point). When provided, the memory is automatically linked to this node and all its ancestors. Takes precedence over universe_id for hierarchy placement.",
@@ -1499,24 +1503,84 @@ to link a memory to this credential.`,
     },
     {
         name: "credential_get",
-        description: `Retrieve a decrypted credential from the vault.
+        description: `Inspect a credential's NON-SECRET metadata — never its value.
 
-Returns the decrypted credential data for the given reference.
-Only the credential owner (authenticated user) can access their credentials.
+This tool returns ONLY non-secret metadata (host/user/db/port), the names of the
+secret fields, and the names of the environment variables that 'credential_exec'
+will inject. The secret VALUE is NEVER returned, so it can never be echoed inline
+into a shell command and leaked on a screen share.
 
-Use this when a memory has a credential_ref and you need the actual
-credentials to perform an action (e.g., connect to a database, call an API).`,
+To actually USE the credential (connect to a DB, call an API), do NOT request the
+value — call 'credential_exec'. It fetches the secret on the server side, injects
+it into the child process environment, runs your command, and returns only the
+output. The secret never reaches you, the screen, or disk.
+
+Only the credential owner (authenticated API key) can access their credentials.`,
         inputSchema: {
             type: "object",
             properties: {
                 ref: {
                     type: "string",
-                    description: "Credential reference to retrieve (e.g., 'jira_muza')",
+                    description: "Credential reference to inspect (e.g., 'jira_muza')",
                 },
             },
             required: ["ref"],
         },
     },
+    {
+        name: "credential_exec",
+        description: `Run a command with a vault credential injected into its environment — the secret NEVER reaches you.
+
+This is the secure way to USE a stored credential. The MCP server (running locally
+via npx) fetches the credential from the vault, injects its fields into the
+ENVIRONMENT of a child process (never into argv, never into any text you see),
+runs your command with shell:false (no shell injection), and returns ONLY
+stdout, stderr, and exit_code. The secret value is never returned to you, never
+printed on screen, never logged, and never written to disk.
+
+Injected environment variables (when present in the credential):
+  - password/secret/token field -> MYSQL_PWD, PGPASSWORD, CRED_PASSWORD
+  - user / username             -> CRED_USER, MYSQL_USER, PGUSER
+  - host / hostname             -> CRED_HOST, MYSQL_HOST, PGHOST
+  - port                        -> CRED_PORT, MYSQL_TCP_PORT, PGPORT
+  - database / db / dbname      -> CRED_DATABASE, PGDATABASE
+  - any other scalar field      -> CRED_<UPPER_SNAKE_NAME> (e.g. base_url -> CRED_BASE_URL)
+
+Because MYSQL_PWD / PGPASSWORD etc. are standard, common clients pick them up
+with no flags:
+  credential_exec(ref="mysql_prod", argv=["mysql", "-e", "SELECT 1"])
+  credential_exec(ref="pg_prod",    argv=["psql", "-c", "SELECT 1"])
+
+For anything else, read the injected vars inside an explicit shell — the secret
+is expanded inside the child, never in text you author:
+  credential_exec(ref="jira_x", argv=["sh", "-c",
+    "curl -sS -H \\"Authorization: Bearer $CRED_TOKEN\\" \\"$CRED_BASE_URL/whoami\\""])
+
+RULES:
+  - 'argv' MUST be an array of strings (program first, then args). A shell command
+    string is NOT accepted; pass ["sh","-c","..."] only when you genuinely need a shell.
+  - NEVER put a secret value in argv or ask for the value — there is no path to it.
+  - 30s timeout; output capped at 256 KiB per stream.`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                ref: {
+                    type: "string",
+                    description: "Credential reference to use (e.g., 'mysql_centerpag', 'jira_muza').",
+                },
+                argv: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Command as an array: program first, then each argument as a separate string. E.g. [\"mysql\", \"-e\", \"SELECT 1\"]. NOT a shell string.",
+                },
+                stdin: {
+                    type: "string",
+                    description: "Optional data to pipe to the command's stdin (e.g. a SQL script).",
+                },
+            },
+            required: ["ref", "argv"],
+        },
+    },
     {
         name: "credential_list",
         description: `List all stored credentials for the current user.

package/dist/tools/handlers.js

@@ -5,8 +5,166 @@
  * and return formatted MCP tool results.
  */
 import axios from "axios";
+import { spawn } from "node:child_process";
 import { getResolvedTenantOrgId } from "../client/memory-client.js";
 // ---------------------------------------------------------------------------
+// Credential delivery — server-side broker, never by value
+// ---------------------------------------------------------------------------
+// SECURITY: agents running in Claude Code render the full bash command string
+// on screen. If a secret value ever enters the agent's text context, the agent
+// can (and historically did) splice it inline into a command like
+// `export MYSQL_PWD='...'`, leaking it in plaintext during screen sharing.
+//
+// The structural fix is to NEVER return the secret value to the model at all,
+// and — going one step further — to never even require the agent to hold the
+// secret as a shell-side reference. The MCP server already runs locally (via
+// `npx -y frinus-mcp@latest`) and already fetches the credential from the
+// Control Plane vault. So the broker lives INSIDE this process as a native
+// tool: `credential_exec`.
+//
+// `credential_exec` fetches the credential, injects the fields into the ENV of
+// a child process (never into argv, never into the model's text), spawns the
+// command with shell:false, and returns ONLY stdout/stderr/exit_code. The
+// secret never enters the tool result, is never logged, and never touches disk.
+// Everything ships in the npm package — the user installs nothing, edits no
+// PATH, and runs no extra command.
+//
+// `credential_get` no longer surfaces any secret-bearing snippet: it returns
+// non-sensitive metadata only and points the agent at `credential_exec`.
+/** Keys (case-insensitive) treated as sensitive when surfacing metadata. */
+const SECRET_KEY_RE = /pass(word|wd)?|secret|token|api[_-]?key|private[_-]?key|credential/i;
+function looksLikePassword(key) {
+    return SECRET_KEY_RE.test(key);
+}
+// ---------------------------------------------------------------------------
+// credential_exec internals
+// ---------------------------------------------------------------------------
+const CRED_EXEC_TIMEOUT_MS = 30_000;
+const CRED_EXEC_MAX_OUTPUT = 256 * 1024; // 256 KiB cap per stream
+/**
+ * Map credential fields onto environment variables for the child process.
+ * The secret value flows ONLY into this env map — never into argv, never into
+ * any returned/ logged text.
+ *
+ *  - Password-like field  -> MYSQL_PWD, PGPASSWORD, CRED_PASSWORD
+ *  - user/username        -> CRED_USER (+ MYSQL_USER, PGUSER)
+ *  - host/hostname        -> CRED_HOST (+ MYSQL_HOST, PGHOST)
+ *  - port                 -> CRED_PORT (+ MYSQL_TCP_PORT, PGPORT)
+ *  - database/db/dbname   -> CRED_DATABASE (+ PGDATABASE)
+ *  - any other scalar     -> CRED_<UPPER_SNAKE> (e.g. base_url -> CRED_BASE_URL)
+ */
+function buildCredentialEnv(data) {
+    const env = {};
+    const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+    let passwordSet = false;
+    let userSet = false;
+    let hostSet = false;
+    let portSet = false;
+    let dbSet = false;
+    for (const [k, v] of Object.entries(data)) {
+        if (!isScalar(v))
+            continue;
+        const val = String(v);
+        const lk = k.toLowerCase();
+        // Generic CRED_<NAME> for every scalar field (raw key, upper-snaked).
+        const credKey = "CRED_" + k.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+        env[credKey] = val;
+        if (!passwordSet && looksLikePassword(k)) {
+            env.CRED_PASSWORD = val;
+            env.MYSQL_PWD = val;
+            env.PGPASSWORD = val;
+            passwordSet = true;
+        }
+        else if (!userSet && (lk === "user" || lk === "username")) {
+            env.CRED_USER = val;
+            env.MYSQL_USER = val;
+            env.PGUSER = val;
+            userSet = true;
+        }
+        else if (!hostSet && (lk === "host" || lk === "hostname")) {
+            env.CRED_HOST = val;
+            env.MYSQL_HOST = val;
+            env.PGHOST = val;
+            hostSet = true;
+        }
+        else if (!portSet && lk === "port") {
+            env.CRED_PORT = val;
+            env.MYSQL_TCP_PORT = val;
+            env.PGPORT = val;
+            portSet = true;
+        }
+        else if (!dbSet && (lk === "database" || lk === "db" || lk === "dbname")) {
+            env.CRED_DATABASE = val;
+            env.PGDATABASE = val;
+            dbSet = true;
+        }
+    }
+    return env;
+}
+/**
+ * Spawn `argv` (program + args, shell:false) with the credential env injected
+ * on top of a minimal copy of the current env. Captures stdout/stderr with a
+ * size cap and a hard timeout. Never throws on a non-zero exit; throws only on
+ * spawn failure (e.g. command not found).
+ */
+function runWithCredEnv(argv, credEnv, stdin) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(argv[0], argv.slice(1), {
+            shell: false,
+            env: { ...process.env, ...credEnv },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let truncated = false;
+        let timedOut = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, CRED_EXEC_TIMEOUT_MS);
+        const append = (buf, chunk) => {
+            if (buf.length >= CRED_EXEC_MAX_OUTPUT) {
+                truncated = true;
+                return buf;
+            }
+            const next = buf + chunk.toString("utf8");
+            if (next.length > CRED_EXEC_MAX_OUTPUT) {
+                truncated = true;
+                return next.slice(0, CRED_EXEC_MAX_OUTPUT);
+            }
+            return next;
+        };
+        child.stdout.on("data", (c) => { stdout = append(stdout, c); });
+        child.stderr.on("data", (c) => { stderr = append(stderr, c); });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                stdout,
+                stderr,
+                exit_code: code,
+                signal: signal ?? null,
+                timed_out: timedOut,
+                truncated,
+            });
+        });
+        if (typeof stdin === "string") {
+            child.stdin.write(stdin);
+        }
+        child.stdin.end();
+    });
+}
+// ---------------------------------------------------------------------------
 // Helper: 401/403 error handling
 // ---------------------------------------------------------------------------
 export function handleApiError(error) {
@@ -42,39 +200,33 @@ const handlers = {
     // ==========================================================================
     // Core Memory
     // ==========================================================================
-    async memory_store(args, { memoryClient, resolvedUserId }) {
+    async memory_store(args, { memoryClient, cpClient, resolvedUserId }) {
+        const createdByUser = args.created_by_user_id || resolvedUserId || undefined;
+        const userId = args.user_id || resolvedUserId || undefined;
+        const meta = args.metadata || {};
+        const universeId = args.universe_id || meta.universe_id || undefined;
+        // Context-first default: when the caller does NOT pass an explicit `scope`,
+        // memories are associated with a CONTEXT (universe). The backend resolves
+        // the universe_id from the agent when none is supplied. `organization` and
+        // `user` are only used when explicitly requested by the caller. When the
+        // agent has no resolvable universe, we fall back to `agent` scope and help
+        // future categorization by returning the list of available universes.
+        const explicitScope = args.scope;
+        const resolvedScope = explicitScope || "universe";
+        const baseInput = {
+            agent_id: args.agent_id,
+            content: args.content,
+            memory_type: args.memory_type,
+            importance: args.importance,
+            user_id: userId,
+            created_by_user_id: createdByUser,
+            metadata: args.metadata,
+            context_id: args.context_id,
+            credential_ref: args.credential_ref,
+            universe_id: universeId,
+        };
         try {
-            const createdByUser = args.created_by_user_id || resolvedUserId || undefined;
-            const userId = args.user_id || resolvedUserId || undefined;
-            // Auto-scope inference: if scope not provided, pick the narrowest
-            // scope justified by the available context. Caller can always pass
-            // an explicit `scope` to override this heuristic.
-            const meta = args.metadata || {};
-            const universeId = args.universe_id || meta.universe_id || undefined;
-            let resolvedScope = args.scope;
-            if (!resolvedScope) {
-                if (userId || createdByUser) {
-                    resolvedScope = "user";
-                }
-                else if (universeId) {
-                    resolvedScope = "universe";
-                }
-                else {
-                    resolvedScope = "organization";
-                }
-            }
-            const result = await memoryClient.storeMemory({
-                agent_id: args.agent_id,
-                content: args.content,
-                memory_type: args.memory_type,
-                scope: resolvedScope,
-                importance: args.importance,
-                user_id: userId,
-                created_by_user_id: createdByUser,
-                metadata: args.metadata,
-                context_id: args.context_id,
-                credential_ref: args.credential_ref,
-            });
+            const result = await memoryClient.storeMemory({ ...baseInput, scope: resolvedScope });
             return {
                 content: [{
                         type: "text",
@@ -83,6 +235,45 @@ const handlers = {
             };
         }
         catch (error) {
+            // Fallback: scope was implicitly "universe" but the agent has no
+            // resolvable universe (backend returns 400 "must be linked to a
+            // universe"). Retry as `agent` scope and surface available universes.
+            const status = error?.response?.status;
+            const detail = String(error?.response?.data?.detail ?? "");
+            const isMissingUniverse = status === 400 &&
+                !explicitScope &&
+                !universeId &&
+                detail.includes("must be linked to a universe");
+            if (isMissingUniverse) {
+                try {
+                    const result = await memoryClient.storeMemory({ ...baseInput, scope: "agent" });
+                    let text = `Memory stored successfully.\nID: ${result.id}\nType: ${result.memory_type}\nScope: ${result.scope}`;
+                    // Enrich with available universes to help future categorization.
+                    try {
+                        const orgId = getResolvedTenantOrgId();
+                        if (orgId) {
+                            const list = await cpClient.listUniverses(orgId);
+                            const universes = Array.isArray(list) ? list : (list.universes || list.items || []);
+                            if (universes && universes.length > 0) {
+                                text += `\n\nDica: esta memória não foi associada a um universo (salva como memória do agente). Para categorizá-la, informe universe_id na próxima vez. Universos disponíveis:`;
+                                universes.forEach((u) => {
+                                    text += `\n- ${u.name} (id: ${u.id})`;
+                                });
+                            }
+                        }
+                    }
+                    catch {
+                        // Listing universes is best-effort; never break a successful store.
+                    }
+                    return { content: [{ type: "text", text }] };
+                }
+                catch (retryError) {
+                    const retryApiErr = handleApiError(retryError);
+                    if (retryApiErr)
+                        return retryApiErr;
+                    throw retryError;
+                }
+            }
             const apiErr = handleApiError(error);
             if (apiErr)
                 return apiErr;
@@ -1472,11 +1663,57 @@ const handlers = {
         try {
             const ref = args.ref;
             const result = await cpClient.getCredential(ref);
+            const data = (result ?? {});
+            // SERVER-SIDE BROKER MODEL: we never return any secret value here, and we
+            // no longer emit shell snippets that handle the secret either. We surface
+            // ONLY non-sensitive metadata (host/user/db/port) plus the names of the
+            // secret fields and the env vars they will populate, and we instruct the
+            // agent to run the command through `credential_exec`, which injects the
+            // secret into the child process env on the server side — the value never
+            // reaches the agent, the screen, or disk.
+            const nonSecret = {};
+            const secretFields = [];
+            const credEnvKeys = Object.keys(buildCredentialEnv(data)).sort();
+            for (const [k, v] of Object.entries(data)) {
+                if (typeof v === "object" && v !== null)
+                    continue;
+                if (looksLikePassword(k))
+                    secretFields.push(k);
+                else
+                    nonSecret[k] = v;
+            }
+            const hasUser = "user" in data || "username" in data;
+            const isDbLike = hasUser && secretFields.length > 0;
+            const lines = [];
+            lines.push(`Credential '${ref}' resolved (metadata only — NO secret value is ever returned).`);
+            lines.push("To USE this credential, call the `credential_exec` tool. It fetches the " +
+                "secret on the server side, injects it into the child process environment, " +
+                "runs your command, and returns ONLY stdout/stderr/exit_code. The secret " +
+                "never enters this text, your context, the screen, or disk.");
+            lines.push("");
+            if (Object.keys(nonSecret).length > 0) {
+                lines.push("Non-secret metadata: " + JSON.stringify(nonSecret));
+            }
+            if (secretFields.length > 0) {
+                lines.push(`Secret fields (handled server-side only): ${secretFields.join(", ")}`);
+            }
+            lines.push(`Env vars injected into the child by credential_exec: ${credEnvKeys.join(", ")}`);
+            lines.push("");
+            lines.push("DO NOT request, print, or inline the secret value. Use credential_exec:");
+            lines.push("");
+            if (isDbLike) {
+                lines.push("# MySQL (MYSQL_PWD / MYSQL_USER / MYSQL_HOST are pre-injected):");
+                lines.push(`credential_exec(ref="${ref}", argv=["mysql", "-e", "SELECT 1"])`);
+                lines.push("");
+                lines.push("# Postgres (PGPASSWORD / PGUSER / PGHOST / PGDATABASE are pre-injected):");
+                lines.push(`credential_exec(ref="${ref}", argv=["psql", "-c", "SELECT 1"])`);
+            }
+            else {
+                lines.push("# Read an injected field inside the command (here CRED_API_KEY, etc.):");
+                lines.push(`credential_exec(ref="${ref}", argv=["sh", "-c", "curl -sS -H \\"Authorization: Bearer $CRED_TOKEN\\" \\"$CRED_BASE_URL/whoami\\""])`);
+            }
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    }],
+                content: [{ type: "text", text: lines.join("\n") }],
             };
         }
         catch (error) {
@@ -1494,6 +1731,90 @@ const handlers = {
             throw error;
         }
     },
+    // credential_exec — server-side broker. Runs a command with the credential
+    // injected into the child process ENV. Returns ONLY stdout/stderr/exit_code.
+    // The secret value never enters the returned text and is never logged.
+    async credential_exec(args, { cpClient }) {
+        const ref = args.ref;
+        const argv = args.argv;
+        const stdin = args.stdin;
+        // Validate argv: must be a non-empty array of strings (program + args).
+        // We deliberately do NOT accept a shell command string — spawn runs with
+        // shell:false to avoid shell injection. The caller can still opt into a
+        // shell explicitly with argv ["sh","-c","..."], which is their choice.
+        if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === "string")) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "argv must be a non-empty array of strings (program + args), e.g. [\"mysql\", \"-e\", \"SELECT 1\"]. A shell command string is not accepted (use [\"sh\", \"-c\", \"...\"] if you really need a shell).",
+                    }],
+                isError: true,
+            };
+        }
+        if (stdin !== undefined && typeof stdin !== "string") {
+            return {
+                content: [{ type: "text", text: "stdin, if provided, must be a string." }],
+                isError: true,
+            };
+        }
+        let credData;
+        try {
+            const result = await cpClient.getCredential(ref);
+            credData = (result ?? {});
+        }
+        catch (error) {
+            if (error?.response?.status === 404) {
+                return {
+                    content: [{ type: "text", text: `No credential found for ref '${ref}'` }],
+                    isError: true,
+                };
+            }
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+        if (Object.keys(credData).length === 0) {
+            return {
+                content: [{ type: "text", text: `Credential '${ref}' has no fields to inject.` }],
+                isError: true,
+            };
+        }
+        const credEnv = buildCredentialEnv(credData);
+        let res;
+        try {
+            res = await runWithCredEnv(argv, credEnv, stdin);
+        }
+        catch (err) {
+            // Spawn failure (e.g. ENOENT command not found). The error message is
+            // about the program/argv, which the caller already provided — no secret.
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to execute command: ${err?.code ? err.code + " " : ""}${err?.message ?? String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+        // Return ONLY non-secret execution results. The credential value lived only
+        // in the child's env; it is not part of stdout/stderr unless the invoked
+        // command itself chose to print it (the caller's responsibility).
+        const summary = [
+            `exit_code: ${res.exit_code}`,
+            res.signal ? `signal: ${res.signal}` : null,
+            res.timed_out ? "timed_out: true (killed after 30s)" : null,
+            res.truncated ? "truncated: true (output capped at 256 KiB)" : null,
+            "",
+            "--- stdout ---",
+            res.stdout.length ? res.stdout : "(empty)",
+            "--- stderr ---",
+            res.stderr.length ? res.stderr : "(empty)",
+        ].filter((l) => l !== null).join("\n");
+        return {
+            content: [{ type: "text", text: summary }],
+            isError: res.exit_code !== 0,
+        };
+    },
     async credential_list(_args, { cpClient }) {
         try {
             const result = await cpClient.listCredentials();

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "manifest_version": "0.2",
+  "manifest_version": "0.3",
   "name": "frinus",
   "display_name": "Frinus — Memória Cognitiva",
   "version": "3.1.0",
@@ -12,7 +12,6 @@
   "homepage": "https://frinus.rdxsec.com.br",
   "documentation": "https://github.com/frinus-ai/frinus-mcp",
   "support": "https://github.com/frinus-ai/frinus-mcp/issues",
-  "icon": "icon.png",
   "server": {
     "type": "node",
     "entry_point": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frinus-mcp",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Frinus - MCP Server for Cognitive Memory (φρήν + νοῦς). Long-term memory, sessions, agents and knowledge for Claude and any MCP client.",
   "type": "module",
   "main": "dist/index.js",