@hydradb/mcp 1.0.0 → 1.1.1

package/dist/server.js

@@ -1,76 +1,103 @@
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { HydraDBClient } from "./client.js";
+import { toAddMemoryResponse, toMemoryList, toRecallResponse, toSourceList } from "./adapters.js";
+import { resolveConfig } from "./config.js";
 import { buildRecalledContext } from "./context.js";
-import { TOOL_DESCRIPTIONS, SERVER_INSTRUCTIONS } from "./descriptions.js";
+import { SERVER_INSTRUCTIONS, TOOL_DESCRIPTIONS } from "./descriptions.js";
+import { HydraDB } from "./hydra/index.js";
 import { logger } from "./logger.js";
-import { TOOL_NAMES } from "./tool-names.js";
-const DEFAULT_SUB_TENANT = "hydra-db-mcp";
-function getConfig() {
-    const apiKey = process.env.HYDRA_DB_API_KEY;
-    if (!apiKey) {
-        throw new Error("HYDRA_DB_API_KEY environment variable is required");
-    }
-    const tenantId = process.env.HYDRA_DB_TENANT_ID;
-    if (!tenantId) {
-        throw new Error("HYDRA_DB_TENANT_ID environment variable is required");
-    }
-    const subTenantId = process.env.HYDRA_DB_SUB_TENANT_ID || DEFAULT_SUB_TENANT;
-    return { apiKey, tenantId, subTenantId };
+import { ALIAS_REPLACEMENTS, DEPRECATED_TOOL_NAMES, TOOL_NAMES } from "./tool-names.js";
+// Host-owned default: silently attached to ingest so Hydra DB extracts the kind
+// of personal context this server cares about. Injected here (not in the
+// portable wrapper) because it is MCP-specific host behaviour.
+const INGEST_INSTRUCTIONS = "Focus on extracting user preferences, habits, opinions, likes, dislikes, " +
+    "goals, and recurring themes. Capture any stated or implied personal context " +
+    "that would help personalise future interactions.";
+// Read the version from package.json rather than repeating it here: the literal
+// this replaces sat at 1.0.0 through the whole 1.x line, so every client saw
+// stale version metadata. `../package.json` resolves to the package root from
+// both `src/` (tsx) and `dist/` (published build).
+const require = createRequire(import.meta.url);
+const { version: SERVER_VERSION } = require("../package.json");
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * What a query actually searched, for the result strings. A query over `all`
+ * must not report "memories" — that phrasing is what taught callers the MCP
+ * was memory-only in the first place.
+ */
+function resultNoun(kind, count) {
+    const one = count === 1;
+    if (kind === "memory")
+        return one ? "memory" : "memories";
+    if (kind === "knowledge")
+        return one ? "knowledge source" : "knowledge sources";
+    return one ? "context item" : "context items";
 }
-export function createHydraDBServer() {
+const turnSchema = z.object({
+    user: z.string().describe("The user's message"),
+    assistant: z.string().describe("The assistant's response"),
+});
+// Deprecated aliases emit exactly one stderr warning PER PROCESS naming the
+// canonical replacement (CONTRACT §3). The dedupe state is module-scoped so the
+// guarantee holds across multiple server instances in the same process, and is
+// intentionally NOT routed through `logger` — the warning must surface
+// regardless of HYDRA_DB_LOG_LEVEL.
+const warnedAliases = new Set();
+function warnDeprecatedAlias(name) {
+    if (warnedAliases.has(name))
+        return;
+    warnedAliases.add(name);
+    const replacement = ALIAS_REPLACEMENTS[name] ?? "a canonical tool";
+    console.error(`[hydradb-mcp] Tool "${name}" is deprecated and will be removed in a future major version; use "${replacement}" instead.`);
+}
+/** Test-only: reset the once-per-process alias warning dedupe. */
+export function __resetAliasWarnings() {
+    warnedAliases.clear();
+}
+export function createHydraDBServer(hydraOverride) {
     const server = new McpServer({
         name: "hydradb-mcp",
-        version: "1.0.0",
+        version: SERVER_VERSION,
     }, {
         instructions: SERVER_INSTRUCTIONS,
     });
-    const config = getConfig();
-    const client = new HydraDBClient(config.apiKey, config.tenantId, config.subTenantId);
-    // --- Search ---
-    const desc = TOOL_DESCRIPTIONS[TOOL_NAMES.SEARCH];
-    server.registerTool(TOOL_NAMES.SEARCH, {
-        title: desc.title,
-        description: desc.description,
-        inputSchema: {
-            query: z.string().describe(desc.params.query),
-            max_results: z
-                .number()
-                .min(1)
-                .max(50)
-                .optional()
-                .describe(desc.params.max_results),
-            mode: z
-                .enum(["fast", "thinking"])
-                .optional()
-                .describe(desc.params.mode),
-            graph_context: z
-                .boolean()
-                .optional()
-                .describe(desc.params.graph_context),
-        },
-        annotations: {
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        const { query, max_results, mode, graph_context, } = args;
-        logger.debug(`${TOOL_NAMES.SEARCH}: "${query}"`);
-        const res = await client.recall(query, {
-            maxResults: max_results ?? 10,
-            mode: mode ?? "thinking",
-            graphContext: graph_context ?? true,
+    let hydra;
+    if (hydraOverride) {
+        hydra = hydraOverride;
+    }
+    else {
+        const config = resolveConfig();
+        hydra = new HydraDB({
+            token: config.apiKey,
+            database: config.database,
+            collection: config.collection,
+            ...(config.baseUrl != null ? { baseUrl: config.baseUrl } : {}),
         });
+        logger.info(`Hydra DB connected (database=${config.database}, collection=${config.collection})`);
+    }
+    // --- Handlers (shared by canonical tools and their deprecated aliases) ---
+    async function runQuery(args) {
+        // Host-owned default (CONTRACT §2 rule 5): search BOTH families. This tool
+        // used to pin `kind: "memory"`, which made every ingested knowledge source
+        // unreachable from the MCP — `hydradb_list`/`hydradb_inspect` could browse
+        // knowledge but nothing could search it.
+        const kind = args.kind ?? "all";
+        logger.debug(`${TOOL_NAMES.QUERY}: "${args.query}" (kind=${kind})`);
+        const raw = await hydra.context.query({
+            query: args.query,
+            kind,
+            maxResults: args.max_results ?? 10,
+            mode: args.mode ?? "thinking",
+            graphContext: args.graph_context ?? true,
+            alpha: 0.8,
+            recencyBias: 0,
+        });
+        const res = toRecallResponse(raw);
         if (!res.chunks || res.chunks.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "No relevant memories found in Hydra DB.",
-                    },
-                ],
-            };
+            return textResult(`No relevant ${resultNoun(kind)} found in Hydra DB.`);
         }
         const contextStr = buildRecalledContext(res);
         const summary = res.chunks.slice(0, 10).map((c, i) => {
@@ -82,240 +109,312 @@ export function createHydraDBServer() {
                 : c.chunk_content;
             return `${i + 1}. ${snippet}${score}`;
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Found ${res.chunks.length} memories:\n\n${summary.join("\n")}\n\n---\nFull context:\n${contextStr}`,
-                },
-            ],
-        };
-    });
-    // --- Store ---
-    const storeDesc = TOOL_DESCRIPTIONS[TOOL_NAMES.STORE];
-    server.registerTool(TOOL_NAMES.STORE, {
-        title: storeDesc.title,
-        description: storeDesc.description,
-        inputSchema: {
-            text: z.string().describe(storeDesc.params.text),
-            title: z
-                .string()
-                .optional()
-                .describe(storeDesc.params.title),
-            source_id: z
-                .string()
-                .optional()
-                .describe(storeDesc.params.source_id),
-            infer: z
-                .boolean()
-                .optional()
-                .describe(storeDesc.params.infer),
-            is_markdown: z
-                .boolean()
-                .optional()
-                .describe(storeDesc.params.is_markdown),
-        },
-    }, async (args) => {
-        const { text, title, source_id, infer, is_markdown } = args;
-        logger.debug(`${TOOL_NAMES.STORE}: "${text.slice(0, 50)}..."`);
-        const res = await client.ingestText(text, {
-            sourceId: source_id,
-            title: title ?? "MCP Memory",
-            infer: infer ?? true,
-            isMarkdown: is_markdown ?? false,
+        return textResult(`Found ${res.chunks.length} ${resultNoun(kind, res.chunks.length)}:\n\n${summary.join("\n")}\n\n---\nFull context:\n${contextStr}`);
+    }
+    async function runStore(args) {
+        logger.debug(`${TOOL_NAMES.INGEST}: "${args.text.slice(0, 50)}..."`);
+        const raw = await hydra.context.ingest({
+            kind: "memory",
+            text: args.text,
+            title: args.title ?? "MCP Memory",
+            sourceId: args.source_id,
+            infer: args.infer ?? true,
+            isMarkdown: args.is_markdown ?? false,
+            customInstructions: INGEST_INSTRUCTIONS,
+            upsert: true,
         });
-        const preview = text.length > 80 ? `${text.slice(0, 80)}...` : text;
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Saved to Hydra DB (${res.success_count} success, ${res.failed_count} failed): "${preview}"`,
-                },
-            ],
-        };
-    });
-    // --- Ingest Conversation ---
-    const ingestDesc = TOOL_DESCRIPTIONS[TOOL_NAMES.INGEST_CONVERSATION];
-    const turnSchema = z.object({
-        user: z.string().describe("The user's message"),
-        assistant: z.string().describe("The assistant's response"),
-    });
-    server.registerTool(TOOL_NAMES.INGEST_CONVERSATION, {
-        title: ingestDesc.title,
-        description: ingestDesc.description,
-        inputSchema: {
-            turns: z
-                .array(turnSchema)
-                .min(1)
-                .describe(ingestDesc.params.turns),
-            source_id: z
-                .string()
-                .describe(ingestDesc.params.source_id),
-            user_name: z
-                .string()
-                .optional()
-                .describe(ingestDesc.params.user_name),
-        },
-    }, async (args) => {
-        const { turns, source_id, user_name } = args;
-        logger.debug(`${TOOL_NAMES.INGEST_CONVERSATION}: ${turns.length} turns -> ${source_id}`);
-        const res = await client.ingestConversation(turns, source_id, user_name);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Ingested ${turns.length} conversation turn(s) into Hydra DB (source: ${source_id}, success: ${res.success_count}, failed: ${res.failed_count})`,
-                },
-            ],
-        };
-    });
-    // --- List Memories ---
-    const listDesc = TOOL_DESCRIPTIONS[TOOL_NAMES.LIST_MEMORIES];
-    server.registerTool(TOOL_NAMES.LIST_MEMORIES, {
-        title: listDesc.title,
-        description: listDesc.description,
-        inputSchema: {},
-        annotations: {
-            readOnlyHint: true,
-            idempotentHint: true,
-        },
-    }, async () => {
-        logger.debug(TOOL_NAMES.LIST_MEMORIES);
-        const res = await client.listMemories();
-        const memories = res.user_memories ?? [];
+        const res = toAddMemoryResponse(raw);
+        const preview = args.text.length > 80 ? `${args.text.slice(0, 80)}...` : args.text;
+        return textResult(`Saved to Hydra DB (${res.success_count} success, ${res.failed_count} failed): "${preview}"`);
+    }
+    async function runIngestConversation(turns, sourceId, opts) {
+        logger.debug(`${TOOL_NAMES.INGEST}: ${turns.length} turns -> ${sourceId}`);
+        const raw = await hydra.context.ingest({
+            kind: "memory",
+            pairs: turns,
+            sourceId,
+            userName: opts?.userName ?? "User",
+            infer: opts?.infer ?? true,
+            title: opts?.title,
+            isMarkdown: opts?.isMarkdown,
+            customInstructions: INGEST_INSTRUCTIONS,
+            upsert: true,
+        });
+        const res = toAddMemoryResponse(raw);
+        return textResult(`Ingested ${turns.length} conversation turn(s) into Hydra DB (source: ${sourceId}, success: ${res.success_count}, failed: ${res.failed_count})`);
+    }
+    async function runListMemories() {
+        logger.debug(TOOL_NAMES.LIST);
+        const raw = await hydra.context.list({ kind: "memory" });
+        const memories = toMemoryList(raw);
         if (memories.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "No memories stored yet.",
-                    },
-                ],
-            };
+            return textResult("No memories stored yet.");
         }
         const lines = memories.map((m, i) => `${i + 1}. [${m.memory_id}] ${m.memory_content.slice(0, 150)}`);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `${memories.length} memories:\n\n${lines.join("\n")}`,
-                },
-            ],
-        };
-    });
-    // --- Delete Memory ---
-    const deleteDesc = TOOL_DESCRIPTIONS[TOOL_NAMES.DELETE_MEMORY];
-    server.registerTool(TOOL_NAMES.DELETE_MEMORY, {
-        title: deleteDesc.title,
-        description: deleteDesc.description,
-        inputSchema: {
-            memory_id: z.string().describe(deleteDesc.params.memory_id),
-        },
-    }, async (args) => {
-        const { memory_id } = args;
-        logger.debug(`${TOOL_NAMES.DELETE_MEMORY}: ${memory_id}`);
-        const res = await client.deleteMemory(memory_id);
-        if (res.user_memory_deleted) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Deleted memory: ${memory_id}`,
-                    },
-                ],
-            };
-        }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Memory ${memory_id} was not found or already deleted.`,
-                },
-            ],
-        };
-    });
-    // --- Fetch Content ---
-    const fetchDesc = TOOL_DESCRIPTIONS[TOOL_NAMES.FETCH_CONTENT];
-    server.registerTool(TOOL_NAMES.FETCH_CONTENT, {
-        title: fetchDesc.title,
-        description: fetchDesc.description,
-        inputSchema: {
-            source_id: z.string().describe(fetchDesc.params.source_id),
-            mode: z
-                .enum(["content", "url", "both"])
-                .optional()
-                .describe(fetchDesc.params.mode),
-        },
-        annotations: {
-            readOnlyHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        const { source_id, mode } = args;
-        logger.debug(`${TOOL_NAMES.FETCH_CONTENT}: ${source_id}`);
-        const res = await client.fetchContent(source_id, mode ?? "content");
-        if (!res.success || res.error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Could not fetch source ${source_id}: ${res.error ?? "unknown error"}`,
-                    },
-                ],
-            };
-        }
-        const content = res.content ?? res.content_base64 ?? "(no text content)";
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Source: ${source_id}\n\n${content}`,
-                },
-            ],
-        };
-    });
-    // --- List Sources ---
-    const sourcesDesc = TOOL_DESCRIPTIONS[TOOL_NAMES.LIST_SOURCES];
-    server.registerTool(TOOL_NAMES.LIST_SOURCES, {
-        title: sourcesDesc.title,
-        description: sourcesDesc.description,
-        inputSchema: {
-            source_ids: z
-                .array(z.string())
-                .optional()
-                .describe(sourcesDesc.params.source_ids),
-        },
-        annotations: {
-            readOnlyHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        const { source_ids } = args;
-        logger.debug(TOOL_NAMES.LIST_SOURCES);
-        const res = await client.listSources(source_ids);
-        if (!res.sources || res.sources.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "No sources found.",
-                    },
-                ],
-            };
+        return textResult(`${memories.length} memories:\n\n${lines.join("\n")}`);
+    }
+    async function runListSources(args) {
+        logger.debug(TOOL_NAMES.LIST);
+        const raw = await hydra.context.list({
+            kind: "knowledge",
+            ids: args.source_ids,
+        });
+        const { sources, total } = toSourceList(raw);
+        if (sources.length === 0) {
+            return textResult("No sources found.");
         }
-        const lines = res.sources.map((s, i) => {
+        const lines = sources.map((s, i) => {
             const title = s.title ? ` — ${s.title}` : "";
             const type = s.type ? ` (${s.type})` : "";
             return `${i + 1}. [${s.id}]${title}${type}`;
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `${res.total} sources:\n\n${lines.join("\n")}`,
-                },
-            ],
-        };
+        return textResult(`${total} sources:\n\n${lines.join("\n")}`);
+    }
+    async function runInspect(args) {
+        logger.debug(`${TOOL_NAMES.INSPECT}: ${args.source_id}`);
+        const res = await hydra.context.inspect({
+            id: args.source_id,
+            mode: args.mode ?? "content",
+        });
+        // Soft failure: return a normal (non-error) text result, matching v1.
+        if (!res.success || res.error) {
+            return textResult(`Could not fetch source ${args.source_id}: ${res.error ?? "unknown error"}`);
+        }
+        const content = res.content ?? res.contentBase64 ?? "(no text content)";
+        return textResult(`Source: ${args.source_id}\n\n${content}`);
+    }
+    /**
+     * Three outcomes, not two. A delete that removed nothing is either the
+     * benign idempotent case (the server succeeded, there was nothing there) or
+     * a refusal (the server returned success:false and told us why). Collapsing
+     * both into "not found or already deleted" states a cause we did not
+     * observe, and it is the reassuring one: the caller is told their data is
+     * gone when the server just declined to remove it.
+     */
+    function deleteReport(kind, id, res, removed) {
+        const noun = kind === "knowledge" ? "source" : "memory";
+        if (removed) {
+            return textResult(`Deleted ${noun}: ${id}`);
+        }
+        if (res.success === false) {
+            const reason = deleteFailureReason(res);
+            return textResult(`Could NOT delete ${noun} ${id} — the server refused the request` +
+                `${reason ? `: ${reason}` : " and gave no reason"}. ` +
+                `The ${noun} has not been removed.`);
+        }
+        const Noun = noun.charAt(0).toUpperCase() + noun.slice(1);
+        return textResult(`${Noun} ${id} was not found or already deleted.`);
+    }
+    /** The server's own explanation, preferring the per-item error over the summary. */
+    function deleteFailureReason(res) {
+        const items = Array.isArray(res.results) ? res.results : [];
+        for (const item of items) {
+            if (item != null && typeof item === "object") {
+                const error = item.error;
+                if (typeof error === "string" && error !== "")
+                    return error;
+            }
+        }
+        return res.message !== "" ? res.message : undefined;
+    }
+    async function runDelete(args) {
+        const kind = args.kind ?? "memory";
+        logger.debug(`${TOOL_NAMES.DELETE}: ${kind} ${args.id}`);
+        const res = await hydra.context.delete({ ids: [args.id], kind });
+        const removed = (res.userMemoryDeleted ?? 0) > 0 || (res.deletedCount ?? 0) > 0;
+        if (!removed) {
+            logger.warn(`${TOOL_NAMES.DELETE}: removed nothing for ${kind} ${args.id}`, { success: res.success, message: res.message, results: res.results });
+        }
+        return deleteReport(kind, args.id, res, removed);
+    }
+    // --- Registration helper ---
+    function register(name, inputSchema, handler, annotations) {
+        const desc = TOOL_DESCRIPTIONS[name];
+        const isDeprecated = DEPRECATED_TOOL_NAMES.includes(name);
+        const wrapped = isDeprecated
+            ? (args) => {
+                warnDeprecatedAlias(name);
+                return handler(args);
+            }
+            : handler;
+        server.registerTool(name, {
+            title: desc.title,
+            description: desc.description,
+            inputSchema: inputSchema,
+            ...(annotations ? { annotations } : {}),
+        }, wrapped);
+    }
+    // --- Input schemas ---
+    const querySchema = {
+        query: z.string().describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.query),
+        kind: z
+            .enum(["memory", "knowledge", "all"])
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.kind),
+        max_results: z
+            .number()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.max_results),
+        mode: z
+            .enum(["fast", "thinking"])
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.mode),
+        graph_context: z
+            .boolean()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.graph_context),
+    };
+    const storeSchema = {
+        text: z.string().describe(TOOL_DESCRIPTIONS[TOOL_NAMES.STORE].params.text),
+        title: z
+            .string()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.STORE].params.title),
+        source_id: z
+            .string()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.STORE].params.source_id),
+        infer: z
+            .boolean()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.STORE].params.infer),
+        is_markdown: z
+            .boolean()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.STORE].params.is_markdown),
+    };
+    const ingestSchema = {
+        ...storeSchema,
+        // Canonical ingest accepts EITHER `text` or `turns`, so `text` is optional
+        // here (the `hydra_db_store` alias keeps it required).
+        text: z
+            .string()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INGEST].params.text),
+        turns: z
+            .array(turnSchema)
+            .min(1)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INGEST].params.turns),
+        user_name: z
+            .string()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INGEST].params.user_name),
+    };
+    const conversationSchema = {
+        turns: z
+            .array(turnSchema)
+            .min(1)
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INGEST_CONVERSATION].params.turns),
+        source_id: z
+            .string()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INGEST_CONVERSATION].params.source_id),
+        user_name: z
+            .string()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INGEST_CONVERSATION].params.user_name),
+    };
+    const listSchema = {
+        kind: z
+            .enum(["memory", "knowledge"])
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST].params.kind),
+        source_ids: z
+            .array(z.string())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST].params.source_ids),
+    };
+    const listSourcesSchema = {
+        source_ids: z
+            .array(z.string())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST_SOURCES].params.source_ids),
+    };
+    const inspectSchema = {
+        source_id: z
+            .string()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INSPECT].params.source_id),
+        mode: z
+            .enum(["content", "url", "both"])
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INSPECT].params.mode),
+    };
+    const deleteSchema = {
+        id: z.string().describe(TOOL_DESCRIPTIONS[TOOL_NAMES.DELETE].params.id),
+        kind: z
+            .enum(["memory", "knowledge"])
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.DELETE].params.kind),
+    };
+    const deleteMemorySchema = {
+        memory_id: z
+            .string()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.DELETE_MEMORY].params.memory_id),
+    };
+    const readOnly = { readOnlyHint: true, idempotentHint: true };
+    const searchAnnotations = {
+        readOnlyHint: true,
+        openWorldHint: true,
+        idempotentHint: true,
+    };
+    // --- Canonical tools ---
+    register(TOOL_NAMES.QUERY, querySchema, (args) => runQuery(args), searchAnnotations);
+    register(TOOL_NAMES.INGEST, ingestSchema, async (args) => {
+        const a = args;
+        const hasTurns = a.turns != null && a.turns.length > 0;
+        // `text` and `turns` are mutually exclusive — reject rather than silently
+        // dropping one (the documented "exactly one" contract).
+        if (hasTurns && a.text != null) {
+            throw new Error(`${TOOL_NAMES.INGEST} accepts either \`text\` (a note) or \`turns\` (a conversation), not both.`);
+        }
+        if (a.turns != null && a.turns.length > 0) {
+            const sourceId = a.source_id ?? `mcp-conversation-${Date.now()}`;
+            // Forward every option the canonical schema accepts so none is
+            // silently dropped on the conversation path.
+            return runIngestConversation(a.turns, sourceId, {
+                userName: a.user_name,
+                infer: a.infer,
+                title: a.title,
+                isMarkdown: a.is_markdown,
+            });
+        }
+        if (a.text != null) {
+            return runStore({
+                text: a.text,
+                title: a.title,
+                source_id: a.source_id,
+                infer: a.infer,
+                is_markdown: a.is_markdown,
+            });
+        }
+        throw new Error(`${TOOL_NAMES.INGEST} requires either \`text\` (a note) or \`turns\` (a conversation).`);
+    });
+    register(TOOL_NAMES.LIST, listSchema, (args) => {
+        const a = args;
+        if ((a.kind ?? "memory") === "knowledge") {
+            return runListSources({ source_ids: a.source_ids });
+        }
+        return runListMemories();
+    }, readOnly);
+    register(TOOL_NAMES.INSPECT, inspectSchema, (args) => runInspect(args), readOnly);
+    register(TOOL_NAMES.DELETE, deleteSchema, (args) => runDelete(args));
+    // --- Deprecated aliases ---
+    register(TOOL_NAMES.SEARCH, querySchema, (args) => runQuery(args), searchAnnotations);
+    register(TOOL_NAMES.STORE, storeSchema, (args) => runStore(args));
+    register(TOOL_NAMES.INGEST_CONVERSATION, conversationSchema, (args) => {
+        const a = args;
+        // The deprecated alias keeps its historical shape (user_name only; infer
+        // on, no title/markdown). The canonical hydradb_ingest forwards the rest.
+        return runIngestConversation(a.turns, a.source_id, { userName: a.user_name });
+    });
+    register(TOOL_NAMES.LIST_MEMORIES, {}, () => runListMemories(), readOnly);
+    register(TOOL_NAMES.LIST_SOURCES, listSourcesSchema, (args) => runListSources(args), readOnly);
+    register(TOOL_NAMES.FETCH_CONTENT, inspectSchema, (args) => runInspect(args), readOnly);
+    register(TOOL_NAMES.DELETE_MEMORY, deleteMemorySchema, (args) => {
+        const { memory_id } = args;
+        return runDelete({ id: memory_id, kind: "memory" });
     });
     return server.server;
 }