recallx 1.0.7 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jazpiper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -204,10 +204,29 @@ Use the returned endpoint list and request examples to search nodes and activiti
 Reuse the existing local service instead of starting a new one.
 ```
 
+Recommended instruction for MCP-connected coding agents:
+
+```text
+Use my RecallX MCP server as an active local memory layer during this task, not just for final write-back.
+Treat the current workspace as the default scope and do not switch workspaces unless I explicitly ask.
+Before making assumptions or starting meaningful work, read context first: confirm the current workspace, use recallx_search_workspace when the target is still unclear, search for an existing project node when the task is clearly project-shaped, and build a compact recallx_context_bundle once the relevant node or project is known.
+Prefer compact context over repeated broad browsing.
+Once a project is known, append routine work logs to that project instead of writing untargeted workspace captures.
+At the end of meaningful work, write back a concise summary of what changed, what was verified, and any follow-up.
+```
+
+MCP result rendering note:
+
+- RecallX MCP keeps `structuredContent` as the authoritative machine-readable payload.
+- The mirrored text content may be a compact deterministic summary rather than a pretty-printed JSON dump.
+- For the current rendering policy and compatibility guidance, see `docs/mcp.md`.
+
 ## MCP Bridge
 
 RecallX also ships a stdio MCP adapter for agent clients that prefer tool discovery over raw HTTP calls.
 
+MCP tool results keep `structuredContent` as the authoritative machine-readable payload, while `content.text` is rendered as a compact deterministic summary instead of a pretty-printed JSON mirror when the payload shape is known.
+
 ```bash
 npm run mcp
 node dist/server/app/mcp/index.js --api http://127.0.0.1:8787/api/v1
@@ -225,3 +244,7 @@ For launcher paths, environment variables, and editor-specific setup, see `docs/
 - `docs/mcp.md` for MCP bridge setup
 - `docs/workflows.md` for common usage flows
 - `docs/schema.md` for storage and data model details
+
+## License
+
+MIT. See `LICENSE`.

package/app/cli/src/format.js

@@ -206,8 +206,18 @@ export function renderTelemetrySummary(data) {
     `since: ${data?.since || ""}`,
     `logs: ${data?.logsPath || ""}`,
     `events: ${data?.totalEvents ?? 0}`,
+    `slow threshold: ${data?.slowRequestThresholdMs ?? ""}ms`,
   ];
 
+  const hot = Array.isArray(data?.hotOperations) ? data.hotOperations : [];
+  if (hot.length > 0) {
+    lines.push("");
+    lines.push("Hot operations:");
+    for (const item of hot.slice(0, 5)) {
+      lines.push(`- [${item.surface}] ${item.operation} p95=${item.p95DurationMs ?? ""}ms errors=${item.errorCount}/${item.count}`);
+    }
+  }
+
   const slow = Array.isArray(data?.slowOperations) ? data.slowOperations : [];
   if (slow.length > 0) {
     lines.push("");

package/app/mcp/index.js

@@ -45,7 +45,7 @@ async function resolveObservabilityState() {
             workspaceRoot: typeof workspace.rootPath === "string" ? workspace.rootPath : process.cwd(),
             workspaceName: typeof workspace.workspaceName === "string" ? workspace.workspaceName : "RecallX MCP",
             retentionDays: typeof values["observability.retentionDays"] === "number" ? values["observability.retentionDays"] : 14,
-            slowRequestMs: typeof values["observability.slowRequestMs"] === "number" ? values["observability.slowRequestMs"] : 250,
+            slowRequestMs: typeof values["observability.slowRequestMs"] === "number" ? values["observability.slowRequestMs"] : 50,
             capturePayloadShape: values["observability.capturePayloadShape"] !== false
         };
     }
@@ -55,7 +55,7 @@ async function resolveObservabilityState() {
             workspaceRoot: process.cwd(),
             workspaceName: "RecallX MCP",
             retentionDays: 14,
-            slowRequestMs: 250,
+            slowRequestMs: 50,
             capturePayloadShape: true
         };
     }

package/app/mcp/server.js

@@ -64,8 +64,264 @@ function coerceBooleanSchema(defaultValue) {
         return value;
     }, z.boolean().default(defaultValue));
 }
+const textSummaryItemLimit = 5;
+const textSummaryLength = 140;
+const textTitleLength = 80;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cleanInlineText(value, maxLength = textSummaryLength) {
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (compact.length <= maxLength) {
+        return compact;
+    }
+    return `${compact.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function formatKeyLabel(key) {
+    return key
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .trim();
+}
+function capitalize(value) {
+    return value ? `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}` : value;
+}
+function pickString(record, keys) {
+    for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === "string" && candidate.trim()) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function summarizeValue(value) {
+    if (typeof value === "string" && value.trim()) {
+        return cleanInlineText(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `${value.length} item(s)`;
+    }
+    if (isRecord(value)) {
+        const title = pickString(value, ["title", "name", "id", "nodeId"]);
+        if (title) {
+            return cleanInlineText(title);
+        }
+        return `${Object.keys(value).length} field(s)`;
+    }
+    return undefined;
+}
+function unwrapSummaryRecord(record) {
+    const resultType = typeof record.resultType === "string" ? record.resultType : undefined;
+    if (resultType && isRecord(record[resultType])) {
+        const nested = record[resultType];
+        return {
+            kind: (resultType === "activity" ? pickString(nested, ["activityType"]) : undefined) ??
+                (resultType === "node" ? pickString(nested, ["type"]) : undefined) ??
+                resultType,
+            value: nested
+        };
+    }
+    if (isRecord(record.node)) {
+        return {
+            kind: resultType ?? "node",
+            value: record.node
+        };
+    }
+    if (isRecord(record.activity)) {
+        return {
+            kind: resultType ?? "activity",
+            value: record.activity
+        };
+    }
+    return {
+        kind: pickString(record, ["type", "activityType", "status"]) ??
+            (typeof record.resultType === "string" ? record.resultType : undefined),
+        value: record
+    };
+}
+function summarizeRecordLine(record, index) {
+    const { kind, value } = unwrapSummaryRecord(record);
+    const title = pickString(value, ["title", "targetNodeTitle", "name", "workspaceName", "rootPath", "id", "nodeId"]);
+    const identifier = pickString(value, ["id", "nodeId", "targetNodeId"]);
+    const detail = pickString(value, ["summary", "reason", "body", "message", "staleReason", "workspaceRoot"]);
+    const parts = [`${index}.`];
+    if (kind) {
+        parts.push(`[${kind}]`);
+    }
+    if (title) {
+        parts.push(cleanInlineText(title, textTitleLength));
+    }
+    if (identifier && identifier !== title) {
+        parts.push(`(id: ${cleanInlineText(identifier, textTitleLength)})`);
+    }
+    let line = parts.join(" ");
+    if (detail) {
+        line += ` - ${cleanInlineText(detail)}`;
+    }
+    return line;
+}
+function formatItemsSummary(payload) {
+    const rawItems = payload.items;
+    if (!Array.isArray(rawItems)) {
+        return null;
+    }
+    const items = rawItems.filter(isRecord);
+    const shown = Math.min(items.length, textSummaryItemLimit);
+    const total = typeof payload.total === "number" ? payload.total : items.length;
+    const lines = [`Results: ${shown} shown of ${total} total.`];
+    if (!items.length) {
+        lines.push("No results.");
+    }
+    else {
+        for (const [index, item] of items.slice(0, textSummaryItemLimit).entries()) {
+            lines.push(summarizeRecordLine(item, index + 1));
+        }
+    }
+    if (total > shown) {
+        lines.push(`More available: ${total - shown} additional result(s).`);
+    }
+    else if (items.length > shown) {
+        lines.push(`More available: ${items.length - shown} additional item(s).`);
+    }
+    if (typeof payload.nextCursor === "string" && payload.nextCursor.trim()) {
+        lines.push(`Next cursor: ${cleanInlineText(payload.nextCursor, textTitleLength)}`);
+    }
+    return lines.join("\n");
+}
+function formatBundleSummary(payload) {
+    const bundle = isRecord(payload.bundle) ? payload.bundle : payload;
+    if (!isRecord(payload.bundle) && !isRecord(bundle.target)) {
+        return null;
+    }
+    const target = isRecord(bundle.target) ? bundle.target : null;
+    const type = target ? pickString(target, ["type"]) : undefined;
+    const mode = pickString(bundle, ["mode"]);
+    const preset = pickString(bundle, ["preset"]);
+    const summary = pickString(bundle, ["summary"]);
+    const items = Array.isArray(bundle.items) ? bundle.items.filter(isRecord) : [];
+    const decisions = Array.isArray(bundle.decisions) ? bundle.decisions : [];
+    const openQuestions = Array.isArray(bundle.openQuestions) ? bundle.openQuestions : [];
+    const activityDigest = Array.isArray(bundle.activityDigest) ? bundle.activityDigest : [];
+    const lines = [`Context bundle: Target${type ? ` [${type}]` : ""}.`];
+    if (mode || preset) {
+        lines.push(`Mode: ${[mode, preset].filter(Boolean).join(", ")}.`);
+    }
+    if (summary) {
+        lines.push(`Summary: ${cleanInlineText(summary)}`);
+    }
+    lines.push(`Items: ${items.length}.`);
+    for (const [index, item] of items.slice(0, textSummaryItemLimit).entries()) {
+        lines.push(summarizeRecordLine(item, index + 1));
+    }
+    if (items.length > textSummaryItemLimit) {
+        lines.push(`More bundle items: ${items.length - textSummaryItemLimit}.`);
+    }
+    if (activityDigest.length) {
+        lines.push(`Activity digest: ${activityDigest.length} entr${activityDigest.length === 1 ? "y" : "ies"}.`);
+    }
+    if (decisions.length) {
+        lines.push(`Decisions: ${decisions.length}.`);
+    }
+    if (openQuestions.length) {
+        lines.push(`Open questions: ${openQuestions.length}.`);
+    }
+    return lines.join("\n");
+}
+function formatWriteSummary(payload) {
+    const primaryKey = ["node", "activity", "relation"].find((key) => isRecord(payload[key]));
+    if (!primaryKey && !isRecord(payload.landing)) {
+        return null;
+    }
+    const lines = [];
+    if (primaryKey && isRecord(payload[primaryKey])) {
+        lines.push(`${capitalize(primaryKey)} stored: ${summarizeRecordLine(payload[primaryKey], 1).replace(/^1\.\s*/, "")}`);
+    }
+    if (isRecord(payload.landing)) {
+        const landing = payload.landing;
+        const parts = [
+            typeof landing.storedAs === "string" ? `storedAs=${landing.storedAs}` : null,
+            typeof landing.canonicality === "string" ? `canonicality=${landing.canonicality}` : null,
+            typeof landing.status === "string" ? `status=${landing.status}` : null,
+            typeof landing.governanceState === "string" ? `governance=${landing.governanceState}` : null
+        ].filter((value) => Boolean(value));
+        if (parts.length) {
+            lines.push(`Landing: ${parts.join(", ")}.`);
+        }
+        if (typeof landing.reason === "string" && landing.reason.trim()) {
+            lines.push(`Reason: ${cleanInlineText(landing.reason)}`);
+        }
+    }
+    return lines.length ? lines.join("\n") : null;
+}
+function formatObjectSummary(payload) {
+    const preferredKeys = [
+        "status",
+        "message",
+        "workspaceName",
+        "workspaceRoot",
+        "rootPath",
+        "schemaVersion",
+        "authMode",
+        "bindAddress",
+        "queued",
+        "queuedCount",
+        "nodeId",
+        "id",
+        "title",
+        "type",
+        "summary",
+        "reason",
+        "nextCursor"
+    ];
+    const orderedKeys = Array.from(new Set([...preferredKeys.filter((key) => key in payload), ...Object.keys(payload).filter((key) => !preferredKeys.includes(key))]));
+    const lines = [];
+    for (const key of orderedKeys) {
+        const summary = summarizeValue(payload[key]);
+        if (!summary) {
+            continue;
+        }
+        lines.push(`${formatKeyLabel(key)}: ${summary}`);
+        if (lines.length >= 8) {
+            break;
+        }
+    }
+    return lines.length ? lines.join("\n") : "Structured response returned.";
+}
+function formatArraySummary(items) {
+    const recordItems = items.filter(isRecord);
+    if (!recordItems.length) {
+        return `Items: ${items.length}.`;
+    }
+    const lines = [`Items: ${recordItems.length}.`];
+    for (const [index, item] of recordItems.slice(0, textSummaryItemLimit).entries()) {
+        lines.push(summarizeRecordLine(item, index + 1));
+    }
+    if (recordItems.length > textSummaryItemLimit) {
+        lines.push(`More available: ${recordItems.length - textSummaryItemLimit} additional item(s).`);
+    }
+    return lines.join("\n");
+}
 function formatStructuredContent(content) {
-    return JSON.stringify(content, null, 2);
+    if (Array.isArray(content)) {
+        return formatArraySummary(content);
+    }
+    if (isRecord(content)) {
+        return formatBundleSummary(content) ?? formatItemsSummary(content) ?? formatWriteSummary(content) ?? formatObjectSummary(content);
+    }
+    if (typeof content === "string" && content.trim()) {
+        return cleanInlineText(content);
+    }
+    if (typeof content === "number" || typeof content === "boolean") {
+        return String(content);
+    }
+    return "Structured response returned.";
+}
+function renderToolText(_toolName, structuredContent) {
+    return formatStructuredContent(structuredContent);
 }
 function formatInvalidBundleModeMessage(input) {
     const quotedInput = typeof input === "string" && input.trim() ? `'${input}'` : "that value";
@@ -85,12 +341,12 @@ function bundlePresetSchema(defaultValue) {
         error: (issue) => formatInvalidBundlePresetMessage(issue.input)
     })).default(defaultValue);
 }
-function toolResult(structuredContent) {
+function toolResult(toolName, structuredContent) {
     return {
         content: [
             {
                 type: "text",
-                text: formatStructuredContent(structuredContent)
+                text: renderToolText(toolName, structuredContent)
             }
         ],
         structuredContent
@@ -133,14 +389,14 @@ const readOnlyToolAnnotations = {
     readOnlyHint: true,
     idempotentHint: true
 };
-function createGetToolHandler(apiClient, path) {
-    return async () => toolResult(await apiClient.get(path));
+function createGetToolHandler(toolName, apiClient, path) {
+    return async () => toolResult(toolName, await apiClient.get(path));
 }
-function createPostToolHandler(apiClient, path) {
-    return async (input) => toolResult(await apiClient.post(path, input));
+function createPostToolHandler(toolName, apiClient, path) {
+    return async (input) => toolResult(toolName, await apiClient.post(path, input));
 }
-function createNormalizedPostToolHandler(apiClient, path, normalize) {
-    return async (input) => toolResult(await apiClient.post(path, normalize(input)));
+function createNormalizedPostToolHandler(toolName, apiClient, path, normalize) {
+    return async (input) => toolResult(toolName, await apiClient.post(path, normalize(input)));
 }
 function withReadOnlyAnnotations(config) {
     return {
@@ -312,7 +568,7 @@ export function createRecallXMcpServer(params) {
         workspaceRoot: process.cwd(),
         workspaceName: "RecallX MCP",
         retentionDays: 14,
-        slowRequestMs: 250,
+        slowRequestMs: 50,
         capturePayloadShape: true
     };
     let currentObservabilityState = params?.observabilityState ?? defaultObservabilityState;
@@ -335,7 +591,7 @@ export function createRecallXMcpServer(params) {
         name: "recallx-mcp",
         version: params?.serverVersion ?? RECALLX_VERSION
     }, {
-        instructions: "Use RecallX as a local knowledge backend. Treat the current workspace as the default scope, and do not create or open another workspace unless the user explicitly asks. When the work is clearly project-shaped, search for an existing project inside the current workspace first: prefer recallx_search_nodes with type=project, broaden with recallx_search_workspace when needed, create a project node only if no suitable one exists, and then anchor follow-up context with recallx_context_bundle targetId. Once a project is known, do not keep writing untargeted workspace captures for routine work logs: append activity to that project or pass targetNodeId on capture writes. Reserve workspace-scope inbox activity for genuinely untargeted, cross-project, or not-yet-classified short logs. If the conversation is not project-specific, keep memory at workspace scope. Prefer read tools first, and include source details on durable writes when you want caller-specific provenance.",
+        instructions: "Use RecallX as the default local memory layer for meaningful work, not as an afterthought. Treat the current workspace as the default scope, and do not create or open another workspace unless the user explicitly asks. Before making assumptions or starting a meaningful task, read context first: confirm the active workspace, use recallx_search_workspace as the broad default when the target is still unclear, narrow with recallx_search_nodes or recallx_search_activities when needed, and build a compact recallx_context_bundle before deep execution when a node or project is known. When the work is clearly project-shaped, search for an existing project inside the current workspace first, create one only if no suitable project exists, and then anchor follow-up context and routine logs to that project. Once a project is known, do not keep writing untargeted workspace captures for routine work logs: append activity to that project or pass targetNodeId on capture writes. Reserve workspace-scope inbox activity for genuinely untargeted, cross-project, or not-yet-classified short logs. Prefer read tools before durable writes, prefer compact context over repeated broad browsing, and write back concise summaries, decisions, or feedback when RecallX materially helped the task. Include source details on durable writes when you want caller-specific provenance.",
         capabilities: {
             logging: {}
         }
@@ -388,12 +644,12 @@ export function createRecallXMcpServer(params) {
             includeDetails: z.boolean().optional().default(true)
         }),
         outputSchema: healthOutputSchema
-    }, async () => toolResult(await apiClient.get("/health")));
+    }, async () => toolResult("recallx_health", await apiClient.get("/health")));
     registerReadOnlyTool(server, "recallx_workspace_current", {
         title: "Current Workspace",
         description: "Read the currently active RecallX workspace and auth mode. Use this to confirm the default workspace scope before deciding whether an explicit user request justifies switching workspaces.",
         outputSchema: workspaceInfoSchema
-    }, createGetToolHandler(apiClient, "/workspace"));
+    }, createGetToolHandler("recallx_workspace_current", apiClient, "/workspace"));
     registerReadOnlyTool(server, "recallx_workspace_list", {
         title: "List Workspaces",
         description: "List known RecallX workspaces and identify the currently active one.",
@@ -401,7 +657,7 @@ export function createRecallXMcpServer(params) {
             current: workspaceInfoSchema,
             items: z.array(workspaceInfoSchema.extend({ isCurrent: z.boolean(), lastOpenedAt: z.string() }))
         })
-    }, createGetToolHandler(apiClient, "/workspaces"));
+    }, createGetToolHandler("recallx_workspace_list", apiClient, "/workspaces"));
     registerTool(server, "recallx_workspace_create", {
         title: "Create Workspace",
         description: "Create a RecallX workspace on disk and switch the running service to it without restarting. Only use this when the user explicitly requests creating or switching to a new workspace.",
@@ -409,14 +665,14 @@ export function createRecallXMcpServer(params) {
             rootPath: z.string().min(1).describe("Absolute or user-resolved path for the new workspace root."),
             workspaceName: z.string().min(1).optional().describe("Human-friendly workspace name.")
         }
-    }, createPostToolHandler(apiClient, "/workspaces"));
+    }, createPostToolHandler("recallx_workspace_create", apiClient, "/workspaces"));
     registerTool(server, "recallx_workspace_open", {
         title: "Open Workspace",
         description: "Switch the running RecallX service to another existing workspace. Only use this when the user explicitly requests opening or switching workspaces.",
         inputSchema: {
             rootPath: z.string().min(1).describe("Existing workspace root path to open.")
         }
-    }, createPostToolHandler(apiClient, "/workspaces/open"));
+    }, createPostToolHandler("recallx_workspace_open", apiClient, "/workspaces/open"));
     registerReadOnlyTool(server, "recallx_semantic_status", {
         title: "Semantic Index Status",
         description: "Read the current semantic indexing status, provider configuration, and queued item counts.",
@@ -434,7 +690,7 @@ export function createRecallXMcpServer(params) {
                 failed: z.number()
             })
         })
-    }, createGetToolHandler(apiClient, "/semantic/status"));
+    }, createGetToolHandler("recallx_semantic_status", apiClient, "/semantic/status"));
     registerReadOnlyTool(server, "recallx_semantic_issues", {
         title: "Semantic Index Issues",
         description: "Read semantic indexing issues with optional status filters and cursor pagination.",
@@ -462,7 +718,7 @@ export function createRecallXMcpServer(params) {
         if (statuses?.length) {
             params.set("statuses", statuses.join(","));
         }
-        return toolResult(await apiClient.get(`/semantic/issues?${params.toString()}`));
+        return toolResult("recallx_semantic_issues", await apiClient.get(`/semantic/issues?${params.toString()}`));
     });
     registerReadOnlyTool(server, "recallx_search_nodes", {
         title: "Search Nodes",
@@ -486,7 +742,7 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/nodes/search", normalizeNodeSearchInput));
+    }, createNormalizedPostToolHandler("recallx_search_nodes", apiClient, "/nodes/search", normalizeNodeSearchInput));
     registerReadOnlyTool(server, "recallx_search_activities", {
         title: "Search Activities",
         description: "Search operational activity timelines by keyword and optional filters. Prefer this for recent logs, change history, and 'what happened recently' questions. Accepts `activityType` and `targetNodeId` aliases and normalizes single strings into arrays.",
@@ -508,7 +764,7 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/activities/search", normalizeActivitySearchInput));
+    }, createNormalizedPostToolHandler("recallx_search_activities", apiClient, "/activities/search", normalizeActivitySearchInput));
     registerReadOnlyTool(server, "recallx_search_workspace", {
         title: "Search Workspace",
         description: "Search nodes, activities, or both through one workspace-wide endpoint. This is the preferred broad entry point when the target node or request shape is still unclear, or when you need both node and activity recall in the current workspace. Use `scopes` as an array such as `[\"nodes\", \"activities\"]`, or use `scope: \"activities\"` for a single scope. Do not pass a comma-separated string like `\"nodes,activities\"`.",
@@ -538,14 +794,14 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at", "smart"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/search", normalizeWorkspaceSearchInput));
+    }, createNormalizedPostToolHandler("recallx_search_workspace", apiClient, "/search", normalizeWorkspaceSearchInput));
     registerReadOnlyTool(server, "recallx_get_node", {
         title: "Get Node",
         description: "Fetch a node together with its related nodes, activities, artifacts, and provenance.",
         inputSchema: {
             nodeId: z.string().min(1).describe("Target node id.")
         }
-    }, async ({ nodeId }) => toolResult(await apiClient.get(`/nodes/${encodeURIComponent(nodeId)}`)));
+    }, async ({ nodeId }) => toolResult("recallx_get_node", await apiClient.get(`/nodes/${encodeURIComponent(nodeId)}`)));
     registerReadOnlyTool(server, "recallx_get_related", {
         title: "Get Node Neighborhood",
         description: "Fetch the canonical RecallX node neighborhood with optional inferred relations.",
@@ -565,7 +821,7 @@ export function createRecallXMcpServer(params) {
         if (relationTypeFilter.length) {
             query.set("types", relationTypeFilter.join(","));
         }
-        return toolResult(await apiClient.get(`/nodes/${encodeURIComponent(nodeId)}/neighborhood?${query.toString()}`));
+        return toolResult("recallx_get_related", await apiClient.get(`/nodes/${encodeURIComponent(nodeId)}/neighborhood?${query.toString()}`));
     });
     registerTool(server, "recallx_upsert_inferred_relation", {
         title: "Upsert Inferred Relation",
@@ -583,7 +839,7 @@ export function createRecallXMcpServer(params) {
             expiresAt: z.string().optional(),
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/inferred-relations"));
+    }, createPostToolHandler("recallx_upsert_inferred_relation", apiClient, "/inferred-relations"));
     registerTool(server, "recallx_append_relation_usage_event", {
         title: "Append Relation Usage Event",
         description: "Append a lightweight usage signal after a relation actually helped retrieval or final output.",
@@ -597,7 +853,7 @@ export function createRecallXMcpServer(params) {
             delta: z.number(),
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/relation-usage-events"));
+    }, createPostToolHandler("recallx_append_relation_usage_event", apiClient, "/relation-usage-events"));
     registerTool(server, "recallx_append_search_feedback", {
         title: "Append Search Feedback",
         description: "Append a usefulness signal for a node or activity search result after it helped or failed a task.",
@@ -612,7 +868,7 @@ export function createRecallXMcpServer(params) {
             confidence: z.number().min(0).max(1).default(1),
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/search-feedback-events"));
+    }, createPostToolHandler("recallx_append_search_feedback", apiClient, "/search-feedback-events"));
     registerTool(server, "recallx_recompute_inferred_relations", {
         title: "Recompute Inferred Relations",
         description: "Run an explicit maintenance pass that refreshes inferred relation usage_score and final_score from usage events.",
@@ -621,7 +877,7 @@ export function createRecallXMcpServer(params) {
             generator: z.string().min(1).optional(),
             limit: z.number().int().min(1).max(500).default(100)
         }
-    }, createPostToolHandler(apiClient, "/inferred-relations/recompute"));
+    }, createPostToolHandler("recallx_recompute_inferred_relations", apiClient, "/inferred-relations/recompute"));
     registerTool(server, "recallx_append_activity", {
         title: "Append Activity",
         description: "Append an activity entry to a specific RecallX node or project timeline with provenance. Use this when you already know the target node or project; otherwise prefer recallx_capture_memory for general workspace-scope updates.",
@@ -632,7 +888,7 @@ export function createRecallXMcpServer(params) {
             source: sourceSchema,
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/activities"));
+    }, createPostToolHandler("recallx_append_activity", apiClient, "/activities"));
     registerTool(server, "recallx_capture_memory", {
         title: "Capture Memory",
         description: "Safely capture a memory item without choosing low-level storage first. Prefer this as the default write only when the conversation is not yet tied to a specific project or node. Once a project or target node is known, include targetNodeId or switch to recallx_append_activity for routine work logs. General short logs can stay at workspace scope and be auto-routed into activities, while reusable content can still land as durable memory.",
@@ -646,7 +902,7 @@ export function createRecallXMcpServer(params) {
             source: sourceSchema,
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/capture"));
+    }, createPostToolHandler("recallx_capture_memory", apiClient, "/capture"));
     registerTool(server, "recallx_create_node", {
         title: "Create Node",
         description: "Create a durable RecallX node with provenance. Use this for reusable knowledge; when creating a project node in the current workspace, search first and only create one if no suitable project already exists. Short work-log updates are usually better captured with `recallx_capture_memory` or `recallx_append_activity`.",
@@ -663,7 +919,7 @@ export function createRecallXMcpServer(params) {
         }
     }, async (input) => {
         try {
-            return toolResult(await apiClient.post("/nodes", input));
+            return toolResult("recallx_create_node", await apiClient.post("/nodes", input));
         }
         catch (error) {
             if (error instanceof RecallXApiError &&
@@ -695,7 +951,7 @@ export function createRecallXMcpServer(params) {
                 .min(1)
                 .max(100)
         }
-    }, async (input) => toolResult(await apiClient.post("/nodes/batch", input)));
+    }, async (input) => toolResult("recallx_create_nodes", await apiClient.post("/nodes/batch", input)));
     registerTool(server, "recallx_create_relation", {
         title: "Create Relation",
         description: "Create a relation between two nodes. Agent-created relations typically start suggested and are promoted automatically when confidence improves.",
@@ -707,7 +963,7 @@ export function createRecallXMcpServer(params) {
             source: sourceSchema,
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/relations"));
+    }, createPostToolHandler("recallx_create_relation", apiClient, "/relations"));
     registerReadOnlyTool(server, "recallx_list_governance_issues", {
         title: "List Governance Issues",
         description: "List contested or low-confidence governance items that may need inspection.",
@@ -720,7 +976,7 @@ export function createRecallXMcpServer(params) {
             states: states.join(","),
             limit: String(limit)
         });
-        return toolResult(await apiClient.get(`/governance/issues?${query.toString()}`));
+        return toolResult("recallx_list_governance_issues", await apiClient.get(`/governance/issues?${query.toString()}`));
     });
     registerReadOnlyTool(server, "recallx_get_governance_state", {
         title: "Get Governance State",
@@ -729,7 +985,7 @@ export function createRecallXMcpServer(params) {
             entityType: z.enum(["node", "relation"]),
             entityId: z.string().min(1)
         }
-    }, async ({ entityType, entityId }) => toolResult(await apiClient.get(`/governance/state/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`)));
+    }, async ({ entityType, entityId }) => toolResult("recallx_get_governance_state", await apiClient.get(`/governance/state/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`)));
     registerTool(server, "recallx_recompute_governance", {
         title: "Recompute Governance",
         description: "Run a bounded automatic governance recompute pass for nodes, relations, or both.",
@@ -738,7 +994,7 @@ export function createRecallXMcpServer(params) {
             entityIds: z.array(z.string().min(1)).max(200).optional(),
             limit: z.number().int().min(1).max(500).default(100)
         }
-    }, createPostToolHandler(apiClient, "/governance/recompute"));
+    }, createPostToolHandler("recallx_recompute_governance", apiClient, "/governance/recompute"));
     registerReadOnlyTool(server, "recallx_context_bundle", {
         title: "Build Context Bundle",
         description: "Build a compact RecallX context bundle for coding, research, writing, or decision support. Omit targetId to get a workspace-entry bundle when the work is not yet tied to a specific project or node, and add targetId only after you know which project or node should anchor the context.",
@@ -766,7 +1022,7 @@ export function createRecallXMcpServer(params) {
                 maxItems: 10
             })
         }
-    }, async ({ targetId, ...input }) => toolResult(await apiClient.post("/context/bundles", {
+    }, async ({ targetId, ...input }) => toolResult("recallx_context_bundle", await apiClient.post("/context/bundles", {
         ...input,
         ...(targetId
             ? {
@@ -782,14 +1038,14 @@ export function createRecallXMcpServer(params) {
         inputSchema: {
             limit: coerceIntegerSchema(250, 1, 1000)
         }
-    }, createPostToolHandler(apiClient, "/semantic/reindex"));
+    }, createPostToolHandler("recallx_semantic_reindex", apiClient, "/semantic/reindex"));
     registerTool(server, "recallx_semantic_reindex_node", {
         title: "Queue Node Semantic Reindex",
         description: "Queue semantic reindexing for a specific node id.",
         inputSchema: {
             nodeId: z.string().min(1)
         }
-    }, async ({ nodeId }) => toolResult(await apiClient.post(`/semantic/reindex/${encodeURIComponent(nodeId)}`, {})));
+    }, async ({ nodeId }) => toolResult("recallx_semantic_reindex_node", await apiClient.post(`/semantic/reindex/${encodeURIComponent(nodeId)}`, {})));
     registerReadOnlyTool(server, "recallx_rank_candidates", {
         title: "Rank Candidate Nodes",
         description: "Rank a bounded set of candidate node ids for a target using RecallX request-time retrieval scoring.",
@@ -799,6 +1055,6 @@ export function createRecallXMcpServer(params) {
             preset: bundlePresetSchema("for-assistant"),
             targetNodeId: z.string().optional()
         }
-    }, createPostToolHandler(apiClient, "/retrieval/rank-candidates"));
+    }, createPostToolHandler("recallx_rank_candidates", apiClient, "/retrieval/rank-candidates"));
     return server;
 }