frinus-mcp 3.6.4 → 3.7.0

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

@@ -1,4 +1,4 @@
-import type { CpClientInterface } from "../types/index.js";
+import type { CpClientInterface, NotificationInbox } from "../types/index.js";
 export declare class CpClient implements CpClientInterface {
     private client;
     constructor(baseURL: string, apiKey: string);
@@ -13,6 +13,12 @@ export declare class CpClient implements CpClientInterface {
         description?: string;
     }): Promise<any>;
     deleteUniverse(orgId: string, universeId: string): Promise<void>;
+    getNotificationInbox(opts?: {
+        channel?: string;
+        limit?: number;
+        markDelivered?: boolean;
+    }): Promise<NotificationInbox>;
+    ackNotification(id: string): Promise<void>;
     storeCredential(integrationRef: string, data: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<any>;
     getCredential(integrationRef: string): Promise<any>;
     listCredentials(): Promise<any>;

package/dist/client/cp-client.js

@@ -4,6 +4,13 @@
 import axios from "axios";
 import { getResolvedTenantOrgId } from "./memory-client.js";
 import { getResolvedClient } from "./client-info.js";
+/**
+ * Short timeout (ms) for the platform-notification calls. These are best-effort
+ * side channels that must never slow down bootstrap/heartbeat or hold the agent
+ * hostage on a slow network, so they use a much tighter deadline than the 30s
+ * default of the rest of the Control Plane client.
+ */
+const NOTIFICATION_TIMEOUT_MS = 4000;
 export class CpClient {
     client;
     constructor(baseURL, apiKey) {
@@ -37,6 +44,25 @@ export class CpClient {
         await this.client.delete(`/api/v1/orgs/${orgId}/universes/${universeId}`);
     }
     // =========================================================================
+    // Platform Notifications (short timeout, best-effort)
+    // =========================================================================
+    async getNotificationInbox(opts = {}) {
+        const response = await this.client.get(`/api/v1/notifications/inbox`, {
+            params: {
+                channel: opts.channel ?? "mcp",
+                limit: opts.limit ?? 3,
+                mark_delivered: opts.markDelivered ?? false,
+            },
+            timeout: NOTIFICATION_TIMEOUT_MS,
+        });
+        return response.data;
+    }
+    async ackNotification(id) {
+        await this.client.post(`/api/v1/notifications/${id}/ack`, undefined, {
+            timeout: NOTIFICATION_TIMEOUT_MS,
+        });
+    }
+    // =========================================================================
     // Credential Vault
     // =========================================================================
     async storeCredential(integrationRef, data, metadata) {

package/dist/index.js

@@ -11,6 +11,7 @@
  *   tools/handlers.ts             - Tool handlers (dispatch map)
  *   types/index.ts                - Shared interfaces and types
  */
+import net from "node:net";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
@@ -26,6 +27,15 @@ import { dispatchTool } from "./tools/handlers.js";
 const MEMORY_SERVICE_URL = process.env.MEMORY_SERVICE_URL || "https://frinus-memory.rdxsec.com.br";
 const CP_URL = process.env.FRINUS_CP_URL || "https://frinus-api.rdxsec.com.br";
 const AGENT_SERVICE_URL = process.env.AGENT_SERVICE_URL || "https://frinus-agents.rdxsec.com.br";
+// Give Happy Eyeballs (RFC 8305) a realistic deadline before giving up on an
+// address family. Node's default auto-select-family attempt timeout is 250ms,
+// which on a slow network (2026-10-27 incident) made the API-key validation
+// fail with "Failed to validate API key: AggregateError" before the TCP
+// handshake could complete. 5s per attempt matches how long a cold mobile/VPN
+// link realistically needs. Guarded with typeof for older Node runtimes.
+if (typeof net.setDefaultAutoSelectFamilyAttemptTimeout === "function") {
+    net.setDefaultAutoSelectFamilyAttemptTimeout(5000);
+}
 // Main server
 async function main() {
     // Require API key (FRINUS_API_KEY preferred, FRINUS_MEMORY_API_KEY for backward compat)
@@ -40,31 +50,52 @@ async function main() {
     const cpClient = new CpClient(CP_URL, apiKey);
     const capture = new InteractionCapture(memoryClient);
     console.error(`[InteractionCapture] Session: ${capture.getSessionId()}`);
-    // Validate API key and resolve tenant identity at startup
-    try {
-        const me = await memoryClient.getAuthMe();
-        setResolvedUserEmail(me.email || me.user?.email || null);
-        setResolvedUserId(me.id || me.user?.id || me.user_id || null);
-        // Resolve tenant org ID from /auth/me response (env var takes precedence)
-        const meOrgId = me.organization_id || me.org_id || me.user?.organization_id || null;
-        if (!getResolvedTenantOrgId() && meOrgId) {
-            setResolvedTenantOrgId(meOrgId);
-        }
-        console.error(`[Auth] API key validated. User: ${getResolvedUserEmail()}, Tenant: ${getResolvedTenantOrgId() || 'none'}`);
-    }
-    catch (err) {
-        const status = err?.response?.status;
-        if (status === 401 || status === 403) {
-            console.error(`[FATAL] API key rejected (HTTP ${status}). Check FRINUS_API_KEY.`);
+    // Validate API key and resolve tenant identity at startup.
+    //
+    // Retry ONLY transient network failures (no HTTP response: DNS, connection
+    // refused/reset, timeout, AggregateError from Happy Eyeballs). A 401/403 is a
+    // real rejection and must fail fast — retrying a bad key is pointless. Backoff
+    // 1s then 3s between the 3 attempts. This, together with the auto-select-family
+    // timeout above, is the fix for the 2026-10-27 "Failed to validate API key:
+    // AggregateError" crashes on slow links.
+    const MAX_AUTH_ATTEMPTS = 3;
+    const AUTH_BACKOFFS_MS = [1000, 3000];
+    let me;
+    for (let attempt = 1;; attempt++) {
+        try {
+            me = await memoryClient.getAuthMe();
+            break;
         }
-        else {
+        catch (err) {
+            const status = err?.response?.status;
+            if (status === 401 || status === 403) {
+                console.error(`[FATAL] API key rejected (HTTP ${status}). Check FRINUS_API_KEY.`);
+                process.exit(1);
+            }
+            // No HTTP response == network/transport error -> retryable.
+            const isNetworkError = status === undefined;
+            if (isNetworkError && attempt < MAX_AUTH_ATTEMPTS) {
+                const waitMs = AUTH_BACKOFFS_MS[attempt - 1];
+                console.error(`[Auth] Network error validating API key (attempt ${attempt}/${MAX_AUTH_ATTEMPTS}): ` +
+                    `${err?.message || err}. Retrying in ${waitMs}ms...`);
+                await new Promise((resolve) => setTimeout(resolve, waitMs));
+                continue;
+            }
             console.error(`[FATAL] Failed to validate API key: ${err?.message || err}`);
+            process.exit(1);
         }
-        process.exit(1);
     }
+    setResolvedUserEmail(me.email || me.user?.email || null);
+    setResolvedUserId(me.id || me.user?.id || me.user_id || null);
+    // Resolve tenant org ID from /auth/me response (env var takes precedence)
+    const meOrgId = me.organization_id || me.org_id || me.user?.organization_id || null;
+    if (!getResolvedTenantOrgId() && meOrgId) {
+        setResolvedTenantOrgId(meOrgId);
+    }
+    console.error(`[Auth] API key validated. User: ${getResolvedUserEmail()}, Tenant: ${getResolvedTenantOrgId() || 'none'}`);
     const server = new Server({
         name: "frinus",
-        version: "3.6.4",
+        version: "3.7.0",
     }, {
         capabilities: {
             tools: {},

package/dist/notifications.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Platform notifications delivered through the MCP channel.
+ *
+ * Clients rarely come back to the web dashboard after the initial integration,
+ * so the MCP session itself becomes the way to reach them. This module fetches
+ * the Control Plane inbox and renders a compact markdown block that is appended
+ * to `agent_bootstrap` (once, forced) and `heartbeat_tick` (throttled).
+ *
+ * Design rules:
+ *  - NEVER throws. A 404, timeout or any network error yields '' plus a stderr
+ *    log. The agent's real work must never be blocked by the news channel.
+ *  - In-process state, per MCP process (= per session): which notification ids
+ *    were already shown, and when we last hit the inbox. A long-lived process
+ *    therefore shows each item at most once and polls at most once per window.
+ *  - Env toggles: FRINUS_NOTIFICATIONS=off disables everything;
+ *    FRINUS_NOTIFICATIONS_INTERVAL_MIN overrides the throttle window (default 60).
+ */
+import type { CpClientInterface } from "./types/index.js";
+/** Reset module state. Test-only; not part of the runtime surface. */
+export declare function __resetNotificationsState(): void;
+export interface FetchBlockOptions {
+    /** Bypass the throttle window (used by agent_bootstrap). */
+    force?: boolean;
+}
+/**
+ * Fetch the inbox and render the "Novidades do Frinus" block, or '' when there
+ * is nothing new to show (disabled, throttled, empty, already-shown, or any
+ * failure). Guaranteed not to throw.
+ */
+export declare function fetchNotificationsBlock(cpClient: CpClientInterface, opts?: FetchBlockOptions): Promise<string>;

package/dist/notifications.js

@@ -0,0 +1,86 @@
+/** Max characters of a notification body rendered inline. */
+const BODY_LIMIT = 600;
+/** Default throttle window for non-forced checks (minutes). */
+const DEFAULT_INTERVAL_MIN = 60;
+// ---------------------------------------------------------------------------
+// In-process session state
+// ---------------------------------------------------------------------------
+/** Notification ids already shown in this session (dedupe across bootstrap + ticks). */
+const shownIds = new Set();
+/** Epoch ms of the last inbox check (forced or throttled). 0 = never. */
+let lastCheckAt = 0;
+/** Reset module state. Test-only; not part of the runtime surface. */
+export function __resetNotificationsState() {
+    shownIds.clear();
+    lastCheckAt = 0;
+}
+function isDisabled() {
+    return (process.env.FRINUS_NOTIFICATIONS || "").trim().toLowerCase() === "off";
+}
+function throttleMs() {
+    const raw = process.env.FRINUS_NOTIFICATIONS_INTERVAL_MIN;
+    const parsed = raw !== undefined ? Number.parseInt(raw, 10) : NaN;
+    const minutes = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_INTERVAL_MIN;
+    return minutes * 60_000;
+}
+/**
+ * Fetch the inbox and render the "Novidades do Frinus" block, or '' when there
+ * is nothing new to show (disabled, throttled, empty, already-shown, or any
+ * failure). Guaranteed not to throw.
+ */
+export async function fetchNotificationsBlock(cpClient, opts = {}) {
+    if (isDisabled())
+        return "";
+    const now = Date.now();
+    if (!opts.force && now - lastCheckAt < throttleMs()) {
+        return "";
+    }
+    lastCheckAt = now;
+    let inbox;
+    try {
+        inbox = await cpClient.getNotificationInbox({
+            channel: "mcp",
+            limit: 3,
+            markDelivered: true,
+        });
+    }
+    catch (err) {
+        // 404 (CP not yet deployed), timeout, DNS, connection refused — all benign
+        // here. Swallow and keep working; log to stderr for operators.
+        console.error(`[Notifications] inbox fetch failed: ${err?.message || err}`);
+        return "";
+    }
+    const fresh = (inbox?.items || []).filter((it) => !!it && typeof it.id === "string" && !shownIds.has(it.id));
+    if (fresh.length === 0)
+        return "";
+    for (const it of fresh)
+        shownIds.add(it.id);
+    return renderBlock(fresh);
+}
+/** Render the markdown block the agent relays to the user. */
+function renderBlock(items) {
+    let out = `## 📣 Novidades do Frinus\n\n`;
+    for (const it of items) {
+        const sev = it.severity ? ` _(${it.severity})_` : "";
+        out += `### ${it.title}${sev}\n`;
+        let body = (it.body || "").trim();
+        if (body.length > BODY_LIMIT) {
+            body = body.slice(0, BODY_LIMIT).trimEnd() + "…";
+        }
+        if (body)
+            out += `${body}\n`;
+        if (it.cta_label && it.cta_url) {
+            out += `\n[${it.cta_label}](${it.cta_url})\n`;
+        }
+        else if (it.cta_url) {
+            out += `\n${it.cta_url}\n`;
+        }
+        out += `\n_id: ${it.id}_\n\n`;
+    }
+    out += `---\n`;
+    out +=
+        `Avise o usuário destas novidades de forma breve (1–3 linhas cada) no ` +
+            `início da sua próxima resposta, sem interromper a tarefa. Quando ele ` +
+            `confirmar ciência ou pedir para não ver mais, chame notification_ack(id).\n`;
+    return out;
+}

package/dist/tools/definitions.js

@@ -1855,4 +1855,43 @@ granted it and when. No secret data.`,
             required: ["ref"],
         },
     },
+    // ==========================================================================
+    // Platform Notifications (2)
+    // ==========================================================================
+    {
+        name: "notifications_list",
+        description: `List pending Frinus platform notifications for the current user.
+
+These are platform-authored announcements: new features, maintenance windows,
+tips and alerts. This is a READ-ONLY peek — it does not mark anything as
+delivered or acknowledged, so items stay in the inbox until the user sees them.
+
+Each item includes an \`id\` you can pass to notification_ack once the user has
+read it. Use this when the user asks "what's new" or to re-check news that was
+surfaced earlier in the session.`,
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "notification_ack",
+        description: `Acknowledge a Frinus platform notification by id.
+
+Call this once the user confirms they have seen the news, or asks not to see it
+again. The notification then disappears from the inbox and will not be shown
+again (in this or future sessions). The id comes from the "📣 Novidades do
+Frinus" block or from notifications_list.`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "UUID of the notification to acknowledge (required)",
+                },
+            },
+            required: ["id"],
+        },
+    },
 ];

package/dist/tools/handlers.js

@@ -7,6 +7,7 @@
 import axios from "axios";
 import { spawn } from "node:child_process";
 import { getResolvedTenantOrgId } from "../client/memory-client.js";
+import { fetchNotificationsBlock } from "../notifications.js";
 // ---------------------------------------------------------------------------
 // Credential delivery — server-side broker, never by value
 // ---------------------------------------------------------------------------
@@ -982,7 +983,7 @@ const handlers = {
     // ==========================================================================
     // Maintenance
     // ==========================================================================
-    async heartbeat_tick(args, { memoryClient }) {
+    async heartbeat_tick(args, { memoryClient, cpClient }) {
         const result = await memoryClient.heartbeatTick({
             agent_id: args.agent_id,
             context_id: args.context_id,
@@ -1012,6 +1013,13 @@ const handlers = {
                 formatted += `  ${action}: at interaction ${count}\n`;
             }
         }
+        // Piggyback the notifications check on the heartbeat. fetchNotificationsBlock
+        // self-throttles (at most once per FRINUS_NOTIFICATIONS_INTERVAL_MIN) and
+        // dedupes against what this session already showed, so this is cheap and
+        // never shows the same item twice.
+        const notif = await fetchNotificationsBlock(cpClient, { force: false });
+        if (notif)
+            formatted += `\n${notif}`;
         return { content: [{ type: "text", text: formatted }] };
     },
     async sleep_run(args, { memoryClient }) {
@@ -1246,7 +1254,12 @@ const handlers = {
                 }],
         };
     },
-    async agent_bootstrap(args, { agentClient }) {
+    async agent_bootstrap(args, { agentClient, cpClient }) {
+        // Kick off the notifications fetch concurrently with the bootstrap call so
+        // it adds no latency on the critical path. fetchNotificationsBlock never
+        // throws and self-limits to a 4s timeout, so bootstrap can neither fail nor
+        // stall because of it; the extra .catch is defence in depth.
+        const notifPromise = fetchNotificationsBlock(cpClient, { force: true }).catch(() => "");
         try {
             const result = await agentClient.bootstrapAgent(args.agent_id);
             const identity = result.identity || {};
@@ -1310,6 +1323,9 @@ const handlers = {
             if (delegateDigest && delegateDigest.count > 0 && delegateDigest.summary) {
                 formatted += `\n### Delegate Targets\n${delegateDigest.summary}\n`;
             }
+            const notif = await notifPromise;
+            if (notif)
+                formatted += `\n\n${notif}`;
             return { content: [{ type: "text", text: formatted }] };
         }
         catch (error) {
@@ -2316,6 +2332,81 @@ const handlers = {
             throw error;
         }
     },
+    // ==========================================================================
+    // Platform Notifications
+    // ==========================================================================
+    async notifications_list(_args, { cpClient }) {
+        try {
+            // mark_delivered=false: this is a read-only peek that must NOT consume a
+            // delivery against max_deliveries. Use a higher limit than the automatic
+            // channels so the user can see everything still pending.
+            const inbox = await cpClient.getNotificationInbox({
+                channel: "mcp",
+                limit: 10,
+                markDelivered: false,
+            });
+            const items = inbox?.items || [];
+            if (items.length === 0) {
+                return { content: [{ type: "text", text: "No pending Frinus notifications." }] };
+            }
+            let text = `${items.length} pending Frinus notification${items.length === 1 ? "" : "s"}:\n\n`;
+            items.forEach((it) => {
+                const sev = it.severity ? `[${it.severity}] ` : "";
+                text += `- ${sev}${it.title} (id: ${it.id})\n`;
+                let body = (it.body || "").trim();
+                if (body.length > 300)
+                    body = body.slice(0, 300).trimEnd() + "…";
+                if (body)
+                    text += `  ${body.replace(/\n+/g, " ")}\n`;
+                if (it.cta_url)
+                    text += `  → ${it.cta_label ? `${it.cta_label}: ` : ""}${it.cta_url}\n`;
+            });
+            text += `\nCall notification_ack(id) once the user has seen one so it stops appearing.`;
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            if (error?.response?.status === 404) {
+                // CP without the notifications endpoint yet — treat as empty, not error.
+                return { content: [{ type: "text", text: "No pending Frinus notifications." }] };
+            }
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+    },
+    async notification_ack(args, { cpClient }) {
+        const id = args.id || "";
+        if (!id) {
+            return {
+                content: [{ type: "text", text: "notification_ack requires an 'id'." }],
+                isError: true,
+            };
+        }
+        try {
+            await cpClient.ackNotification(id);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Notification ${id} acknowledged. It will no longer appear in the inbox.`,
+                    }],
+            };
+        }
+        catch (error) {
+            if (error?.response?.status === 404) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Notification ${id} not found (already acknowledged, expired, or not for you).`,
+                        }],
+                };
+            }
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+    },
 };
 // ---------------------------------------------------------------------------
 // Dispatcher: looks up the handler and executes it with error handling

package/dist/types/index.d.ts

@@ -58,6 +58,24 @@ export interface AgentClientInterface {
         timeout_seconds?: number;
     }): Promise<any>;
 }
+/** A single platform notification served by the Control Plane inbox. */
+export interface NotificationItem {
+    id: string;
+    slug: string;
+    title: string;
+    body: string;
+    kind: string;
+    severity: string;
+    cta_label?: string | null;
+    cta_url?: string | null;
+    starts_at?: string | null;
+    expires_at?: string | null;
+}
+/** Response shape of GET /api/v1/notifications/inbox. */
+export interface NotificationInbox {
+    items: NotificationItem[];
+    count: number;
+}
 /** Public surface of the CpClient used by handlers. */
 export interface CpClientInterface {
     createUniverse(orgId: string, data: {
@@ -71,6 +89,12 @@ export interface CpClientInterface {
         description?: string;
     }): Promise<any>;
     deleteUniverse(orgId: string, universeId: string): Promise<void>;
+    getNotificationInbox(opts?: {
+        channel?: string;
+        limit?: number;
+        markDelivered?: boolean;
+    }): Promise<NotificationInbox>;
+    ackNotification(id: string): Promise<void>;
     storeCredential(integrationRef: string, data: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<any>;
     getCredential(integrationRef: string): Promise<any>;
     listCredentials(): Promise<any>;

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "frinus",
   "display_name": "Frinus — Memória Cognitiva",
-  "version": "3.6.4",
+  "version": "3.7.0",
   "description": "Memória cognitiva de longo prazo para o Claude (φρήν + νοῦς). 83 ferramentas de memória, sessões, agentes e conhecimento.",
   "long_description": "O Frinus dá ao Claude memória de longo prazo, identidade e inteligência persistente entre conversas. Conecta o Claude Desktop à plataforma Frinus (Memory Engine, Control Plane e Agent Service) via MCP. Basta colar sua chave de API pessoal — nada para instalar ou compilar.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frinus-mcp",
-  "version": "3.6.4",
+  "version": "3.7.0",
   "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",