@hydradb/mcp 1.2.2 → 1.4.0

package/dist/server.js

@@ -8,7 +8,7 @@ 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
@@ -245,7 +245,7 @@ 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) {
+graphOverride, options = {}) {
     const server = new McpServer({
         name: "hydradb-mcp",
         version: SERVER_VERSION,
@@ -290,17 +290,25 @@ graphOverride) {
             operator: args.operator,
             ids: args.source_ids,
             metadataFilters: args.metadata_filters,
+            acl: args.acl,
             numRelatedChunks: args.num_related_chunks,
             graphContext: args.graph_context ?? true,
+            queryApps: args.query_apps,
             database: args.database,
             collection: args.collection,
+            collections: args.collections,
             // 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
             // the wrapper), where there are no two lanes to weigh. Injecting it
             // there would send a hybrid-only knob on a request that is not hybrid.
             alpha: args.operator != null ? undefined : 0.8,
-            recencyBias: 0,
+            // Host-owned default (CONTRACT §2 rule 5), and 0 is also what the API
+            // applies when the field is omitted — so the default ranking is
+            // unchanged. It stops being a constant here because "what is the
+            // current state of X" is a different question from "what matches X",
+            // and only a caller that can raise this can ask the first one.
+            recencyBias: args.recency_bias ?? 0,
         }, { signal });
         // The renderer reads the SDK payload directly; there is no longer a
         // snake_case mirror to convert into.
@@ -522,6 +530,7 @@ graphOverride) {
             ids: args.source_ids,
             page: args.page,
             pageSize: args.page_size,
+            acl: args.acl,
             database: args.database,
             collection: args.collection,
         }, { signal });
@@ -572,6 +581,7 @@ graphOverride) {
             ids: args.source_ids,
             page: args.page,
             pageSize: args.page_size,
+            acl: args.acl,
             database: args.database,
             collection: args.collection,
         }, { signal });
@@ -713,16 +723,120 @@ graphOverride) {
             offset: a.offset,
             limit: a.limit,
             expiry_seconds: a.expiry_seconds,
+            acl: a.acl,
             database: a.database,
             collection: a.collection,
         };
     }
+    async function runSubgraph(args, signal) {
+        // Blank is rejected; anything else is forwarded byte for byte. The
+        // server treats an item id as opaque (ingest stores a caller's
+        // source_id verbatim), so trimming here could ask about a different
+        // item. Same rule as the CLI's `hydradb subgraph`.
+        const id = args.id ?? "";
+        if (id.trim() === "") {
+            throw new Error(`${TOOL_NAMES.SUBGRAPH} requires \`id\` — the value shown as [id: …] in ` +
+                `${TOOL_NAMES.QUERY} results or in [brackets] in ${TOOL_NAMES.LIST} output.`);
+        }
+        logger.debug(`${TOOL_NAMES.SUBGRAPH}: ${id}`);
+        const res = await hydra.context.subgraph({
+            id,
+            kind: args.kind,
+            depth: args.depth,
+            maxSources: args.max_sources,
+            acl: args.acl,
+            database: args.database,
+            collection: args.collection,
+        }, { signal });
+        // Soft failure, like inspect: the server's own message, flagged.
+        if (!res.success) {
+            return errorResult(`Could not read the subgraph of ${id}: ${res.message || "unknown error"}`);
+        }
+        const members = res.sources ?? [];
+        if (members.length === 0) {
+            return structuredResult(`No item with id ${id} was found in this collection, so there is no subgraph to show. ` +
+                `Ids come from ${TOOL_NAMES.QUERY} or ${TOOL_NAMES.LIST}; check the collection as well as the id.`, 
+            // Same keys as a populated result: a client reading
+            // structuredContent should not have to branch on which shape it got.
+            {
+                seed_id: id,
+                member_count: 0,
+                max_depth_reached: 0,
+                truncated: false,
+                relations: [],
+                structural_link_count: 0,
+                structural_truncated: false,
+                members: [],
+            });
+        }
+        const hops = res.max_depth_reached ?? 0;
+        // Sorted once, then used for both the prose and structuredContent: a
+        // machine client that renders the members must not get a different
+        // order from the one a reader sees.
+        const ordered = [...members].sort((a, b) => a.depth - b.depth);
+        const lines = [
+            members.length === 1 && !res.is_truncated
+                ? `${id} stands alone: nothing in the graph links to it yet.`
+                : `${members.length} item${members.length === 1 ? "" : "s"} connected to ${id} through ${hops} hop${hops === 1 ? "" : "s"}` +
+                    (res.is_truncated ? ` (clipped at max_sources; the subgraph continues)` : "") +
+                    ":",
+            "",
+        ];
+        // discovered_relation is the MECHANISM (same_thread, parent, child, or a
+        // relates_to type); discovered_via is the member this one was reached
+        // FROM — another member's id, so the list is also a tree. The parent id
+        // is shortened in the prose because it appears in full on its own line
+        // and in structuredContent; the relation is what a reader scans for.
+        const shortId = (id) => (id.length > 14 ? `${id.slice(0, 12)}…` : id);
+        for (const m of ordered) {
+            const title = m.title?.trim() || m.app_external_id || "(untitled)";
+            const reached = m.depth === 0
+                ? "the item you started from"
+                : `${m.discovered_relation || "linked"}${m.discovered_via ? ` from ${shortId(m.discovered_via)}` : ""}`;
+            const kind = [m.app_provider, m.app_kind].filter(Boolean).join(" ");
+            lines.push(`- [id: ${m.source_id}] ${title}${kind ? ` (${kind})` : ""} — depth ${m.depth}, ${reached}`);
+        }
+        lines.push("", `${(res.relations ?? []).length} relation(s) among them; ` +
+            `${(res.auxiliary_relations ?? []).length} structural link(s) around them` +
+            (res.auxiliary_truncated ? " (structural links clipped)" : "") +
+            `. Pass any [id: …] to ${TOOL_NAMES.INSPECT} for its full content.`);
+        // The edges make it a graph rather than a list, so structuredContent
+        // carries them too, compacted to what a client can act on: both
+        // endpoints are Source nodes, so entity_id is the member's id. The
+        // structural links are about entities and comments, not members, so
+        // they stay a count plus their own clipped flag, exactly as the prose
+        // reports them.
+        const edges = (res.relations ?? []).map((r) => ({
+            from: r.source?.entity_id ?? null,
+            to: r.target?.entity_id ?? null,
+            type: r.relations?.[0]?.canonical_predicate ?? null,
+        }));
+        return structuredResult(lines.join("\n"), {
+            seed_id: res.seed_source_id || id,
+            member_count: members.length,
+            max_depth_reached: hops,
+            truncated: Boolean(res.is_truncated),
+            relations: edges,
+            structural_link_count: (res.auxiliary_relations ?? []).length,
+            structural_truncated: Boolean(res.auxiliary_truncated),
+            members: ordered.map((m) => ({
+                id: m.source_id,
+                title: m.title ?? null,
+                depth: m.depth,
+                discovered_via: m.discovered_via ?? null,
+                discovered_relation: m.discovered_relation ?? null,
+                app_provider: m.app_provider ?? null,
+                app_kind: m.app_kind ?? null,
+            })),
+        });
+    }
     async function runInspect(args, signal) {
         logger.debug(`${TOOL_NAMES.INSPECT}: ${args.source_id}`);
         const res = await hydra.context.inspect({
             id: args.source_id,
             mode: args.mode ?? "content",
             expirySeconds: args.expiry_seconds,
+            acl: args.acl,
             database: args.database,
             collection: args.collection,
         }, { signal });
@@ -898,6 +1012,34 @@ graphOverride) {
         }
         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.
@@ -907,9 +1049,33 @@ graphOverride) {
      * 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 = args.database?.trim() || graphConfig.database;
-        const collection = args.collection?.trim() || graphConfig.collection;
+        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.");
@@ -990,7 +1156,7 @@ graphOverride) {
         });
     }
     async function runGraphCollections(args, signal) {
-        const database = args.database?.trim() || graphConfig.database;
+        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.");
@@ -1005,7 +1171,7 @@ graphOverride) {
             collections.map((name) => `  - ${name}`).join("\n"), { database, collections, count: collections.length });
     }
     async function runGraphAdmin(args, signal) {
-        const database = args.database?.trim() || graphConfig.database;
+        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.");
@@ -1022,6 +1188,13 @@ graphOverride) {
                 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
@@ -1031,6 +1204,21 @@ graphOverride) {
                 "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(", ")}.` : "";
@@ -1151,6 +1339,25 @@ graphOverride) {
             .max(5)
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.num_related_chunks),
+        recency_bias: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.recency_bias),
+        query_apps: z
+            .boolean()
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.query_apps),
+        collections: z
+            .array(z.string().min(1))
+            .min(1)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.collections),
+        acl: z
+            .array(z.string())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.QUERY].params.acl),
         ...scopeSchema,
     };
     const storeSchema = {
@@ -1273,6 +1480,10 @@ graphOverride) {
             .max(100)
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST].params.page_size),
+        acl: z
+            .array(z.string())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST].params.acl),
         ...scopeSchema,
     };
     const listSourcesSchema = {
@@ -1280,9 +1491,43 @@ graphOverride) {
             .array(z.string())
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST_SOURCES].params.source_ids),
+        acl: z
+            .array(z.string())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST].params.acl),
         ...scopeSchema,
     };
     const listMemoriesSchema = {
+        acl: z
+            .array(z.string())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.LIST].params.acl),
+        ...scopeSchema,
+    };
+    const subgraphSchema = {
+        id: z.string().min(1).describe(TOOL_DESCRIPTIONS[TOOL_NAMES.SUBGRAPH].params.id),
+        kind: z
+            .enum(["memory", "knowledge"])
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.SUBGRAPH].params.kind),
+        depth: z
+            .number()
+            .int()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.SUBGRAPH].params.depth),
+        max_sources: z
+            .number()
+            .int()
+            .min(1)
+            .max(1000)
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.SUBGRAPH].params.max_sources),
+        acl: z
+            .array(z.string())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.SUBGRAPH].params.acl),
         ...scopeSchema,
     };
     const inspectSchema = {
@@ -1321,6 +1566,10 @@ graphOverride) {
             .min(1)
             .optional()
             .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INSPECT].params.expiry_seconds),
+        acl: z
+            .array(z.string())
+            .optional()
+            .describe(TOOL_DESCRIPTIONS[TOOL_NAMES.INSPECT].params.acl),
         ...scopeSchema,
     };
     const deleteSchema = {
@@ -1575,6 +1824,7 @@ graphOverride) {
                 source_ids: ids,
                 page: a.page,
                 page_size: a.page_size,
+                acl: a.acl,
                 database: a.database,
                 collection: a.collection,
             }, extra?.signal);
@@ -1583,13 +1833,21 @@ graphOverride) {
             source_ids: ids,
             page: a.page,
             page_size: a.page_size,
+            acl: a.acl,
             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.SUBGRAPH, subgraphSchema, (args, extra) => runSubgraph(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