@hydradb/mcp 1.2.1 → 1.3.0

package/dist/server.js

@@ -1,12 +1,14 @@
+import { Buffer } from "node:buffer";
 import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { toAddMemoryResponse, toMemoryList, toSourceList } from "./adapters.js";
-import { resolveConfig } from "./config.js";
+import { resolveConfig, resolveGraphConfig } from "./config.js";
 import { renderRecalledContext } from "./context.js";
+import { COLLECTION_PATTERN, MAX_BODY_BYTES, renderRows } from "./cypher.js";
 import { SERVER_INSTRUCTIONS, TOOL_DESCRIPTIONS } from "./descriptions.js";
-import { HydraDB } from "./hydra/index.js";
+import { assertCollectionAllowed, assertDatabaseAllowed, HydraDB } from "./hydra/index.js";
 import { logger } from "./logger.js";
 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
@@ -238,7 +240,12 @@ export function legacyToolsEnabled(env = process.env) {
 export function __resetAliasWarnings() {
     warnedAliases.clear();
 }
-export function createHydraDBServer(hydraOverride) {
+export function createHydraDBServer(hydraOverride, 
+/**
+ * Graph scope/gating override, for tests and embedders. Without it the graph
+ * config is read from the environment exactly as the rest of the config is.
+ */
+graphOverride, options = {}) {
     const server = new McpServer({
         name: "hydradb-mcp",
         version: SERVER_VERSION,
@@ -246,8 +253,10 @@ export function createHydraDBServer(hydraOverride) {
         instructions: SERVER_INSTRUCTIONS,
     });
     let hydra;
+    let graphConfig;
     if (hydraOverride) {
         hydra = hydraOverride;
+        graphConfig = { ...resolveGraphConfig(), ...graphOverride };
     }
     else {
         const config = resolveConfig();
@@ -261,6 +270,7 @@ export function createHydraDBServer(hydraOverride) {
                 : {}),
             ...(config.maxRetries != null ? { maxRetries: config.maxRetries } : {}),
         });
+        graphConfig = { ...config.graph, ...graphOverride };
         logger.info(`Hydra DB connected (database=${config.database}, collection=${config.collection})`);
     }
     // --- Handlers (shared by canonical tools and their deprecated aliases) ---
@@ -282,6 +292,8 @@ export function createHydraDBServer(hydraOverride) {
             metadataFilters: args.metadata_filters,
             numRelatedChunks: args.num_related_chunks,
             graphContext: args.graph_context ?? true,
+            database: args.database,
+            collection: args.collection,
             // Host-owned default (CONTRACT §2 rule 5), but only where it means
             // something: alpha balances dense against sparse retrieval in HYBRID
             // mode, and an `operator` switches the query to text retrieval (see
@@ -422,6 +434,8 @@ export function createHydraDBServer(hydraOverride) {
             text: args.text,
             title: args.title ?? defaultTitle(args.text),
             ...memoryOnly,
+            database: args.database,
+            collection: args.collection,
             // Default stays true. The SDK retries POSTs, so upsert is what keeps a
             // retried ingest from duplicating — flipping this default would trade a
             // silent overwrite for a silent duplicate.
@@ -455,6 +469,8 @@ export function createHydraDBServer(hydraOverride) {
             isMarkdown: opts?.isMarkdown,
             customInstructions: INGEST_INSTRUCTIONS,
             upsert: opts?.overwrite ?? true,
+            database: opts?.database,
+            collection: opts?.collection,
         }, { signal });
         const res = toAddMemoryResponse(raw);
         const conversationId = createdId(res) ?? sourceId;
@@ -506,6 +522,8 @@ export function createHydraDBServer(hydraOverride) {
             ids: args.source_ids,
             page: args.page,
             pageSize: args.page_size,
+            database: args.database,
+            collection: args.collection,
         }, { signal });
         const { memories, page } = toMemoryList(raw);
         if (memories.length === 0) {
@@ -554,6 +572,8 @@ export function createHydraDBServer(hydraOverride) {
             ids: args.source_ids,
             page: args.page,
             pageSize: args.page_size,
+            database: args.database,
+            collection: args.collection,
         }, { signal });
         const { sources, page } = toSourceList(raw);
         if (sources.length === 0) {
@@ -693,6 +713,8 @@ export function createHydraDBServer(hydraOverride) {
             offset: a.offset,
             limit: a.limit,
             expiry_seconds: a.expiry_seconds,
+            database: a.database,
+            collection: a.collection,
         };
     }
     async function runInspect(args, signal) {
@@ -701,6 +723,8 @@ export function createHydraDBServer(hydraOverride) {
             id: args.source_id,
             mode: args.mode ?? "content",
             expirySeconds: args.expiry_seconds,
+            database: args.database,
+            collection: args.collection,
         }, { signal });
         // Soft failure: return a normal (non-error) text result, matching v1.
         if (!res.success || res.error) {
@@ -723,7 +747,11 @@ export function createHydraDBServer(hydraOverride) {
     }
     async function runStatus(args, signal) {
         logger.debug(`${TOOL_NAMES.STATUS}: ${args.ids.join(", ")}`);
-        const res = await hydra.context.ingestionStatus({ ids: args.ids }, { signal });
+        const res = await hydra.context.ingestionStatus({
+            ids: args.ids,
+            database: args.database,
+            collection: args.collection,
+        }, { signal });
         const statuses = res.statuses ?? [];
         if (statuses.length === 0) {
             return textResult(`No indexing status found for: ${args.ids.join(", ")}. ` +
@@ -834,12 +862,17 @@ export function createHydraDBServer(hydraOverride) {
             throw new Error(`${TOOL_NAMES.DELETE} requires \`ids\` (or \`id\`). Ids come from ` +
                 `${TOOL_NAMES.QUERY} or ${TOOL_NAMES.LIST} — do not guess one.`);
         }
-        return { ids, kind: a.kind };
+        return { ids, kind: a.kind, database: a.database, collection: a.collection };
     }
     async function runDelete(args, signal) {
         const kind = args.kind ?? "memory";
         logger.debug(`${TOOL_NAMES.DELETE}: ${kind} ${args.ids.join(", ")}`);
-        const res = await hydra.context.delete({ ids: args.ids, kind }, { signal });
+        const res = await hydra.context.delete({
+            ids: args.ids,
+            kind,
+            database: args.database,
+            collection: args.collection,
+        }, { signal });
         // `userMemoryDeleted` is a COUNT on the v2 wire — a live delete returned
         // `{"deletedCount":1,"userMemoryDeleted":1}` — and the SDK types it as a
         // number. The v1 memory-delete handler returns a boolean for the same
@@ -865,6 +898,257 @@ export function createHydraDBServer(hydraOverride) {
         }
         return deleteReport(kind, args.ids, res, removed, removedCount);
     }
+    /**
+     * Which databases this connection can address, and which is the default.
+     *
+     * A confined connection answers from its allowed list without a network
+     * call: the list IS the answer, and asking the API would only show
+     * databases the connection is not permitted to use.
+     */
+    async function runDatabases() {
+        const defaultDatabase = hydra.database;
+        let databases;
+        let confined = false;
+        if (hydra.allowedDatabases) {
+            databases = [...hydra.allowedDatabases];
+            confined = true;
+        }
+        else {
+            const listed = await hydra.databases.list();
+            databases = (listed.databases ?? listed.tenantIds ?? []).filter(Boolean);
+        }
+        if (!databases.includes(defaultDatabase))
+            databases.unshift(defaultDatabase);
+        const lines = databases.map((d) => `  - ${d}${d === defaultDatabase ? "  (default for this connection)" : ""}`);
+        const note = confined
+            ? "\nThis connection is confined to the database(s) above; any other name is refused. " +
+                "The user chose this when approving the connection."
+            : "\nPass `database` on any tool to work in another one.";
+        return structuredResult(`${databases.length} database(s):\n${lines.join("\n")}${note}`, { databases, default: defaultDatabase, confined });
+    }
+    // --- BYOG graph handlers ---
+    /**
+     * The scope a graph call runs against.
+     *
+     * Resolved per call rather than captured once, so a caller can address a
+     * second graph without reconfiguring the server. The collection name is
+     * validated here because the server's rule is a documented charset and
+     * rejecting locally names it, where the remote failure is a bare 400.
+     */
+    /**
+     * The graph database a call runs against, checked against the connection's
+     * allowed set. The graph client does not go through the context client's
+     * scope(), so the same rule is applied here for every graph tool.
+     */
+    function graphDatabase(override) {
+        const database = override?.trim() || graphConfig.database;
+        if (database && database !== hydra.database) {
+            assertDatabaseAllowed(database, hydra.allowedDatabases);
+        }
+        return database;
+    }
+    /**
+     * The graph collection a call runs against, checked the same way the
+     * database is. `drop_collection` makes an unchecked override destructive,
+     * so confinement covers both axes or it covers nothing.
+     */
+    function graphCollection(override) {
+        const collection = override?.trim() || graphConfig.collection;
+        if (collection && collection !== hydra.collection) {
+            assertCollectionAllowed(collection, hydra.allowedCollections);
+        }
+        return collection;
+    }
+    function graphScope(args) {
+        const database = graphDatabase(args.database);
+        const collection = graphCollection(args.collection);
+        if (!database) {
+            throw new Error("No graph database configured. Set HYDRADB_GRAPH_DATABASE (or HYDRADB_DATABASE), " +
+                "or pass `database` on this call.");
+        }
+        if (!COLLECTION_PATTERN.test(collection)) {
+            throw new Error(`Invalid graph collection name "${collection}". Collection names must match ` +
+                "[A-Za-z0-9][A-Za-z0-9_-]{0,63} — start with a letter or digit, then letters, " +
+                "digits, underscores or hyphens, up to 64 characters.");
+        }
+        return { database, collection };
+    }
+    /**
+     * Refuse an oversized request before it goes out.
+     *
+     * The server answers a body over 256 KiB with 413, but only after receiving
+     * all of it — so on the bulk loads where this actually happens, the remote
+     * check is the slowest possible way to learn the batch was too big. Measured
+     * in BYTES, not characters: the cap is on the encoded body, and non-ASCII
+     * property values are where a "small enough" batch stops being one.
+     */
+    function assertBodyFits(body) {
+        let bytes;
+        try {
+            // The WHOLE body, not just the caller's two fields. `database` and
+            // `collection` are serialised alongside the query, so measuring
+            // without them let a payload sitting just under the cap pass here and
+            // be rejected remotely with a 413 — after the entire thing had been
+            // uploaded, which is the outcome this check exists to avoid.
+            bytes = Buffer.byteLength(JSON.stringify(body) ?? "", "utf8");
+        }
+        catch {
+            throw new Error("`params` could not be serialised to JSON — it must contain only plain " +
+                "values (strings, numbers, booleans, null, arrays, objects).");
+        }
+        if (bytes > MAX_BODY_BYTES) {
+            throw new Error(`This request is ${Math.round(bytes / 1024)} KiB, over Hydra DB's ` +
+                `${MAX_BODY_BYTES / 1024} KiB limit. Split it into batches — send rows in ` +
+                "chunks with `UNWIND $rows AS row ...` (about 500 rows per call is a good start).");
+        }
+    }
+    /**
+     * The single Cypher entry point: reads and writes go through one tool.
+     *
+     * This deliberately does NOT inspect the query. An earlier version lexed it
+     * to classify reads vs writes and to pre-reject constructs the server
+     * refuses; both were a client reimplementing the server's rules, able only
+     * to agree with it or to be wrong. The server rejects unsupported
+     * constructs before executing anything and says so more precisely than we
+     * did, so the query goes out as written.
+     */
+    async function runGraphCypher(args, signal) {
+        const scope = graphScope(args);
+        assertBodyFits({ ...scope, query: args.query, params: args.params });
+        logger.debug(`${TOOL_NAMES.GRAPH_QUERY}: ${scope.database}/${scope.collection}`);
+        const rows = await hydra.graph.query({ ...scope, query: args.query, params: args.params }, { signal });
+        // A write with no RETURN legitimately yields zero rows. Reporting that as
+        // "no results" invites the caller to retry a write that already committed.
+        if (rows.length === 0) {
+            return structuredResult(
+            // Zero rows means one of two things and this does not guess which:
+            // a read that matched nothing, or a write with no RETURN clause.
+            // Naming both keeps a caller from re-running a write that already
+            // committed because the result "looked empty".
+            `The query ran against ${scope.database}/${scope.collection} and returned ` +
+                "0 rows. For a read that means nothing matched; for a write with no RETURN " +
+                "clause it is the expected result and the write has been applied — do not " +
+                "re-run it to check.", { database: scope.database, collection: scope.collection, rows: [], row_count: 0 });
+        }
+        const maxRows = args.max_rows ?? 100;
+        const rendered = renderRows(rows, { maxRows });
+        return structuredResult(`${rows.length} row(s) from ${scope.database}/${scope.collection}:\n\n${rendered}`, {
+            database: scope.database,
+            collection: scope.collection,
+            // Bounded the same way the prose is: structured output is a different
+            // encoding of the same answer, not a bypass of its limits.
+            rows: rows.slice(0, maxRows),
+            row_count: rows.length,
+        });
+    }
+    async function runGraphCollections(args, signal) {
+        const database = graphDatabase(args.database);
+        if (!database) {
+            throw new Error("No graph database configured. Set HYDRADB_GRAPH_DATABASE (or HYDRADB_DATABASE), " +
+                "or pass `database` on this call.");
+        }
+        logger.debug(`${TOOL_NAMES.GRAPH_COLLECTIONS}: ${database}`);
+        const collections = await hydra.graph.listCollections({ database }, { signal });
+        if (collections.length === 0) {
+            return structuredResult(`No graph collections in ${database} yet. Collections are created by their ` +
+                `first write — run one with ${TOOL_NAMES.GRAPH_QUERY}.`, { database, collections: [], count: 0 });
+        }
+        return structuredResult(`${collections.length} graph collection(s) in ${database}:\n` +
+            collections.map((name) => `  - ${name}`).join("\n"), { database, collections, count: collections.length });
+    }
+    async function runGraphAdmin(args, signal) {
+        const database = graphDatabase(args.database);
+        if (!database) {
+            throw new Error("No graph database configured. Set HYDRADB_GRAPH_DATABASE (or HYDRADB_DATABASE), " +
+                "or pass `database` on this call.");
+        }
+        logger.debug(`${TOOL_NAMES.GRAPH_ADMIN}: ${args.action} ${database}`);
+        if (args.action === "create_database") {
+            const res = await hydra.graph.createDatabase(database, { signal });
+            return structuredResult(`Created graph database "${database}" (status: ${res.status ?? "ready"}). ` +
+                "Collections are created by their first write; there is no create-collection step.", { action: args.action, database, status: res.status ?? "ready", created: true });
+        }
+        if (args.action === "drop_collection") {
+            const collection = args.collection?.trim();
+            if (!collection) {
+                throw new Error(`${TOOL_NAMES.GRAPH_ADMIN} action "drop_collection" requires \`collection\` — ` +
+                    "the name of the graph to drop. Nothing was deleted.");
+            }
+            // This action takes its collection directly rather than through
+            // graphCollection(), because there is no default to fall back to, so
+            // the confinement check has to be stated here as well. It is the one
+            // place an unchecked collection would be irreversible.
+            if (collection !== hydra.collection) {
+                assertCollectionAllowed(collection, hydra.allowedCollections);
+            }
+            await hydra.graph.dropCollection({ database, collection }, { signal });
+            // The endpoint is idempotent and does not report whether anything was
+            // there, so this states what was requested rather than claiming a
+            // removal that may not have had anything to remove.
+            return structuredResult(`Dropped graph collection "${collection}" from ${database}, along with all its ` +
+                "data. This call is idempotent, so it also succeeds when the collection did " +
+                "not exist.", { action: args.action, database, collection, dropped: true });
+        }
+        if (args.action === "drop_database") {
+            // This deletes EVERY graph collection in the database, so on a
+            // collection-confined connection it cannot be performed within the
+            // confinement: even an allowed database holds collections the user
+            // never approved. The per-collection checks elsewhere cannot catch
+            // this one, because the call names no collection at all. Refuse the
+            // action outright rather than let the broadest destructive operation
+            // be the way around the narrowest grant.
+            if (hydra.allowedCollections) {
+                throw new Error(`This connection is confined to collection ${hydra.allowedCollections
+                    .map((c) => `"${c}"`)
+                    .join(", ")}, and "drop_database" removes every collection in ` +
+                    `"${database}", including ones it was not granted. Nothing was deleted. ` +
+                    'Use "drop_collection" for a collection this connection may use, or ' +
+                    "reconnect with wider access.");
+            }
+            const res = await hydra.graph.dropDatabase(database, { signal });
+            const dropped = res.deleted_collections ?? [];
+            const listed = dropped.length > 0 ? ` Collections removed: ${dropped.join(", ")}.` : "";
+            // Three outcomes, not two, and the third is "we were not told".
+            //
+            // `deleted: false` is a real, different result — the database predates
+            // BYOG, so only its graph collections went and the database itself
+            // remains. Reporting that as a full drop tells the user something is
+            // gone that is still there.
+            //
+            // A MISSING `deleted` used to fall into the same branch as `true` and
+            // claim a full drop. On a destructive, irreversible call that is the
+            // wrong direction to guess in: the server did not establish that
+            // outcome, so it is not asserted. Say what is known and how to check.
+            let text;
+            if (res.deleted === true) {
+                text = `Dropped graph database "${database}" and everything in it.${listed}`;
+            }
+            else if (res.deleted === false) {
+                text =
+                    `Dropped the graph collections in "${database}", but NOT the database itself — ` +
+                        "it was created through the standard database API, so remove it there." +
+                        listed;
+            }
+            else {
+                text =
+                    `Dropped the graph collections in "${database}".${listed} The server did not ` +
+                        "report whether the database itself was removed, so that is unconfirmed — " +
+                        "check with your database listing rather than assuming it is gone.";
+            }
+            return structuredResult(text, {
+                action: args.action,
+                database,
+                // Omitted rather than guessed when the server did not say, matching
+                // how the memory delete path reports an unknown count.
+                ...(typeof res.deleted === "boolean"
+                    ? { database_deleted: res.deleted }
+                    : { database_deleted_known: false }),
+                deleted_collections: dropped,
+            });
+        }
+        throw new Error(`${TOOL_NAMES.GRAPH_ADMIN} received an unknown action "${args.action}". ` +
+            'Valid actions are "create_database", "drop_collection" and "drop_database".');
+    }
     // --- Registration helper ---
     function register(name, inputSchema, handler, annotations, outputSchema) {
         const desc = TOOL_DESCRIPTIONS[name];
@@ -885,6 +1169,18 @@ export function createHydraDBServer(hydraOverride) {
         }, wrapped);
     }
     // --- Input schemas ---
+    const scopeSchema = {
+        database: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.database),
+        collection: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.collection),
+    };
     const querySchema = {
         query: z.string().describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.query),
         kind: z
@@ -929,6 +1225,7 @@ export function createHydraDBServer(hydraOverride) {
             .max(5)
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.num_related_chunks),
+        ...scopeSchema,
     };
     const storeSchema = {
         text: z
@@ -957,6 +1254,7 @@ export function createHydraDBServer(hydraOverride) {
             .boolean()
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.STORE].params.overwrite),
+        ...scopeSchema,
     };
     const ingestMetadataSchema = {
         metadata: z
@@ -1018,6 +1316,7 @@ export function createHydraDBServer(hydraOverride) {
             .string()
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INGEST_CONVERSATION].params.user_name),
+        ...scopeSchema,
     };
     const listSchema = {
         // Required, not defaulted. `hydradb_list({})` used to return memories only
@@ -1048,12 +1347,17 @@ export function createHydraDBServer(hydraOverride) {
             .max(100)
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST].params.page_size),
+        ...scopeSchema,
     };
     const listSourcesSchema = {
         source_ids: z
             .array(z.string())
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST_SOURCES].params.source_ids),
+        ...scopeSchema,
+    };
+    const listMemoriesSchema = {
+        ...scopeSchema,
     };
     const inspectSchema = {
         // CONTRACT §1 says a source's identifier field is `id`, but this surface
@@ -1091,6 +1395,7 @@ export function createHydraDBServer(hydraOverride) {
             .min(1)
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INSPECT].params.expiry_seconds),
+        ...scopeSchema,
     };
     const deleteSchema = {
         ids: z
@@ -1106,6 +1411,7 @@ export function createHydraDBServer(hydraOverride) {
             .enum(["memory", "knowledge"])
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.DELETE].params.kind),
+        ...scopeSchema,
     };
     // Output schemas, declared only where the result is genuinely structured.
     // Query stays prose: its payload IS text, and forcing it into fields would
@@ -1144,11 +1450,78 @@ export function createHydraDBServer(hydraOverride) {
             .array(z.string())
             .min(1)
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.STATUS].params.ids),
+        ...scopeSchema,
     };
     const deleteMemorySchema = {
         memory_id: z
             .string()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.DELETE_MEMORY].params.memory_id),
+        ...scopeSchema,
+    };
+    // --- BYOG graph schemas ---
+    const graphScopeSchema = {
+        database: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_QUERY].params.database),
+        collection: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_QUERY].params.collection),
+    };
+    /**
+     * Cypher text is bounded like every other free-text input on this server.
+     * The 256 KiB body cap covers query plus params together and is checked in
+     * the handler; this only stops an absurd query string before it gets there.
+     */
+    const MAX_CYPHER_CHARS = 100000;
+    const graphCypherSchema = {
+        query: z
+            .string()
+            .min(1, { message: "query must not be empty" })
+            .max(MAX_CYPHER_CHARS, {
+            message: `query must be at most ${MAX_CYPHER_CHARS} characters`,
+        })
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_QUERY].params.query),
+        params: z
+            .record(z.unknown())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_QUERY].params.params),
+        ...graphScopeSchema,
+        max_rows: z
+            .number()
+            .int()
+            .min(1)
+            .max(1000)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_QUERY].params.max_rows),
+    };
+    const graphCollectionsSchema = {
+        database: z
+            .string()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_COLLECTIONS].params.database),
+    };
+    const graphAdminSchema = {
+        action: z
+            .enum(["create_database", "drop_collection", "drop_database"])
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_ADMIN].params.action),
+        database: z
+            .string()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_ADMIN].params.database),
+        collection: z
+            .string()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.GRAPH_ADMIN].params.collection),
+    };
+    const graphRowsOutputSchema = {
+        database: z.string(),
+        collection: z.string(),
+        rows: z.array(z.record(z.unknown())),
+        row_count: z.number(),
     };
     // `destructiveHint` was missing from the annotations type, so no tool could
     // declare it — and the MCP spec defaults it to TRUE for any non-readonly
@@ -1228,6 +1601,8 @@ export function createHydraDBServer(hydraOverride) {
                 title: a.title,
                 isMarkdown: a.is_markdown,
                 overwrite: a.overwrite,
+                database: a.database,
+                collection: a.collection,
             }, extra?.signal);
         }
         if (a.text != null) {
@@ -1241,6 +1616,8 @@ export function createHydraDBServer(hydraOverride) {
                 overwrite: a.overwrite,
                 metadata: a.metadata,
                 observation_date: a.observation_date,
+                database: a.database,
+                collection: a.collection,
             }, extra?.signal);
         }
         throw new Error(`${TOOL_NAMES.INGEST} requires either \`text\` (a note) or \`turns\` (a conversation).`);
@@ -1268,13 +1645,55 @@ export function createHydraDBServer(hydraOverride) {
         }
         const ids = a.ids ?? a.source_ids;
         if (a.kind === "knowledge") {
-            return runListSources({ source_ids: ids, page: a.page, page_size: a.page_size }, extra?.signal);
+            return runListSources({
+                source_ids: ids,
+                page: a.page,
+                page_size: a.page_size,
+                database: a.database,
+                collection: a.collection,
+            }, extra?.signal);
         }
-        return runListMemories({ source_ids: ids, page: a.page, page_size: a.page_size }, extra?.signal);
+        return runListMemories({
+            source_ids: ids,
+            page: a.page,
+            page_size: a.page_size,
+            database: a.database,
+            collection: a.collection,
+        }, extra?.signal);
     }, readOnly, listOutputSchema);
     register(TOOL_NAMES.INSPECT, inspectSchema, (args, extra) => runInspect(toInspectArgs(args), extra?.signal), readOnly);
     register(TOOL_NAMES.DELETE, deleteSchema, (args, extra) => runDelete(toDeleteArgs(args), extra?.signal), destructive, deleteOutputSchema);
     register(TOOL_NAMES.STATUS, statusSchema, (args, extra) => runStatus(args, extra?.signal), readOnly);
+    // Only an OAuth connection carries a user's database decision, and only
+    // there does an agent need a way to see it. Registering this for API-key
+    // connections too would change their tool list, which must stay identical.
+    if (options.oauthTools) {
+        register(TOOL_NAMES.DATABASES, {}, () => runDatabases(), readOnly);
+    }
+    // --- BYOG graph tools (PRO-1681) ---
+    //
+    // A separate product surface from the memory/knowledge tools above: property
+    // graphs the user models and owns, addressed in Cypher. Registered by
+    // default so the capability is discoverable — the feature exists today and
+    // no client surfaces it — and gated by one switch:
+    //
+    //   HYDRADB_MCP_GRAPH_TOOLS=0  withholds all three, for memory-only users
+    //                              who do not want the manifest cost.
+    //
+    // There is no read-only mode. It would have to classify Cypher client-side
+    // to decide what to refuse, which is a heuristic — offering it would invite
+    // operators to trust a guarantee it could not make. Withholding the tools
+    // outright is a real guarantee; that is the switch above.
+    if (graphConfig.enabled) {
+        register(TOOL_NAMES.GRAPH_QUERY, graphCypherSchema, (args, extra) => runGraphCypher(args, extra?.signal), 
+        // Destructive, not read-only: this one tool runs arbitrary Cypher, so
+        // DELETE is as reachable through it as MATCH. Annotating it any other
+        // way would tell a host it is safe to auto-approve, which is exactly
+        // the claim the removed read/write split could not actually back.
+        destructive, graphRowsOutputSchema);
+        register(TOOL_NAMES.GRAPH_COLLECTIONS, graphCollectionsSchema, (args, extra) => runGraphCollections(args, extra?.signal), readOnly);
+        register(TOOL_NAMES.GRAPH_ADMIN, graphAdminSchema, (args, extra) => runGraphAdmin(args, extra?.signal), destructive);
+    }
     // --- Deprecated aliases ---
     //
     // Registered only when HYDRADB_MCP_LEGACY_TOOLS is set. Off by default.
@@ -1303,14 +1722,23 @@ export function createHydraDBServer(hydraOverride) {
             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 }, extra?.signal);
+            return runIngestConversation(a.turns, a.source_id, {
+                userName: a.user_name,
+                database: a.database,
+                collection: a.collection,
+            }, extra?.signal);
         }, additiveWrite);
-        register(TOOL_NAMES.LIST_MEMORIES, {}, (_args, extra) => runListMemories({}, extra?.signal), readOnly);
+        register(TOOL_NAMES.LIST_MEMORIES, listMemoriesSchema, (args, extra) => runListMemories(args, extra?.signal), readOnly);
         register(TOOL_NAMES.LIST_SOURCES, listSourcesSchema, (args, extra) => runListSources(args, extra?.signal), readOnly);
         register(TOOL_NAMES.FETCH_CONTENT, inspectSchema, (args, extra) => runInspect(toInspectArgs(args), extra?.signal), readOnly);
         register(TOOL_NAMES.DELETE_MEMORY, deleteMemorySchema, (args, extra) => {
-            const { memory_id } = args;
-            return runDelete({ ids: [memory_id], kind: "memory" }, extra?.signal);
+            const a = args;
+            return runDelete({
+                ids: [a.memory_id],
+                kind: "memory",
+                database: a.database,
+                collection: a.collection,
+            }, extra?.signal);
         }, destructive);
     }
     return server.server;