@echomem/mcp 1.3.0 → 1.3.1

package/dist/index.js

@@ -4,11 +4,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import { ZodError } from "zod";
-import { canonicalToolNames, keywordsSchema, listToolSpecs, othersSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, timeRangeSchema, } from "./v1-contract.js";
+import { canonicalToolNames, deleteMemorySchema, keywordsSchema, listToolSpecs, othersSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, timeRangeSchema, } from "./v1-contract.js";
 import { KeyStore } from "./keystore.js";
 import { EventLogger, hashText } from "./events.js";
 import { buildReportText } from "./report.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { fetchEncryptionConfig, decryptMemoryFields } from "./encryption.js";
 import { runCli } from "./setup.js";
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
@@ -88,6 +88,10 @@ function classifyError(error) {
         return "invalid_args";
     return "api_error";
 }
+const URL_RE = /\bhttps?:\/\/[^\s<>"')\]]+/i;
+const SECRET_LIKE_RE = /(sk-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]+|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{20,}|-----BEGIN [A-Z ]+PRIVATE KEY-----|\b(api[_-]?key|token|secret|password)\s*[:=])/i;
+const CODE_LIKE_RE = /(```|^\s*(import|export|const|let|var|function|class|interface|type)\s|\b(def|async|await)\s+\w+)/m;
+const DELETE_CONFIRMATION_TTL_MS = 15 * 60 * 1000;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -99,6 +103,141 @@ function readNumber(record, key) {
     const value = record[key];
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
+function compactOneLine(value, maxLength) {
+    if (!value)
+        return undefined;
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (!compact)
+        return undefined;
+    return compact.length > maxLength ? `${compact.slice(0, maxLength - 3)}...` : compact;
+}
+function memoryDeleteFingerprint(memory) {
+    return [
+        readString(memory, "id"),
+        readString(memory, "updated_at"),
+        readString(memory, "created_at"),
+        readString(memory, "time"),
+        readString(memory, "keys") ?? readString(memory, "key"),
+    ].filter(Boolean).join("|");
+}
+function formatDeletePreview(memory) {
+    const lines = [
+        `Memory ID: ${readString(memory, "id") ?? "(unknown)"}`,
+        readString(memory, "keys") || readString(memory, "key")
+            ? `Keys: ${readString(memory, "keys") ?? readString(memory, "key")}`
+            : "",
+        readString(memory, "time") ? `Time: ${readString(memory, "time")}` : "",
+        readString(memory, "location") ? `Location: ${readString(memory, "location")}` : "",
+        readString(memory, "category") ? `Category: ${readString(memory, "category")}` : "",
+        readString(memory, "object") ? `Object: ${readString(memory, "object")}` : "",
+        readString(memory, "emotion") ? `Emotion: ${readString(memory, "emotion")}` : "",
+        compactOneLine(readString(memory, "description"), 320)
+            ? `Description: ${compactOneLine(readString(memory, "description"), 320)}`
+            : "",
+        compactOneLine(readString(memory, "details"), 240)
+            ? `Details: ${compactOneLine(readString(memory, "details"), 240)}`
+            : "",
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+function redactAnalyticsText(text) {
+    return text
+        .replace(URL_RE, "[url]")
+        .replace(SECRET_LIKE_RE, "[secret-like-text]")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function safeTextAnalytics(prefix, text, previewChars = 300) {
+    if (typeof text !== "string" || text.length === 0) {
+        return {
+            [`${prefix}_available`]: false,
+            [`${prefix}_length`]: 0,
+        };
+    }
+    return {
+        [`${prefix}_available`]: true,
+        [`${prefix}_preview`]: redactAnalyticsText(text).slice(0, previewChars),
+        [`${prefix}_length`]: text.length,
+        [`${prefix}_hash`]: `sha256:${createHash("sha256").update(text).digest("hex")}`,
+        [`${prefix}_contains_url`]: URL_RE.test(text),
+        [`${prefix}_contains_code`]: CODE_LIKE_RE.test(text),
+        [`${prefix}_contains_secret_like_text`]: SECRET_LIKE_RE.test(text),
+    };
+}
+function hashAnalyticsText(text) {
+    return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+function isUserRole(role) {
+    return typeof role === "string" && ["user", "human"].includes(role.toLowerCase());
+}
+function conversationAnalyticsFromMessages(value) {
+    if (!Array.isArray(value))
+        return {};
+    const records = value.filter(isRecord);
+    const userMessages = records
+        .filter((item) => isUserRole(item.role) && readString(item, "content"))
+        .map((item) => readString(item, "content") ?? "");
+    const assistantMessages = records
+        .filter((item) => typeof item.role === "string" && ["assistant", "ai"].includes(item.role.toLowerCase()))
+        .map((item) => readString(item, "content") ?? "");
+    const conversationText = records
+        .map((item) => `${readString(item, "role") ?? "unknown"}: ${typeof item.content === "string" ? item.content : ""}`)
+        .join("\n\n");
+    return {
+        conversation_length: conversationText.length,
+        conversation_hash: conversationText ? hashAnalyticsText(conversationText) : undefined,
+        conversation_message_count: value.length,
+        user_message_count: userMessages.length,
+        assistant_message_count: assistantMessages.length,
+        ...safeTextAnalytics("first_user_message", userMessages[0]),
+        ...safeTextAnalytics("last_user_message", userMessages.at(-1)),
+    };
+}
+function lastUserMessageFromMessages(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    for (let i = value.length - 1; i >= 0; i--) {
+        const item = value[i];
+        if (!isRecord(item) || !isUserRole(item.role))
+            continue;
+        const content = readString(item, "content");
+        if (content)
+            return content;
+    }
+    return undefined;
+}
+function lastUserMessageFromConversationText(value) {
+    if (typeof value !== "string" || !value)
+        return undefined;
+    const markdownUserTurns = [...value.matchAll(/(?:^|\n)##\s+(?:User|Human)[^\n]*\n([\s\S]*?)(?=\n---\n|\n##\s+(?:User|Human|Assistant|AI|System)\b|$)/gi)];
+    const lastMarkdownTurn = markdownUserTurns.at(-1)?.[1]?.trim();
+    if (lastMarkdownTurn)
+        return lastMarkdownTurn;
+    const roleLines = value.split(/\n/);
+    let currentRole = null;
+    let current = [];
+    let lastUser = "";
+    const flush = () => {
+        if (currentRole && isUserRole(currentRole)) {
+            const content = current.join("\n").trim();
+            if (content)
+                lastUser = content;
+        }
+    };
+    for (const line of roleLines) {
+        const match = line.match(/^\s*(user|human|assistant|ai|system)\s*:\s*(.*)$/i);
+        if (match) {
+            flush();
+            currentRole = match[1];
+            current = [match[2] ?? ""];
+        }
+        else if (currentRole) {
+            current.push(line);
+        }
+    }
+    flush();
+    return lastUser || undefined;
+}
 function normalizeRetrievalCandidate(value, fallbackRank) {
     if (!isRecord(value))
         return null;
@@ -128,6 +267,98 @@ function withinTimeFrame(memory, candidate, timeFrameDays) {
         return true;
     return ms >= Date.now() - timeFrameDays * 24 * 60 * 60 * 1000;
 }
+function numberArg(args, key) {
+    return typeof args[key] === "number" && Number.isFinite(args[key]) ? args[key] : undefined;
+}
+function triggerAnalyticsForTool(canonicalName, args) {
+    const a = isRecord(args) ? args : {};
+    const explicitTrigger = readString(a, "triggerMessage");
+    let triggerText = explicitTrigger;
+    let triggerSource = explicitTrigger ? "tool_argument" : "not_provided_by_mcp_client";
+    if (!triggerText && canonicalName === canonicalToolNames.save) {
+        triggerText =
+            lastUserMessageFromMessages(a.messages) ??
+                lastUserMessageFromConversationText(a.conversation);
+        triggerSource = triggerText ? "conversation_payload_inferred" : triggerSource;
+    }
+    if (!triggerText) {
+        return {
+            trigger_message_available: false,
+            trigger_message_source: triggerSource,
+        };
+    }
+    return {
+        trigger_message_source: triggerSource,
+        trigger_message_role: readString(a, "triggerMessageRole") ?? "user",
+        ...safeTextAnalytics("trigger_message", triggerText),
+    };
+}
+function inputAnalyticsForTool(canonicalName, args) {
+    const a = isRecord(args) ? args : {};
+    switch (canonicalName) {
+        case canonicalToolNames.search: {
+            const query = readString(a, "query");
+            const queryAnalytics = safeTextAnalytics("query", query);
+            return {
+                ...queryAnalytics,
+                query_preview_safe: queryAnalytics.query_preview,
+                query_length: query?.length ?? 0,
+                limit: numberArg(a, "limit") ?? numberArg(a, "k"),
+                threshold: numberArg(a, "threshold"),
+                time_frame_days: numberArg(a, "timeFrameDays"),
+                include_answer: typeof a.includeAnswer === "boolean" ? a.includeAnswer : undefined,
+            };
+        }
+        case canonicalToolNames.save: {
+            const messages = Array.isArray(a.messages) ? a.messages : undefined;
+            const conversation = typeof a.conversation === "string" ? a.conversation : undefined;
+            return {
+                input_mode: messages?.length ? "messages" : "conversation",
+                message_count: messages?.length,
+                content_length: messages?.reduce((sum, item) => {
+                    if (!isRecord(item))
+                        return sum;
+                    return sum + String(item.content ?? "").length;
+                }, 0) ?? conversation?.length ?? 0,
+                ...(messages?.length
+                    ? conversationAnalyticsFromMessages(messages)
+                    : {
+                        conversation_length: conversation?.length ?? 0,
+                        conversation_hash: conversation ? hashAnalyticsText(conversation) : undefined,
+                    }),
+                has_title: !!readString(a, "title"),
+                has_url: !!readString(a, "url"),
+                has_source: !!readString(a, "source"),
+                tag_count: Array.isArray(a.tags) ? a.tags.length : undefined,
+            };
+        }
+        case canonicalToolNames.timeRange:
+            return {
+                limit: numberArg(a, "limit"),
+                has_start_date: !!readString(a, "startDate"),
+                has_end_date: !!readString(a, "endDate"),
+            };
+        case canonicalToolNames.keywords:
+            return {
+                keyword_count: Array.isArray(a.keywords) ? a.keywords.length : 0,
+                limit: numberArg(a, "limit"),
+            };
+        case canonicalToolNames.others: {
+            const query = readString(a, "query");
+            const queryAnalytics = safeTextAnalytics("query", query);
+            return {
+                ...queryAnalytics,
+                query_preview_safe: queryAnalytics.query_preview,
+                query_length: query?.length ?? 0,
+            };
+        }
+        default:
+            return {};
+    }
+}
+function toolEventName(canonicalName, status) {
+    return `[MCP] ${canonicalName} ${status}`;
+}
 class EchoMemApiClient {
     store;
     axios;
@@ -135,6 +366,7 @@ class EchoMemApiClient {
     /** One id per bridge process — groups all saves from this coding session under a single EchoMem context. */
     sessionId = randomUUID();
     encConfigPromise = null;
+    deleteConfirmations = new Map();
     constructor(store) {
         this.store = store;
         this.axios = axios.create({
@@ -160,6 +392,16 @@ class EchoMemApiClient {
     getSessionId() {
         return this.sessionId;
     }
+    async trackMcpAnalyticsEvent(eventType, eventProperties) {
+        if (!this.hasToken())
+            return;
+        try {
+            await this.axios.post("/api/extension/mcp/events", { eventType, eventProperties }, { timeout: 1500 });
+        }
+        catch {
+            // Remote analytics is best-effort and must never change MCP behavior.
+        }
+    }
     /**
      * Compact topic map of the user's memory for the search-tool description — a cheap "what's in here"
      * index built from memory keys so the agent knows the boundary up front and recalls proactively.
@@ -211,10 +453,17 @@ class EchoMemApiClient {
             throw new LockedError(this.store.isKeyExpired());
         return { enabled: false };
     }
+    pruneDeleteConfirmations(now = Date.now()) {
+        for (const [memoryId, confirmation] of this.deleteConfirmations) {
+            if (confirmation.expiresAtMs <= now) {
+                this.deleteConfirmations.delete(memoryId);
+            }
+        }
+    }
     async whoami() {
         if (!this.whoamiCache) {
             this.whoamiCache = this.axios
-                .get("/api/openclaw/v1/whoami")
+                .get("/api/openclaw/v1/whoami", { timeout: 6000 })
                 .then((response) => response.data)
                 .catch((error) => {
                 this.whoamiCache = null; // don't pin a token-less failure; retry once a token exists
@@ -408,9 +657,57 @@ class EchoMemApiClient {
             title: parsed.title,
             // Stable per-session id so multiple saves in this coding session group under one context.
             conversationKey: this.sessionId,
+            triggerMessage: parsed.triggerMessage ||
+                lastUserMessageFromMessages(parsed.messages) ||
+                lastUserMessageFromConversationText(parsed.conversation),
+            triggerMessageRole: parsed.triggerMessageRole || "user",
         }, config);
         return response.data;
     }
+    async deleteMemory(args) {
+        const parsed = deleteMemorySchema.parse(args);
+        const enc = await this.encState();
+        const memory = await this.fetchMemoryById(parsed.memoryId, enc);
+        if (!memory) {
+            return { success: false, notFound: true, memoryId: parsed.memoryId };
+        }
+        this.pruneDeleteConfirmations();
+        const fingerprint = memoryDeleteFingerprint(memory);
+        if (!parsed.confirmed) {
+            const token = randomUUID();
+            const expiresAtMs = Date.now() + DELETE_CONFIRMATION_TTL_MS;
+            this.deleteConfirmations.set(parsed.memoryId, { token, expiresAtMs, fingerprint });
+            return {
+                success: true,
+                confirmationRequired: true,
+                memory,
+                confirmationToken: token,
+                expiresAt: new Date(expiresAtMs).toISOString(),
+            };
+        }
+        const confirmation = this.deleteConfirmations.get(parsed.memoryId);
+        if (!parsed.confirmationToken || !confirmation || confirmation.token !== parsed.confirmationToken) {
+            throw new McpError(ErrorCode.InvalidParams, "Deletion requires the exact confirmationToken returned by a prior delete_memory preview call.");
+        }
+        if (confirmation.expiresAtMs <= Date.now()) {
+            this.deleteConfirmations.delete(parsed.memoryId);
+            throw new McpError(ErrorCode.InvalidParams, "Deletion confirmation expired. Call delete_memory again with confirmed=false to generate a fresh preview.");
+        }
+        if (confirmation.fingerprint !== fingerprint) {
+            this.deleteConfirmations.delete(parsed.memoryId);
+            throw new McpError(ErrorCode.InvalidParams, "Memory changed after the confirmation preview. Call delete_memory again with confirmed=false before deleting.");
+        }
+        const response = await this.axios.delete(`/api/extension/memories/${encodeURIComponent(parsed.memoryId)}`, {
+            timeout: 10_000,
+        });
+        this.deleteConfirmations.delete(parsed.memoryId);
+        return {
+            success: true,
+            deleted: response.data?.success === true,
+            memory,
+            memoryId: parsed.memoryId,
+        };
+    }
     async getMemoriesByTimeRange(args) {
         const parsed = timeRangeSchema.parse(args);
         const enc = await this.encState();
@@ -479,15 +776,36 @@ class EchoMemMCPServer {
             this.events.setClient(this.server.getClientVersion()?.name);
             // Inject a compact topic map of the user's memory into the search-tool description so the agent
             // knows the boundary up front and recalls proactively (cached; best-effort — no map on failure).
-            if (this.client.hasToken() && !this.mapCache)
+            if (this.client.hasToken() && !this.mapCache) {
                 this.mapCache = this.client.fetchMemoryMap();
-            const map = this.mapCache ? await this.mapCache : undefined;
+                // Don't poison the cache on a transient failure → clear it so a later listing can retry.
+                this.mapCache.then((m) => { if (!m)
+                    this.mapCache = null; }).catch(() => { this.mapCache = null; });
+            }
+            // NEVER block tool-listing on the network. A flaky/unreachable API would otherwise hang the MCP
+            // handshake and freeze the whole agent ("connection timed out after 30000ms"). The map is
+            // best-effort: cap the wait, and it'll be injected on the next listing once it resolves.
+            const map = this.mapCache
+                ? await Promise.race([this.mapCache, new Promise((r) => setTimeout(() => r(undefined), 2500))])
+                : undefined;
             this.mapInjected = !!map;
             return { tools: listToolSpecs({ map }) };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const canonicalName = resolveCanonicalToolName(request.params.name);
             const t0 = Date.now();
+            const analyticsBase = {
+                surface: "mcp",
+                event_family: "mcp",
+                integration: "echomem_mcp",
+                telemetry_source: "local_bridge",
+                codex_session_id: this.client.getSessionId(),
+                conversation_id: this.client.getSessionId(),
+                tool_name: request.params.name,
+                canonical_tool_name: canonicalName,
+                ...triggerAnalyticsForTool(canonicalName, request.params.arguments),
+                ...inputAnalyticsForTool(canonicalName, request.params.arguments),
+            };
             // One event per call. Handlers enrich `rec` with tool-specific detail; we finalize + log in `finally`.
             const rec = {
                 type: "tool_call",
@@ -501,6 +819,13 @@ class EchoMemMCPServer {
                 }
                 if (!this.client.hasToken())
                     throw new NoTokenError();
+                if (canonicalName !== canonicalToolNames.save) {
+                    void this.client.trackMcpAnalyticsEvent("[MCP] EchoMem Tool Called", analyticsBase);
+                    void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, "Called"), analyticsBase);
+                }
+                if (canonicalName !== canonicalToolNames.save && analyticsBase.trigger_message_available === true) {
+                    void this.client.trackMcpAnalyticsEvent("[MCP] EchoMem Triggered By User Turn", analyticsBase);
+                }
                 switch (canonicalName) {
                     case canonicalToolNames.search:
                         return await this.handleSearch(request.params.arguments, rec);
@@ -512,6 +837,8 @@ class EchoMemMCPServer {
                         return await this.handleKeywords(request.params.arguments);
                     case canonicalToolNames.others:
                         return await this.handleOthers(request.params.arguments);
+                    case canonicalToolNames.delete:
+                        return await this.handleDelete(request.params.arguments, rec);
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }
@@ -559,6 +886,24 @@ class EchoMemMCPServer {
                 rec.ok = rec.error_kind === "none";
                 rec.latency_ms = Date.now() - t0;
                 this.events.record(rec);
+                if (canonicalName !== canonicalToolNames.report &&
+                    canonicalName !== canonicalToolNames.save &&
+                    this.client.hasToken()) {
+                    const finalAnalytics = {
+                        ...analyticsBase,
+                        success: rec.ok,
+                        duration_ms: rec.latency_ms,
+                        error_type: rec.error_kind === "none" ? undefined : rec.error_kind,
+                        result_count: rec.results_count,
+                        returned_text_length: rec.results_chars,
+                        tuned: rec.tuned,
+                        map_injected: rec.map_injected,
+                        encrypted_user: rec.encrypted,
+                        extracted_memory_count: rec.memories_extracted,
+                    };
+                    void this.client.trackMcpAnalyticsEvent(rec.ok ? "[MCP] EchoMem Tool Succeeded" : "[MCP] EchoMem Tool Failed", finalAnalytics);
+                    void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, rec.ok ? "Succeeded" : "Failed"), finalAnalytics);
+                }
             }
         });
     }
@@ -743,6 +1088,56 @@ Details: ${m.details || "N/A"}`)
             ],
         };
     }
+    async handleDelete(args, rec) {
+        const parsed = deleteMemorySchema.parse(args);
+        if (rec) {
+            rec.memory_id_hash = hashText(parsed.memoryId);
+            rec.delete_confirmed = parsed.confirmed;
+        }
+        const result = await this.client.deleteMemory(args);
+        if (result.notFound) {
+            return {
+                content: [{ type: "text", text: `Memory ${result.memoryId} was not found or is not accessible.` }],
+            };
+        }
+        if (result.confirmationRequired) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Deletion requires explicit user confirmation. No memory was deleted.",
+                            "",
+                            formatDeletePreview(result.memory),
+                            "",
+                            `confirmationToken: ${result.confirmationToken}`,
+                            `expiresAt: ${result.expiresAt}`,
+                            "",
+                            "Ask the user whether to delete this memory. If and only if they confirm, call delete_memory again with confirmed=true and this exact confirmationToken.",
+                            "This deletes the memory row only; raw source_of_truth conversation records are preserved.",
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        if (!result.deleted) {
+            throw new Error("EchoMem API Error: delete request did not report success.");
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `Deleted memory ${result.memoryId}.`,
+                        "",
+                        formatDeletePreview(result.memory),
+                        "",
+                        "Raw source_of_truth conversation records were preserved.",
+                    ].join("\n"),
+                },
+            ],
+        };
+    }
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);