frinus-mcp 3.1.0

package/dist/client/memory-client.js

@@ -0,0 +1,460 @@
+/**
+ * HTTP client for the Frinus Memory Service.
+ */
+import axios from "axios";
+/**
+ * Mutable tenant / user state resolved at startup.
+ * Shared with the rest of the server via the exported getters/setters below.
+ *
+ * NOTE: These are module-level singletons, not instance properties, because
+ * they are consumed by multiple client classes (MemoryClient, AgentClient,
+ * CpClient) and tool handlers via Axios request interceptors that capture
+ * the getter at construction time.  Moving them to a single class instance
+ * would require threading that instance through every consumer, which is
+ * disproportionate for an MCP server that runs as a single-process stdio
+ * bridge.  Use `resetState()` in tests or when reinitializing the server.
+ */
+let resolvedTenantOrgId = process.env.FRINUS_TENANT_ORG_ID || null;
+let resolvedUserEmail = null;
+let resolvedUserId = null;
+export function getResolvedTenantOrgId() { return resolvedTenantOrgId; }
+export function setResolvedTenantOrgId(v) { resolvedTenantOrgId = v; }
+export function getResolvedUserEmail() { return resolvedUserEmail; }
+export function setResolvedUserEmail(v) { resolvedUserEmail = v; }
+export function getResolvedUserId() { return resolvedUserId; }
+export function setResolvedUserId(v) { resolvedUserId = v; }
+/** Reset all mutable module state. Useful for tests or server reinitialization. */
+export function resetState() {
+    resolvedTenantOrgId = process.env.FRINUS_TENANT_ORG_ID || null;
+    resolvedUserEmail = null;
+    resolvedUserId = null;
+}
+// Memory service client
+export class MemoryClient {
+    client;
+    constructor(baseURL, apiKey) {
+        this.client = axios.create({
+            baseURL,
+            timeout: 30000,
+        });
+        // Intercept every request to inject X-API-Key and X-Tenant-ID
+        this.client.interceptors.request.use((config) => {
+            config.headers = config.headers || {};
+            config.headers['X-API-Key'] = apiKey;
+            if (resolvedTenantOrgId) {
+                config.headers['X-Tenant-ID'] = resolvedTenantOrgId;
+            }
+            return config;
+        });
+    }
+    /** Return the current tenant org ID (if resolved). */
+    getTenantOrgId() {
+        return resolvedTenantOrgId;
+    }
+    async getAuthMe() {
+        const response = await this.client.get("/auth/me");
+        return response.data;
+    }
+    // =========================================================================
+    // Session Management
+    // =========================================================================
+    async startSession(data) {
+        const response = await this.client.post("/session/start", data);
+        return response.data;
+    }
+    async endSession(sessionId) {
+        const response = await this.client.post(`/session/${sessionId}/end`);
+        return response.data;
+    }
+    async getSessionContext(data) {
+        const response = await this.client.post("/session/context", data);
+        return response.data;
+    }
+    async getSessionSummary(sessionId) {
+        const response = await this.client.get(`/session/summary/${encodeURIComponent(sessionId)}`);
+        return response.data;
+    }
+    async clearSession(sessionId) {
+        const response = await this.client.delete(`/session/clear/${encodeURIComponent(sessionId)}`);
+        return response.data;
+    }
+    // =========================================================================
+    // Core Memory CRUD
+    // =========================================================================
+    async storeMemory(data) {
+        const payload = {
+            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,
+        };
+        if (data.user_id)
+            payload.user_id = data.user_id;
+        if (data.created_by_user_id)
+            payload.created_by_user_id = data.created_by_user_id;
+        if (data.context_id)
+            payload.context_id = data.context_id;
+        if (data.credential_ref)
+            payload.credential_ref = data.credential_ref;
+        const response = await this.client.post("/memories", payload);
+        return response.data;
+    }
+    async searchMemories(data) {
+        const response = await this.client.post("/memories/search", {
+            query_text: data.query_text,
+            agent_id: data.agent_id,
+            memory_types: data.memory_types,
+            limit: data.limit || 10,
+        });
+        return response.data;
+    }
+    async getMemory(memoryId) {
+        const response = await this.client.get(`/memories/${memoryId}`);
+        return response.data;
+    }
+    async getAgentMemories(agentId, memoryType, limit = 50) {
+        const params = new URLSearchParams({ limit: limit.toString() });
+        if (memoryType)
+            params.append("memory_type", memoryType);
+        const response = await this.client.get(`/memories/agent/${agentId}?${params}`);
+        return response.data;
+    }
+    async deleteMemory(memoryId) {
+        const response = await this.client.delete(`/memories/${memoryId}`);
+        // API returns 204 No Content on successful delete
+        if (response.status === 204) {
+            return { deleted: true };
+        }
+        return response.data;
+    }
+    async buildContext(data) {
+        const response = await this.client.post("/memories/context", {
+            agent_id: data.agent_id,
+            task_description: data.task_description,
+            max_tokens: data.max_tokens || 2000,
+        });
+        return response.data;
+    }
+    // =========================================================================
+    // Dynamic Relevance
+    // =========================================================================
+    async reinforceMemory(memoryId, boost) {
+        const response = await this.client.post(`/memories/${memoryId}/reinforce`, { boost });
+        return response.data;
+    }
+    async weakenMemory(memoryId, penalty) {
+        const response = await this.client.post(`/memories/${memoryId}/weaken`, { penalty });
+        return response.data;
+    }
+    // =========================================================================
+    // Working Memory
+    // =========================================================================
+    async getWorkingMemory(contextId) {
+        const response = await this.client.get(`/working-memory/${contextId}`);
+        return response.data;
+    }
+    async addWorkingMemory(data) {
+        const response = await this.client.post("/working-memory", data);
+        return response.data;
+    }
+    async clearWorkingMemory(contextId) {
+        const response = await this.client.delete(`/working-memory/${contextId}`);
+        return response.data;
+    }
+    // =========================================================================
+    // Stream
+    // =========================================================================
+    async captureStream(data) {
+        const response = await this.client.post("/stream/capture", data);
+        return response.data;
+    }
+    async getSessionItems(sessionId, limit) {
+        const params = limit ? `?limit=${limit}` : "";
+        const response = await this.client.get(`/stream/session/${encodeURIComponent(sessionId)}${params}`);
+        return response.data;
+    }
+    async getRecentStreamItems(agentId, limit, includeForgotten) {
+        const params = new URLSearchParams();
+        if (agentId)
+            params.append("agent_id", agentId);
+        if (limit)
+            params.append("limit", limit.toString());
+        if (includeForgotten)
+            params.append("include_forgotten", "true");
+        const query = params.toString() ? `?${params}` : "";
+        const response = await this.client.get(`/stream/recent${query}`);
+        return response.data;
+    }
+    async processStream(batchSize) {
+        const params = batchSize ? `?batch_size=${batchSize}` : "";
+        const response = await this.client.post(`/stream/process${params}`);
+        return response.data;
+    }
+    // =========================================================================
+    // Selective Attention
+    // =========================================================================
+    async searchWithAttention(data) {
+        const response = await this.client.post("/memories/search-with-attention", data);
+        return response.data;
+    }
+    // =========================================================================
+    // User
+    // =========================================================================
+    async getUserContext(taskDescription, userEmail) {
+        const response = await this.client.post("/memories/context", {
+            task_description: taskDescription,
+            user_email: userEmail,
+        });
+        return response.data;
+    }
+    // =========================================================================
+    // Maintenance
+    // =========================================================================
+    async heartbeatTick(data) {
+        const response = await this.client.post("/heartbeat/tick", data);
+        return response.data;
+    }
+    async reorientAgent(agentId, focus) {
+        const payload = {};
+        if (focus)
+            payload.focus = focus;
+        const response = await this.client.post(`/agents/${agentId}/reorient`, payload);
+        return response.data;
+    }
+    async runSleepCycle(phases) {
+        const response = await this.client.post("/sleep/run", {
+            phases: phases || ["evaluation", "forgetting", "consolidation", "relevance"],
+        });
+        return response.data;
+    }
+    // =========================================================================
+    // Consolidation (Active Forgetting)
+    // =========================================================================
+    async detectConflicts(similarityThreshold, limit) {
+        const response = await this.client.post("/consolidation/detect-conflicts", {
+            similarity_threshold: similarityThreshold || 0.9,
+            limit: limit || 50,
+        });
+        return response.data;
+    }
+    async resolveConflict(data) {
+        const response = await this.client.post("/consolidation/resolve-conflict", {
+            keep_id: data.keep_id,
+            supersede_id: data.supersede_id,
+            resolution_note: data.resolution_note,
+        });
+        return response.data;
+    }
+    async detectRedundant(similarityThreshold, limit) {
+        const response = await this.client.post("/consolidation/detect-redundant", {
+            similarity_threshold: similarityThreshold || 0.95,
+            limit: limit || 50,
+        });
+        return response.data;
+    }
+    // =========================================================================
+    // Hierarchical Memory
+    // =========================================================================
+    async hierarchyConsolidate(data) {
+        const response = await this.client.post("/hierarchy/consolidate", {
+            memory_ids: data.memory_ids,
+            summary_content: data.summary_content,
+            agent_id: data.agent_id,
+        });
+        return response.data;
+    }
+    async getHierarchyTree(memoryId) {
+        const response = await this.client.get(`/hierarchy/${memoryId}/tree`);
+        return response.data;
+    }
+    // =========================================================================
+    // Knowledge Graph - Concepts
+    // =========================================================================
+    async createConcept(data) {
+        const response = await this.client.post("/graph/concepts", data);
+        return response.data;
+    }
+    async listUniverseConcepts(universeId) {
+        const response = await this.client.get(`/graph/universes/${universeId}/concepts`);
+        return response.data;
+    }
+    async updateConcept(conceptId, data) {
+        const response = await this.client.put(`/graph/concepts/${conceptId}`, data);
+        return response.data;
+    }
+    async deleteConcept(conceptId) {
+        const response = await this.client.delete(`/graph/concepts/${conceptId}`);
+        if (response.status === 204) {
+            return { deleted: true };
+        }
+        return response.data;
+    }
+    // =========================================================================
+    // Knowledge Graph - Themes
+    // =========================================================================
+    async createTheme(data) {
+        const response = await this.client.post("/graph/themes", data);
+        return response.data;
+    }
+    async listConceptThemes(conceptId) {
+        const response = await this.client.get(`/graph/concepts/${conceptId}/themes`);
+        return response.data;
+    }
+    async updateTheme(themeId, data) {
+        const response = await this.client.put(`/graph/themes/${themeId}`, data);
+        return response.data;
+    }
+    async deleteTheme(themeId) {
+        const response = await this.client.delete(`/graph/themes/${themeId}`);
+        if (response.status === 204) {
+            return { deleted: true };
+        }
+        return response.data;
+    }
+    // =========================================================================
+    // Knowledge Graph - Topics
+    // =========================================================================
+    async createTopic(data) {
+        const response = await this.client.post("/graph/topics", data);
+        return response.data;
+    }
+    async listThemeTopics(themeId) {
+        const response = await this.client.get(`/graph/themes/${themeId}/topics`);
+        return response.data;
+    }
+    async updateTopic(topicId, data) {
+        const response = await this.client.put(`/graph/topics/${topicId}`, data);
+        return response.data;
+    }
+    async updateTopicStatus(topicId, status) {
+        const response = await this.client.patch(`/graph/topics/${topicId}/status`, { status });
+        return response.data;
+    }
+    async deleteTopic(topicId) {
+        const response = await this.client.delete(`/graph/topics/${topicId}`);
+        if (response.status === 204) {
+            return { deleted: true };
+        }
+        return response.data;
+    }
+    // =========================================================================
+    // Knowledge Graph - Points
+    // =========================================================================
+    async createPoint(data) {
+        const response = await this.client.post("/graph/points", data);
+        return response.data;
+    }
+    async listTopicPoints(topicId) {
+        const response = await this.client.get(`/graph/topics/${topicId}/points`);
+        return response.data;
+    }
+    async updatePoint(pointId, data) {
+        const response = await this.client.put(`/graph/points/${pointId}`, data);
+        return response.data;
+    }
+    async updatePointStatus(pointId, status) {
+        const response = await this.client.patch(`/graph/points/${pointId}/status`, { status });
+        return response.data;
+    }
+    async deletePoint(pointId) {
+        const response = await this.client.delete(`/graph/points/${pointId}`);
+        if (response.status === 204) {
+            return { deleted: true };
+        }
+        return response.data;
+    }
+    // =========================================================================
+    // Knowledge Graph - Hierarchy
+    // =========================================================================
+    async getUniverseHierarchy(universeId) {
+        const response = await this.client.get(`/graph/universes/${universeId}/hierarchy`);
+        return response.data;
+    }
+    // =========================================================================
+    // Training
+    // =========================================================================
+    async trainingTeach(data) {
+        const response = await this.client.post("/training/teach", {
+            content: data.content,
+            type: data.type || "semantic",
+            importance: data.importance || 0.7,
+            universe_id: data.universe_id,
+        });
+        return response.data;
+    }
+    async trainingQa(data) {
+        const response = await this.client.post("/training/qa", {
+            pairs: data.pairs,
+            universe_id: data.universe_id,
+        });
+        return response.data;
+    }
+    async trainingStats() {
+        const response = await this.client.get("/training/stats");
+        return response.data;
+    }
+    async trainingGaps() {
+        const response = await this.client.get("/training/gaps");
+        return response.data;
+    }
+    async trainingRecent(data) {
+        const params = data?.limit ? `?limit=${data.limit}` : "";
+        const response = await this.client.get(`/training/recent${params}`);
+        return response.data;
+    }
+    // -------------------------------------------------------------------------
+    // Task Management
+    // -------------------------------------------------------------------------
+    async createTask(data) {
+        const response = await this.client.post("/tasks", data);
+        return response.data;
+    }
+    async getTask(taskId) {
+        const response = await this.client.get(`/tasks/${taskId}`);
+        return response.data;
+    }
+    async listTasks(data) {
+        const params = new URLSearchParams();
+        if (data?.status)
+            params.append("status", data.status);
+        if (data?.assigned_agent_id)
+            params.append("assigned_agent_id", data.assigned_agent_id);
+        if (data?.parent_task_id)
+            params.append("parent_task_id", data.parent_task_id);
+        if (data?.limit)
+            params.append("limit", data.limit.toString());
+        const qs = params.toString();
+        const response = await this.client.get(`/tasks${qs ? `?${qs}` : ""}`);
+        return response.data;
+    }
+    async updateTask(taskId, data) {
+        const response = await this.client.patch(`/tasks/${taskId}`, data);
+        return response.data;
+    }
+    // =========================================================================
+    // Skills
+    // =========================================================================
+    async listSkills(category) {
+        const params = {};
+        if (category)
+            params.category = category;
+        const response = await this.client.get('/skills', { params });
+        return response.data;
+    }
+    async getAgentSkills(agentId) {
+        const response = await this.client.get(`/skills/agent/${agentId}`);
+        return response.data;
+    }
+    async assignSkill(agentId, skillId, permission) {
+        const response = await this.client.post(`/skills/agent/${agentId}/${skillId}`, {
+            permission: permission || 'execute',
+        });
+        return response.data;
+    }
+    async removeSkill(agentId, skillId) {
+        const response = await this.client.delete(`/skills/agent/${agentId}/${skillId}`);
+        return response.data;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Agents Memory Service
+ *
+ * This server exposes the memory service as MCP tools for Claude agents.
+ *
+ * Module structure:
+ *   client/memory-client.ts       - HTTP client (MemoryClient + Axios interceptors)
+ *   capture/interaction-capture.ts - Automatic tool-call stream tracking
+ *   tools/definitions.ts          - Tool schemas (inputSchema for all tools)
+ *   tools/handlers.ts             - Tool handlers (dispatch map)
+ *   types/index.ts                - Shared interfaces and types
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Agents Memory Service
+ *
+ * This server exposes the memory service as MCP tools for Claude agents.
+ *
+ * Module structure:
+ *   client/memory-client.ts       - HTTP client (MemoryClient + Axios interceptors)
+ *   capture/interaction-capture.ts - Automatic tool-call stream tracking
+ *   tools/definitions.ts          - Tool schemas (inputSchema for all tools)
+ *   tools/handlers.ts             - Tool handlers (dispatch map)
+ *   types/index.ts                - Shared interfaces and types
+ */
+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 { MemoryClient, getResolvedUserEmail, getResolvedUserId, setResolvedTenantOrgId, setResolvedUserEmail, setResolvedUserId, getResolvedTenantOrgId, } from "./client/memory-client.js";
+import { AgentClient } from "./client/agent-client.js";
+import { CpClient } from "./client/cp-client.js";
+import { InteractionCapture } from "./capture/interaction-capture.js";
+import { TOOLS } from "./tools/definitions.js";
+import { dispatchTool } from "./tools/handlers.js";
+// Defaults point at the Frinus SaaS so `npx -y frinus-mcp` works with only an
+// API key. Local development overrides these via env (MEMORY_SERVICE_URL, etc.).
+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";
+// Main server
+async function main() {
+    // Require API key (FRINUS_API_KEY preferred, FRINUS_MEMORY_API_KEY for backward compat)
+    const apiKey = process.env.FRINUS_API_KEY || process.env.FRINUS_MEMORY_API_KEY;
+    if (!apiKey) {
+        console.error("[FATAL] FRINUS_API_KEY environment variable is required but not set.");
+        console.error("Generate an API key in the Frinus dashboard or via the Control Plane API.");
+        process.exit(1);
+    }
+    const memoryClient = new MemoryClient(MEMORY_SERVICE_URL, apiKey);
+    const agentClient = new AgentClient(AGENT_SERVICE_URL, apiKey);
+    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.`);
+        }
+        else {
+            console.error(`[FATAL] Failed to validate API key: ${err?.message || err}`);
+        }
+        process.exit(1);
+    }
+    const server = new Server({
+        name: "frinus",
+        version: "3.1.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // List tools handler (all tools always visible; backend enforces auth)
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    // Call tool handler (with automatic interaction capture)
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        // Execute the tool via the dispatch map
+        const toolResult = await dispatchTool(name, args, {
+            memoryClient,
+            agentClient,
+            cpClient,
+            capture,
+            resolvedUserEmail: getResolvedUserEmail(),
+            resolvedUserId: getResolvedUserId(),
+            cpUrl: CP_URL,
+        });
+        // Fire-and-forget: capture the tool call interaction to the memory stream
+        try {
+            capture.captureToolCall(name, args, toolResult);
+        }
+        catch (err) {
+            console.error('[MCP] Capture failed:', err.message);
+        }
+        return toolResult;
+    });
+    // Start server
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Memory Server running on stdio");
+}
+main().catch(console.error);

package/dist/tools/definitions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tool schema definitions for the Frinus MCP Server.
+ *
+ * Each entry defines a tool name, description, and inputSchema
+ * following the MCP Tool specification.
+ */
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const TOOLS: Tool[];