@hydradb/mcp 1.0.0 → 1.1.1

package/dist/hydra/envelope.js

@@ -0,0 +1,28 @@
+/**
+ * HandlerEnvelope unwrapping.
+ *
+ * Most `@hydradb/sdk` methods resolve to a `HandlerEnvelope{ data, success, meta,
+ * error }` and we want the inner `data`. But not every method is enveloped
+ * (`databases.updateMetadataSchema` and most `connectors.*` return bare
+ * objects), so we unwrap by *checking the envelope shape* rather than assuming
+ * it: a value is an envelope only if it carries a top-level `data` property
+ * alongside one of the envelope siblings (`success` / `meta` / `error`).
+ *
+ * Payload types (e.g. `FetchV2SourceFetchResponse`) may themselves carry a
+ * `success` field, but never a top-level `data`, so they are correctly left
+ * untouched when they arrive already unwrapped.
+ */
+function isEnvelope(value) {
+    if (value == null || typeof value !== "object")
+        return false;
+    if (!("data" in value))
+        return false;
+    return "success" in value || "meta" in value || "error" in value;
+}
+export function unwrap(value) {
+    if (isEnvelope(value)) {
+        return value.data;
+    }
+    return value;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/hydra/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/hydra/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,SAAS,UAAU,CAAC,KAAc;IACjC,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC7D,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,OAAO,SAAS,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,OAAO,IAAI,KAAK,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,MAAM,CAAI,KAAc;IACvC,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,IAAS,CAAC;IACxB,CAAC;IACD,OAAO,KAAU,CAAC;AACnB,CAAC"}

package/dist/hydra/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error translation for the HydraDB wrapper.
+ *
+ * The wrapper is the firewall between the generated `@hydradb/sdk` and the host
+ * (this MCP server). SDK calls throw `HydraDBError` subclasses; we catch those
+ * and re-throw a `HydraWrapperError` whose `message` reproduces the exact
+ * template the hand-rolled v1 client used:
+ *
+ *     Hydra DB ${path} → ${status}: ${body}
+ *
+ * The MCP runtime surfaces only `error.message` to the model (see
+ * `createToolError` in @modelcontextprotocol/sdk), so keeping this template
+ * byte-identical keeps model-visible error behaviour unchanged across the
+ * v1 → SDK migration. The `path`/`status`/`body` values naturally reflect the
+ * v2 endpoint now being called; changing the template text itself is a
+ * separate, later, deliberate step.
+ */
+export declare class HydraWrapperError extends Error {
+    /** Logical endpoint path the failing call targeted (e.g. `/query`). */
+    readonly path: string;
+    /** HTTP status code, when the failure carried one. */
+    readonly status?: number;
+    /** Parsed error body from the SDK, preserved for programmatic handling. */
+    readonly body?: unknown;
+    /** The original SDK error, preserved as the cause. */
+    readonly cause?: unknown;
+    constructor(message: string, path: string, opts?: {
+        status?: number;
+        body?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * Translate any error thrown by an SDK call into a `HydraWrapperError` carrying
+ * the byte-identical `Hydra DB ${path} → ${status}: ${body}` message.
+ */
+export declare function translateError(path: string, err: unknown): HydraWrapperError;

package/dist/hydra/errors.js

@@ -0,0 +1,58 @@
+/**
+ * Error translation for the HydraDB wrapper.
+ *
+ * The wrapper is the firewall between the generated `@hydradb/sdk` and the host
+ * (this MCP server). SDK calls throw `HydraDBError` subclasses; we catch those
+ * and re-throw a `HydraWrapperError` whose `message` reproduces the exact
+ * template the hand-rolled v1 client used:
+ *
+ *     Hydra DB ${path} → ${status}: ${body}
+ *
+ * The MCP runtime surfaces only `error.message` to the model (see
+ * `createToolError` in @modelcontextprotocol/sdk), so keeping this template
+ * byte-identical keeps model-visible error behaviour unchanged across the
+ * v1 → SDK migration. The `path`/`status`/`body` values naturally reflect the
+ * v2 endpoint now being called; changing the template text itself is a
+ * separate, later, deliberate step.
+ */
+import { HydraDBError } from "@hydradb/sdk";
+export class HydraWrapperError extends Error {
+    constructor(message, path, opts) {
+        super(message);
+        this.name = "HydraWrapperError";
+        this.path = path;
+        this.status = opts?.status;
+        this.body = opts?.body;
+        this.cause = opts?.cause;
+        Object.setPrototypeOf(this, HydraWrapperError.prototype);
+    }
+}
+function bodyToString(body) {
+    if (body == null)
+        return "";
+    if (typeof body === "string")
+        return body;
+    try {
+        return JSON.stringify(body);
+    }
+    catch {
+        return String(body);
+    }
+}
+/**
+ * Translate any error thrown by an SDK call into a `HydraWrapperError` carrying
+ * the byte-identical `Hydra DB ${path} → ${status}: ${body}` message.
+ */
+export function translateError(path, err) {
+    if (err instanceof HydraDBError) {
+        const status = err.statusCode;
+        const statusText = status != null ? String(status) : "ERR";
+        return new HydraWrapperError(`Hydra DB ${path} → ${statusText}: ${bodyToString(err.body)}`, path, { status, body: err.body, cause: err });
+    }
+    // Non-SDK failure (network error, aborted request, unexpected throw).
+    const message = err instanceof Error ? err.message : String(err);
+    return new HydraWrapperError(`Hydra DB ${path} → ERR: ${message}`, path, {
+        cause: err,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/hydra/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/hydra/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAU3C,YACC,OAAe,EACf,IAAY,EACZ,IAA2D;QAE3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC;QACzB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC1D,CAAC;CACD;AAED,SAAS,YAAY,CAAC,IAAa;IAClC,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,GAAY;IACxD,IAAI,GAAG,YAAY,YAAY,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC;QAC9B,MAAM,UAAU,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAC3D,OAAO,IAAI,iBAAiB,CAC3B,YAAY,IAAI,MAAM,UAAU,KAAK,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAC7D,IAAI,EACJ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CACtC,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,IAAI,iBAAiB,CAAC,YAAY,IAAI,WAAW,OAAO,EAAE,EAAE,IAAI,EAAE;QACxE,KAAK,EAAE,GAAG;KACV,CAAC,CAAC;AACJ,CAAC"}

package/dist/hydra/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The hand-owned HydraDB wrapper. This module is the ONLY place that imports
+ * `@hydradb/sdk`; everything else in the server talks to `HydraDB` here.
+ *
+ * It is intentionally self-contained so the same pattern can be ported to the
+ * other client repos (per CONTRACT.md).
+ */
+export { HydraDB, ContextResource, DatabasesResource } from "./client.js";
+export type { HydraConfig, ContextKind, QueryKind, ConversationTurn, QueryParams, IngestParams, ListParams, InspectParams, IngestionStatusParams, RelationsParams, DeleteParams, CreateDatabaseParams, } from "./client.js";
+export { HydraWrapperError, translateError } from "./errors.js";
+export { unwrap } from "./envelope.js";

package/dist/hydra/index.js

@@ -0,0 +1,11 @@
+/**
+ * The hand-owned HydraDB wrapper. This module is the ONLY place that imports
+ * `@hydradb/sdk`; everything else in the server talks to `HydraDB` here.
+ *
+ * It is intentionally self-contained so the same pattern can be ported to the
+ * other client repos (per CONTRACT.md).
+ */
+export { HydraDB, ContextResource, DatabasesResource } from "./client.js";
+export { HydraWrapperError, translateError } from "./errors.js";
+export { unwrap } from "./envelope.js";
+//# sourceMappingURL=index.js.map

package/dist/hydra/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hydra/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAe1E,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveConfig } from "./config.js";
 import { createHydraDBServer } from "./server.js";
-const HYDRA_DB_API_KEY = process.env.HYDRA_DB_API_KEY;
-if (!HYDRA_DB_API_KEY) {
-    console.error("Error: HYDRA_DB_API_KEY environment variable is required");
-    process.exit(1);
+// Fail fast with a clean message if required config is missing. Honours the
+// canonical HYDRADB_* names (and the deprecated HYDRA_DB_* aliases).
+try {
+    resolveConfig();
 }
-const HYDRA_DB_TENANT_ID = process.env.HYDRA_DB_TENANT_ID;
-if (!HYDRA_DB_TENANT_ID) {
-    console.error("Error: HYDRA_DB_TENANT_ID environment variable is required");
+catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
     process.exit(1);
 }
 async function main() {

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,4EAA4E;AAC5E,qEAAqE;AACrE,IAAI,CAAC;IACJ,aAAa,EAAE,CAAC;AACjB,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IAChB,OAAO,CAAC,KAAK,CAAC,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,IAAI;IAClB,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;AACF,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACtB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC,CAAC,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Structured logger for Hydra DB MCP Server.
+ * Outputs to stderr to avoid interfering with STDIO transport.
+ */
+import { type EnvSource, type WarnFn } from "./config.js";
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+/**
+ * `HYDRADB_LOG_LEVEL` is the canonical name (CONTRACT §1). `HYDRA_DB_LOG_LEVEL`
+ * was the only variable the canonical-prefix migration missed; it is honoured as
+ * a deprecated alias on the same terms as every other legacy spelling.
+ */
+export declare function resolveLogLevel(env?: EnvSource, warn?: WarnFn): LogLevel;
+export declare const logger: {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+};

package/dist/logger.js

@@ -2,6 +2,7 @@
  * Structured logger for Hydra DB MCP Server.
  * Outputs to stderr to avoid interfering with STDIO transport.
  */
+import { readEnv } from "./config.js";
 export var LogLevel;
 (function (LogLevel) {
     LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
@@ -15,8 +16,15 @@ const LOG_LEVEL_NAMES = {
     [LogLevel.WARN]: "WARN",
     [LogLevel.ERROR]: "ERROR",
 };
-function getLogLevel() {
-    const level = process.env.HYDRA_DB_LOG_LEVEL?.toUpperCase();
+/**
+ * `HYDRADB_LOG_LEVEL` is the canonical name (CONTRACT §1). `HYDRA_DB_LOG_LEVEL`
+ * was the only variable the canonical-prefix migration missed; it is honoured as
+ * a deprecated alias on the same terms as every other legacy spelling.
+ */
+export function resolveLogLevel(env = process.env, warn) {
+    // `warn` is optional here; passing it through undefined falls back to
+    // readEnv's own stderr default.
+    const level = readEnv(env, "HYDRADB_LOG_LEVEL", "HYDRA_DB_LOG_LEVEL", warn)?.toUpperCase();
     switch (level) {
         case "DEBUG":
             return LogLevel.DEBUG;
@@ -30,7 +38,7 @@ function getLogLevel() {
             return LogLevel.ERROR;
     }
 }
-const currentLogLevel = getLogLevel();
+const currentLogLevel = resolveLogLevel();
 function formatMessage(level, message, meta) {
     const timestamp = new Date().toISOString();
     const levelName = LOG_LEVEL_NAMES[level];

package/dist/logger.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,37 @@
+import { HydraDB } from "./hydra/index.js";
+/** Test-only: reset the once-per-process alias warning dedupe. */
+export declare function __resetAliasWarnings(): void;
+export declare function createHydraDBServer(hydraOverride?: HydraDB): import("@modelcontextprotocol/sdk/server/index.js").Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;