@hydradb/mcp 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -5,6 +5,163 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.2.2] - 2026-08-19
+
+### Added — per-call database and collection scope overrides
+
+Every context tool (`hydradb_query`, `hydradb_ingest`, `hydradb_list`,
+`hydradb_inspect`, `hydradb_delete`, `hydradb_status`, and deprecated aliases)
+now accepts optional `database` and `collection` arguments directly in its payload.
+This allows multi-tenant SaaS agents to dynamically switch tenant/collection scopes
+per request within a single persistent MCP session, while falling back to the session
+defaults when omitted.
+
+### Added — remote HTTP transport (hosted server)
+
+The server can now run as a long-lived **HTTP endpoint** that many clients reach
+at one URL (`https://mcp.hydradb.com`), alongside the existing stdio (`npx`) binary.
+This is what a hosted deployment runs, and what `npm run start:http` or the new
+Docker image runs locally — nothing to install per user.
+
+The tool surface is unchanged: the HTTP server builds the exact same server as
+stdio via `createHydraDBServer`. Only connection and auth are new.
+
+- **Root endpoint and backward-compatible alias.** The server serves the MCP
+  Streamable HTTP transport directly on `/` and `/mcp`.
+- **Per-request, multi-tenant credentials.** A hosted process has no single
+  ambient account, so each request selects its tenant with headers —
+  `Authorization: Bearer <api-key>` (or `X-HydraDB-Api-Key`) and
+  `X-HydraDB-Database`, with optional `X-HydraDB-Collection` and
+  `X-HydraDB-Graph-*`. A request that authenticates nobody is refused (`401`);
+  one that names no database is `400`. A single-tenant self-host may instead set
+  `HYDRADB_API_KEY`/`HYDRADB_DATABASE` in the environment and clients send no
+  credentials — the header path falls back to it.
+- **Safe-by-default network posture.** Binds loopback unless `BIND_ADDRESS` is
+  set; a `Host` allowlist (`ALLOWED_HOSTS`, loopback always) answers stray
+  authorities with `421`; CORS is closed until `ALLOWED_ORIGINS` lists an
+  origin. `Base URL`/timeout/retries stay operator-only env settings and are
+  never read from a request header.
+- New: `src/http.ts` (Express app + lifecycle), `src/http-config.ts`
+  (operator + per-request config resolution), `Dockerfile`, `.dockerignore`,
+  `npm run start:http` / `dev:http`, and a `hydradb-mcp-http` bin. Runtime deps
+  `express` and `cors` were added.
+
+### Added — graph (BYOG) tools
+
+Hydra DB's **graph database** offering is now reachable from the MCP. Previously
+this server exposed only the application offering (memory and knowledge); the
+property graphs users model and own end to end, queried in Cypher, had no client
+surface at all despite being [documented](https://docs.hydradb.com/essentials/v2/graph-collections-byog)
+and live.
+
+Three new tools, all additive — nothing about the existing six changed:
+
+| Tool | Annotation | What it does |
+|---|---|---|
+| `hydradb_graph_query` | `destructiveHint` | Cypher, reads and writes alike |
+| `hydradb_graph_collections` | `readOnlyHint` | List the graphs in a graph database |
+| `hydradb_graph_admin` | `destructiveHint` | Create a graph database; drop a collection or database |
+
+This covers [Neo4j's MCP server](https://github.com/neo4j-contrib/mcp-neo4j)
+`read_neo4j_cypher` and `write_neo4j_cypher`, plus the graph database lifecycle
+its Aura server covers. Two of its capabilities are deliberately **not**
+reproduced:
+
+**One Cypher tool, not a read/write pair.** Neo4j splits `read_neo4j_cypher`
+from `write_neo4j_cypher` so a host can auto-approve one and gate the other.
+That split is only sound if the read/write classifier is right on every query,
+and any classifier over Cypher text is a heuristic — Neo4j's own is a substring
+scan that refuses `MATCH (p:Person) WHERE p.name = "CREATE something" RETURN
+p.name`, a query HydraDB accepts and that mutates nothing. Rather than ship a
+tool whose contract ("this one never writes") rests on a heuristic, there is one
+tool, annotated destructive, and the host gates the whole graph surface. No
+classifier ships at all.
+
+**No schema tool.** Neo4j's `get_neo4j_schema` runs `CALL apoc.meta.schema()`,
+which HydraDB rejects outright. A derived equivalent is not part of the product,
+so none ships. Callers discover a collection's structure the same way they query
+it — `MATCH (n) UNWIND labels(n) AS l RETURN l, count(*) AS c ORDER BY l` — and
+the tool description says so.
+
+Also worth recording: **`EXPLAIN` is not a preview.** `EXPLAIN MATCH (p:Person)
+RETURN p` returns live rows rather than a plan, so it is documented as something
+not to reach for.
+
+The 256 KiB body cap IS enforced before upload, since the remote `413` arrives
+only after the whole oversized batch has been sent — that is a transport fact
+the client owns, not a rule about what Cypher means.
+
+Registered by default, with one switch: `HYDRADB_MCP_GRAPH_TOOLS=0` withholds
+all three, for memory-only users who do not want the extra tool definitions in
+every conversation.
+
+**The client does not inspect your Cypher.** No read/write classification, no
+read-only mode, no local pre-rejection of unsupported constructs. All of those
+would put a second, worse implementation of the server's rules inside a client,
+able only to agree with the server or to be wrong — and being wrong means
+refusing a query HydraDB would have run. The server rejects unsupported
+constructs before executing anything (verified: a query mixing `CREATE` with a
+procedure call leaves the node count unchanged) and its messages are more
+specific than the ones this server used to produce. Queries are sent verbatim.
+
+Withholding the tools is the only lockdown offered, because it is the only one
+that is actually a guarantee.
+
+New configuration: `HYDRADB_GRAPH_DATABASE` (falls back to `HYDRADB_DATABASE`)
+and `HYDRADB_GRAPH_COLLECTION` (defaults to `default`). A graph database is a
+different namespace from the memory database, so every graph tool also accepts
+`database` and `collection` per call.
+
+### Internal
+
+- `HydraDB.graph` is a hand-rolled HTTP path, not an SDK call: `@hydradb/sdk`
+  at the pinned 2.1.2 has no `byog` resource, so the endpoints are unreachable
+  through it. It sits behind the same wrapper surface, unwraps the same envelope
+  by shape and raises the same `HydraWrapperError`, so callers cannot tell which
+  methods go through the SDK. When the SDK grows a `byog` resource, that one file
+  is replaced and nothing above it changes. The exact SDK pin is unaffected —
+  there is no generated name to be insulated from yet.
+- `responseError()` added to the wrapper's error module so failures from the
+  non-SDK path are formatted through the same code as SDK failures, keeping the
+  error code, the server's message and the request id.
+## [1.2.1] - 2026-08-17
+
+### Fixed
+
+Two parameters added in 1.2.0 could not succeed under any input. Both failed as a
+remote 400 on a call the caller had already committed to, so the whole tool call
+was lost to a value that had a working form.
+
+- **`operator` on `hydradb_query` failed on every call that set it.** Hydra DB
+  honours an operator only when the request also asks for keyword retrieval, and
+  this server never sent `query_by` — so the parameter answered
+  `400 INVALID_INPUT: operator is only valid with query_by=text` whatever it was
+  set to. An operator now carries the retrieval method it requires, and the one
+  self-contradicting combination (an operator with explicitly hybrid retrieval)
+  is refused here rather than sent out to fail. The cost of that pairing is now
+  in the parameter description instead of being discoverable by 400: setting an
+  operator turns off the hybrid semantic search this tool otherwise runs, so the
+  query matches literal words rather than the concept. The description also stops
+  calling `or` the default, which invited callers to pass it redundantly and lose
+  semantic matching for nothing. The hybrid-only `alpha` weighting is no longer
+  sent on those queries, where there are no two retrieval lanes to weigh.
+- **`observation_date` on `hydradb_ingest` documented a format the API
+  rejects.** The description asked for an RFC3339 date, which is a date-*time*: a
+  model that followed it sent `2026-08-17T00:00:00Z` and lost the entire ingest to
+  `400 INVALID_INPUT: … is not a valid ISO-8601 date (want YYYY-MM-DD)`, on a
+  value that would have worked as `2026-08-17`. The description and the README now
+  state `YYYY-MM-DD` with a worked example, and the schema carries the pattern so
+  the constraint reaches the model choosing the value. A date-time is the form a
+  model reaches for when writing a date in JSON, so it is accepted and kept as its
+  date part — trimmed textually, which keeps the day the caller wrote where
+  converting to UTC would move `2026-08-17T23:00:00-08:00` to the 18th and record
+  a date nobody named. Anything that is not a date is rejected before the request
+  goes out. The deprecated `hydra_db_store` alias held verbatim copies of this
+  blurb and the `metadata` one; both now reference the shared text, which is how
+  the fix stays fixed.
+
 ## [1.2.0] - 2026-08-14
 
 ### ⚠️ Migration required if you call the old tool names
@@ -162,6 +319,7 @@ so neither the caller nor the user learned anything had gone wrong.
 - Canonical HydraDB tool vocabulary (`hydradb_*`), with the previous `hydra_db_*`
   names kept as deprecated aliases.
 
+[1.2.1]: https://github.com/hydra-db/hydradb-mcp/releases/tag/v1.2.1
 [1.2.0]: https://github.com/hydra-db/hydradb-mcp/releases/tag/v1.2.0
 [1.1.1]: https://github.com/hydra-db/hydradb-mcp/releases/tag/v1.1.1
 [1.1.0]: https://github.com/hydra-db/hydradb-mcp/releases/tag/v1.1.0

package/README.md

@@ -2,6 +2,11 @@
 
 MCP (Model Context Protocol) server for [Hydra DB](https://hydradb.com), the state-of-the-art agentic memory. Provides tools for storing, recalling, and managing memories with knowledge-graph enriched context.
 
+Run it two ways, same tools either way:
+
+- **Local (stdio)** — the `npx @hydradb/mcp` binary each client spawns. No server to operate; credentials live in the client's config. This is the default and everything below the [Configuration](#configuration) section documents it.
+- **Remote (HTTP)** — one hosted process behind a URL like `https://mcp.hydradb.com` that many clients point at, with nothing to install. See [**Remote / hosted server**](#remote--hosted-server).
+
 ## Available Tools
 
 | Tool | What it does |
@@ -16,6 +21,44 @@ MCP (Model Context Protocol) server for [Hydra DB](https://hydradb.com), the sta
 Ids flow between these: `hydradb_query` and `hydradb_list` emit them;
 `hydradb_inspect`, `hydradb_delete` and `hydradb_status` accept them.
 
+### Graph tools (Cypher)
+
+Hydra DB also runs **property graphs you model and own end to end**, queried in [Cypher](https://docs.hydradb.com/essentials/v2/graph-collections-byog). This is a different product surface from the memory and knowledge above, and nothing crosses between them: `hydradb_query` cannot see graph data, and `hydradb_graph_query` cannot see memories.
+
+| Tool | What it does |
+|---|---|
+| `hydradb_graph_query` | Run Cypher — reads **and** writes |
+| `hydradb_graph_collections` | List the graphs in a graph database |
+| `hydradb_graph_admin` | Create a graph database; drop a collection or a database |
+
+`hydradb_graph_query` is annotated `destructiveHint`, because it runs arbitrary Cypher and `DELETE` is as reachable through it as `MATCH`. There is deliberately **no** separate read-only Cypher tool and **no read-only mode**: both would mean classifying Cypher text client-side to decide what to refuse, which is a heuristic — a promise the server can keep and a client cannot. This server does not inspect your query at all; it sends it and reports what HydraDB says. To lock the graph surface down, withhold the tools (below) — that is a real guarantee.
+
+```jsonc
+// Everyone Alice knows within four hops
+{"query": "MATCH (a:Person {name:$n})-[:KNOWS*1..4]->(r) RETURN DISTINCT r.name AS name",
+ "params": {"n": "Alice"}}
+
+// Bulk load, re-runnable after a failure
+{"query": "UNWIND $rows AS row MERGE (p:Person {ext_id: row.ext_id}) SET p += row",
+ "params": {"rows": [{"ext_id": "a", "name": "Alice"}]}}
+```
+
+**Differences from Neo4j** worth knowing before you write Cypher. Each is rejected *before* execution, so a rejected query changes nothing and fails identically on retry:
+
+- Procedure calls (`CALL db.*`, `CALL apoc.*`) are rejected **by the server**, before it executes anything. `CALL { ... }` subqueries are fine. There is no schema tool and no `apoc.meta.schema()`; to learn a collection's structure, query it — `MATCH (n) UNWIND labels(n) AS l RETURN l, count(*) AS c ORDER BY l`.
+- `LOAD CSV` is rejected — pass data through `params` instead.
+- Existence checks are bare pattern predicates (`WHERE (p)-[:KNOWS]->()`); `EXISTS { ... }` and `exists()` are not accepted.
+- `shortestPath` belongs in `RETURN`/`WITH`, not `MATCH p = ...`, and must be directed.
+- `EXPLAIN`/`PROFILE` **execute** the query rather than planning it — do not use them to preview one.
+
+Collections auto-create on first write, so there is no create-collection call. Requests are capped at 256 KiB (enforced locally, before upload) and large result sets are truncated server-side — paginate with `ORDER BY ... SKIP $offset LIMIT $limit`.
+
+To turn the graph tools off entirely:
+
+```
+HYDRADB_MCP_GRAPH_TOOLS=0   # withhold all three
+```
+
 ### Deprecated aliases
 
 The previous `hydra_db_*` tool names are **no longer registered by default** as
@@ -46,7 +89,7 @@ chunks with their source id, a relevance score, and knowledge-graph context.
 | `mode` | string | No | `fast`, `thinking` (default), or `auto` |
 | `detail` | string | No | `compact` (default) trims each chunk; `full` returns them whole |
 | `graph_context` | boolean | No | Include knowledge-graph relations (default: true) |
-| `operator` | string | No | `or` (default), `and`, or `phrase` for exact strings |
+| `operator` | string | No | `or`, `and`, or `phrase`. Switches the query to keyword retrieval (`query_by=text`), which is the only mode Hydra DB accepts an operator on — semantic matching is off for that query. Unset (the default) is hybrid semantic search |
 | `source_ids` | array | No | Restrict the search to these sources |
 | `metadata_filters` | object | No | Exact-match filters over stored metadata |
 | `num_related_chunks` | number | No | Adjacent chunks to attach per match (0-5, default: 0) |
@@ -67,7 +110,7 @@ or `turns`.
 | `infer` | boolean | No | Extract insights and graph entities (default: true) |
 | `is_markdown` | boolean | No | Chunk on markdown structure (default: false) |
 | `metadata` | object | No | Key/value metadata, matchable later via `metadata_filters` |
-| `observation_date` | string | No | When the fact was true (RFC3339), vs when it was stored |
+| `observation_date` | string | No | When the fact was true, as `YYYY-MM-DD` (e.g. `2026-07-04`), vs when it was stored |
 | `user_name` | string | No | What to call the user, used with `turns` (default: `User`) |
 
 \* Passing both is an error; passing neither is an error.
@@ -145,6 +188,14 @@ Checks whether ingested sources have finished indexing.
 | `HYDRADB_TIMEOUT_SECONDS` | Per-attempt request timeout     | `30`                      |
 | `HYDRADB_MAX_RETRIES` | Retries per request (0 disables)    | `2`                       |
 | `HYDRADB_MCP_LEGACY_TOOLS` | Register the deprecated `hydra_db_*` tools | *off* |
+| `HYDRADB_GRAPH_DATABASE` | Default graph database for the Cypher tools | `HYDRADB_DATABASE` |
+| `HYDRADB_GRAPH_COLLECTION` | Default graph collection | `default` |
+| `HYDRADB_MCP_GRAPH_TOOLS` | Register the graph tools (`0` withholds them) | *on* |
+
+A graph database is a **different namespace** from the memory database: the same
+name can exist as both, and Cypher aimed at the wrong one reads an empty graph
+rather than failing. Every graph tool also takes `database` and `collection`
+per call, overriding these defaults.
 
 The legacy `HYDRA_DB_*` names — `HYDRA_DB_API_KEY`, `HYDRA_DB_TENANT_ID`,
 `HYDRA_DB_SUB_TENANT_ID`, `HYDRA_DB_BASE_URL`, `HYDRA_DB_LOG_LEVEL` — remain
@@ -230,6 +281,118 @@ To partition data, set the `HYDRADB_COLLECTION` environment variable:
 }
 ```
 
+## Remote / hosted server
+
+Everything above spawns the server locally over stdio. The same server also runs
+as a long-lived **HTTP endpoint** that many clients reach at one URL — nothing to
+install or update per user. This is what powers a hosted deployment like
+`https://mcp.hydradb.com`, and what you run yourself with `npm run start:http`
+or the Docker image.
+
+The tool surface is identical; only how a client connects and authenticates
+changes.
+
+### Point a client at a URL
+
+MCP clients that support a remote (`streamable-http`) server take a URL and
+headers instead of a command:
+
+```jsonc
+{
+  "mcpServers": {
+    "hydradb": {
+      "url": "https://mcp.hydradb.com",
+      "headers": {
+        "Authorization": "Bearer YOUR_HYDRADB_API_KEY",
+        "X-HydraDB-Database": "your-database"
+      }
+    }
+  }
+}
+```
+
+Every request carries its own credentials, so one hosted process serves any
+number of independent users. The headers a request may send:
+
+| Header | Maps to | Required |
+| --- | --- | --- |
+| `Authorization: Bearer <key>` | Hydra DB API key (`X-HydraDB-Api-Key` also accepted) | Yes\* |
+| `X-HydraDB-Database` | Default database (tenant scope) | Yes\* |
+| `X-HydraDB-Collection` | Default collection (sub-tenant); defaults to `hydra-db-mcp` | No |
+| `X-HydraDB-Graph-Database` | Default graph database for the Cypher tools; defaults to the request's database | No |
+| `X-HydraDB-Graph-Collection` | Default graph collection; defaults to `default` | No |
+
+\* Unless the server was started with `HYDRADB_API_KEY` / `HYDRADB_DATABASE` in
+its environment (single-tenant self-host, below), in which case a request may
+omit them and fall back to the server's own credentials. A request that supplies
+neither a header nor a server-side default is refused: `401` with no key, `400`
+with a key but no database.
+
+Every tool additionally accepts optional `database` and `collection` parameters
+directly in its arguments (e.g. `hydradb_query` with `{"query": "...", "database": "tenant_b"}`),
+allowing multi-tenant agents to switch tenant scope per tool call while falling
+back to the session defaults when omitted.
+
+`Base URL`, request timeout and retry count are
+**operator** settings read from the server's environment and are never taken
+from a request header.
+
+### Run the HTTP server
+
+**Node:**
+
+```bash
+npm ci && npm run build
+# Single-tenant: the server holds one account; clients send no credentials.
+HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database npm run start:http
+# Multi-tenant: no account in the env; every client sends its own headers.
+BIND_ADDRESS=0.0.0.0 ALLOWED_HOSTS=mcp.hydradb.com npm run start:http
+```
+
+**Docker:**
+
+```bash
+docker build -t hydradb-mcp .
+# Single-tenant
+docker run -p 8080:8080 -e HYDRADB_API_KEY=your-key -e HYDRADB_DATABASE=your-database hydradb-mcp
+# Multi-tenant (clients authenticate per request)
+docker run -p 8080:8080 -e ALLOWED_HOSTS=mcp.hydradb.com hydradb-mcp
+```
+
+The primary MCP endpoint is `/` (with `/mcp` supported as an alias); `GET /health` is an unauthenticated liveness probe.
+The image binds `0.0.0.0` inside the container (the host controls exposure with
+`-p`) and runs as an unprivileged user.
+
+### Server environment variables
+
+These configure the HTTP process itself (the stdio server ignores them). All
+the `HYDRADB_*` variables from [Environment Variables](#environment-variables)
+also apply — as the single-tenant default and as operator settings.
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `PORT` | Port to listen on | `8080` |
+| `BIND_ADDRESS` | Interface to bind (`0.0.0.0` to accept off-host) | `127.0.0.1` |
+| `ALLOWED_HOSTS` | Extra `Host` headers to accept (comma-separated); loopback always allowed | *(loopback only)* |
+| `ALLOWED_ORIGINS` | CORS origins for browser clients (comma-separated; `*` allows any) | *(none)* |
+| `TRUST_PROXY` | Express `trust proxy` when behind a reverse proxy: a hop count, `true`, or a subnet preset (`loopback`) | *off* |
+
+### Security
+
+The defaults are safe for local use and must be widened deliberately for a
+public deployment — see [SECURITY.md](SECURITY.md):
+
+- **Bind loopback by default.** `BIND_ADDRESS` stays `127.0.0.1` until you set
+  otherwise; `0.0.0.0` exposes the server on every interface and logs a warning.
+- **Host allowlist.** Requests whose `Host` is not loopback or in `ALLOWED_HOSTS`
+  get `421 Misdirected Request` — a DNS-rebinding defence. Add your public
+  hostname when binding publicly.
+- **CORS is closed by default.** No cross-origin browser request is accepted
+  until you list its origin in `ALLOWED_ORIGINS`. Non-browser clients (no
+  `Origin` header) are unaffected.
+- **Terminate TLS in front.** Run the server behind a reverse proxy / load
+  balancer that handles HTTPS; do not expose plain HTTP to the internet.
+
 ## How It Works
 
 The server talks to Hydra DB through the generated [`@hydradb/sdk`](https://www.npmjs.com/package/@hydradb/sdk)
@@ -257,6 +420,13 @@ For development with auto-reload:
 HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database npm run dev
 ```
 
+To run the HTTP transport locally (see [Remote / hosted server](#remote--hosted-server)):
+
+```bash
+HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database npm run dev:http
+# then: curl localhost:8080/health
+```
+
 ## Testing
 
 ```bash

package/dist/config.d.ts

@@ -14,9 +14,31 @@ export interface HydraDBConfig {
     baseUrl?: string;
     timeoutSeconds?: number;
     maxRetries?: number;
+    graph: GraphConfig;
+}
+/**
+ * Scope and gating for the BYOG graph tools.
+ *
+ * A graph database is a DIFFERENT namespace from the memory database: the same
+ * name can exist as both, and a Cypher query aimed at the wrong one silently
+ * reads an empty graph rather than failing. So the graph scope is configured
+ * separately, and every graph tool also takes a per-call override.
+ */
+export interface GraphConfig {
+    /** Whether the graph tools are registered at all. */
+    enabled: boolean;
+    /**
+     * Default graph database. Falls back to HYDRADB_DATABASE — convenient when
+     * one name is used for both, and harmless otherwise because the tools accept
+     * `database` per call.
+     */
+    database: string;
+    /** Default graph collection. */
+    collection: string;
 }
 export type EnvSource = Record<string, string | undefined>;
 export type WarnFn = (message: string) => void;
+export declare const DEFAULT_COLLECTION = "hydra-db-mcp";
 /**
  * Read a canonical `HYDRADB_*` variable, falling back to the legacy `HYDRA_DB_*`
  * spelling with a once-per-process warning. Exported so every variable this
@@ -26,3 +48,21 @@ export type WarnFn = (message: string) => void;
  */
 export declare function readEnv(env: EnvSource, canonical: string, deprecated: string, warn?: WarnFn): string | undefined;
 export declare function resolveConfig(env?: EnvSource, warn?: WarnFn): HydraDBConfig;
+/**
+ * Graph scope and gating, resolved on its own.
+ *
+ * Separate from `resolveConfig` because it must be resolvable WITHOUT an API key
+ * or a memory database: tests construct a server around an injected client and
+ * never set those, and making the graph tools depend on them would mean the
+ * graph surface could not be exercised without a full credential set.
+ */
+export declare function resolveGraphConfig(env?: EnvSource, fallbackDatabase?: string): GraphConfig;
+/**
+ * Numeric overrides are ignored rather than fatal when malformed.
+ *
+ * A typo'd timeout should not stop the server from starting — falling back to
+ * the built-in default keeps it running, and the alternative (exit 1 on a
+ * cosmetic env var) is worse than the misconfiguration.
+ */
+export declare function positiveInt(raw: string | undefined): number | undefined;
+export declare function nonNegativeInt(raw: string | undefined): number | undefined;

package/dist/config.js

@@ -7,7 +7,26 @@
  * deprecated alias emits exactly one stderr warning per process naming the
  * canonical replacement.
  */
-const DEFAULT_COLLECTION = "hydra-db-mcp";
+const DEFAULT_GRAPH_COLLECTION = "default";
+/**
+ * Env flags accept the usual spellings, not just `1`.
+ *
+ * Someone writing `HYDRADB_MCP_GRAPH_TOOLS=false` means it, and silently
+ * ignoring that would register tools an operator believed they had withheld.
+ * An unrecognised value falls back rather than throwing, so a typo cannot stop
+ * the server starting.
+ */
+function flag(raw, fallback) {
+    if (raw == null || raw.trim() === "")
+        return fallback;
+    const value = raw.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(value))
+        return true;
+    if (["0", "false", "no", "off"].includes(value))
+        return false;
+    return fallback;
+}
+export const DEFAULT_COLLECTION = "hydra-db-mcp";
 // Process-lifetime dedupe so each deprecated alias warns at most once.
 const warnedOnce = new Set();
 function defaultWarn(message) {
@@ -61,6 +80,24 @@ export function resolveConfig(env = process.env, warn = defaultWarn) {
         baseUrl,
         ...(timeoutSeconds != null ? { timeoutSeconds } : {}),
         ...(maxRetries != null ? { maxRetries } : {}),
+        graph: resolveGraphConfig(env, database),
+    };
+}
+/**
+ * Graph scope and gating, resolved on its own.
+ *
+ * Separate from `resolveConfig` because it must be resolvable WITHOUT an API key
+ * or a memory database: tests construct a server around an injected client and
+ * never set those, and making the graph tools depend on them would mean the
+ * graph surface could not be exercised without a full credential set.
+ */
+export function resolveGraphConfig(env = process.env, fallbackDatabase = "") {
+    return {
+        enabled: flag(env.HYDRADB_MCP_GRAPH_TOOLS, true),
+        // Not `readEnv` — these are new names with no legacy spelling to alias,
+        // and inventing a deprecated one would be noise.
+        database: env.HYDRADB_GRAPH_DATABASE?.trim() || fallbackDatabase,
+        collection: env.HYDRADB_GRAPH_COLLECTION?.trim() || DEFAULT_GRAPH_COLLECTION,
     };
 }
 /**
@@ -70,11 +107,11 @@ export function resolveConfig(env = process.env, warn = defaultWarn) {
  * the built-in default keeps it running, and the alternative (exit 1 on a
  * cosmetic env var) is worse than the misconfiguration.
  */
-function positiveInt(raw) {
+export function positiveInt(raw) {
     const value = Number(raw);
     return raw != null && Number.isInteger(value) && value > 0 ? value : undefined;
 }
-function nonNegativeInt(raw) {
+export function nonNegativeInt(raw) {
     const value = Number(raw);
     return raw != null && Number.isInteger(value) && value >= 0 ? value : undefined;
 }

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/cypher.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Rendering and local limits for the BYOG (Bring Your Own Graph) tool.
+ *
+ * Deliberately contains NO Cypher analysis. An earlier version lexed the query
+ * to classify reads vs writes and to pre-reject constructs the server refuses,
+ * which meant a second, worse implementation of the server's own rules living
+ * in a client: it could only ever agree with the server or be wrong, and being
+ * wrong meant refusing a query HydraDB would have run.
+ *
+ * The server is the authority on what Cypher is valid and permitted. It rejects
+ * unsupported constructs before executing anything — verified: a query mixing
+ * CREATE with a procedure call leaves the node count unchanged — and its
+ * messages are more specific than the ones this file used to produce.
+ *
+ * What is left is the work a client genuinely owns: turning the server's row
+ * objects into something readable, and the two limits that are cheaper to check
+ * here than to discover from a remote error.
+ */
+/**
+ * The documented request-body ceiling for `POST /byog/query`.
+ *
+ * Enforced before the request goes out. The server answers an oversize body
+ * with 413 — but only after the whole thing has been uploaded, which on a bulk
+ * load is the slowest possible way to learn the batch was too big.
+ */
+export declare const MAX_BODY_BYTES: number;
+/** Collection names the server accepts. Rejecting locally names the rule. */
+export declare const COLLECTION_PATTERN: RegExp;
+type Row = Record<string, unknown>;
+/**
+ * One returned value, rendered the way a graph user reads it.
+ *
+ * A node comes back as a flat object mixing its properties with `id` and
+ * `labels`; dumping that as raw JSON makes the caller do the separating. This
+ * renders `(:Person {name: "Alice"})` instead, which is both shorter and the
+ * notation the query was written in.
+ */
+export declare function renderValue(value: unknown): string;
+/**
+ * Rows as a table, bounded.
+ *
+ * A traversal can return far more than the caller can use, and unlike the
+ * memory tools there is no server-side relevance ranking to lean on — the query
+ * asked for exactly this. So the ceiling is on the rendering, and what was
+ * dropped is stated rather than silently cut.
+ */
+export declare function renderRows(rows: Row[], opts?: {
+    maxRows?: number;
+    maxChars?: number;
+}): string;
+export {};