@tdxvolt/volt-drive-mcp 0.0.0-stage → 0.1.0

package/src/bytes.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Normalise a protobuf `bytes` value to a Uint8Array. The Volt gRPC client
+ * delivers Buffers, but other encodings (base64 strings from JSON based
+ * transports, plain arrays) are tolerated so callers do not have to care.
+ */
+export function toBytes(value) {
+  if (!value) {
+    return new Uint8Array();
+  }
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return Uint8Array.from(value);
+  }
+  if (typeof value === "string") {
+    return new Uint8Array(Buffer.from(value, "base64"));
+  }
+  throw new Error("unexpected binary encoding");
+}
+
+export function concatBytes(chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return bytes;
+}
+
+/**
+ * sha256 of the raw bytes as unpadded base64url. This is the content hash
+ * format used by the synapse blob store and by the native VoltDrive.
+ */
+export function blobHash(bytes) {
+  return createHash("sha256").update(bytes).digest("base64url");
+}
+
+/**
+ * Heuristic matching the Explorer and the native client: a file is binary if
+ * the first 8 KiB contain a NUL byte or are not valid UTF-8.
+ */
+export function looksBinary(bytes) {
+  const sample = bytes.subarray(0, Math.min(bytes.length, 8192));
+  for (const byte of sample) {
+    if (byte === 0) {
+      return true;
+    }
+  }
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(sample);
+    return false;
+  } catch {
+    // A multi-byte character may have been cut in half by the 8 KiB sample.
+    if (bytes.length > sample.length) {
+      for (let trim = 1; trim <= 3 && trim < sample.length; trim++) {
+        try {
+          new TextDecoder("utf-8", { fatal: true }).decode(
+            sample.subarray(0, sample.length - trim)
+          );
+          return false;
+        } catch {
+          // keep trimming
+        }
+      }
+    }
+    return true;
+  }
+}

package/src/config.js

@@ -0,0 +1,116 @@
+import { parseArgs } from "node:util";
+
+const MIB = 1024 * 1024;
+
+const COMMON_OPTIONS = {
+  config: { type: "string", short: "c" },
+  "read-only": { type: "boolean" },
+  drive: { type: "string", multiple: true, short: "d" },
+  "max-file-bytes": { type: "string" },
+  "max-response-chars": { type: "string" },
+  help: { type: "boolean", short: "h" }
+};
+
+const HTTP_OPTIONS = {
+  host: { type: "string" },
+  port: { type: "string", short: "p" },
+  path: { type: "string" },
+  token: { type: "string" },
+  "allowed-host": { type: "string", multiple: true }
+};
+
+function parsePositiveInt(value, name) {
+  if (value === undefined) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`--${name} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function envFlag(name) {
+  const value = process.env[name];
+  return value !== undefined && ["1", "true", "yes"].includes(value.toLowerCase());
+}
+
+function splitList(value) {
+  return (value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export const COMMON_USAGE = `Options:
+  -c, --config <file>        Volt client configuration (volt.config.json).
+                             Env: VOLT_DRIVE_MCP_CONFIG. Default: ./volt.config.json
+      --read-only            Do not offer any tool that changes a drive.
+                             Env: VOLT_DRIVE_MCP_READ_ONLY=1
+  -d, --drive <id|name>      Only expose this drive (repeatable).
+                             Env: VOLT_DRIVE_MCP_DRIVES=a,b
+      --max-file-bytes <n>   Largest file that can be read or written (default ${10 * MIB}).
+      --max-response-chars <n>  Most characters returned by one read (default 100000).
+  -h, --help                 Show this help.
+
+Logging goes to stderr; set VOLT_DRIVE_MCP_LOG=debug for more detail.`;
+
+export const HTTP_USAGE = `HTTP options:
+      --host <addr>          Address to listen on (default 127.0.0.1).
+  -p, --port <n>             Port to listen on (default 3333).
+      --path <path>          URL path of the MCP endpoint (default /mcp).
+      --token <secret>       Bearer token clients must send. Env: VOLT_DRIVE_MCP_TOKEN
+                             Required when listening on a non-loopback address.
+      --allowed-host <name>  Extra Host header value to accept (repeatable), for
+                             use behind a reverse proxy.`;
+
+/**
+ * Parse command line arguments and environment into connector settings.
+ *
+ * @param {string[]} argv
+ * @param {{ http?: boolean }} [mode]
+ */
+export function parseConfig(argv, { http = false } = {}) {
+  const { values } = parseArgs({
+    args: argv,
+    options: http ? { ...COMMON_OPTIONS, ...HTTP_OPTIONS } : COMMON_OPTIONS,
+    allowPositionals: false,
+    strict: true
+  });
+
+  const drives = [
+    ...splitList(process.env.VOLT_DRIVE_MCP_DRIVES),
+    ...(values.drive ?? [])
+  ];
+
+  const config = {
+    help: Boolean(values.help),
+    configPath:
+      values.config ?? process.env.VOLT_DRIVE_MCP_CONFIG ?? "./volt.config.json",
+    options: {
+      readOnly: Boolean(values["read-only"]) || envFlag("VOLT_DRIVE_MCP_READ_ONLY"),
+      drives,
+      ...(values["max-file-bytes"] !== undefined && {
+        maxFileBytes: parsePositiveInt(values["max-file-bytes"], "max-file-bytes")
+      }),
+      ...(values["max-response-chars"] !== undefined && {
+        maxResponseChars: parsePositiveInt(
+          values["max-response-chars"],
+          "max-response-chars"
+        )
+      })
+    }
+  };
+
+  if (http) {
+    config.http = {
+      host: values.host ?? "127.0.0.1",
+      port: parsePositiveInt(values.port, "port") ?? 3333,
+      path: values.path ?? "/mcp",
+      token: values.token ?? process.env.VOLT_DRIVE_MCP_TOKEN ?? "",
+      allowedHosts: values["allowed-host"] ?? []
+    };
+  }
+
+  return config;
+}

package/src/connect.js

@@ -0,0 +1,43 @@
+import grpc from "@grpc/grpc-js";
+import { SyncProvider, VoltClient } from "@tdxvolt/volt-client-grpc";
+import * as Y from "yjs";
+import { DriveService } from "./drive-service.js";
+
+/**
+ * Create a `DriveService` for the Volt described by `configPath`, without
+ * connecting yet. The connection is made on first use (call
+ * `service.ensureConnected()` to start it early) and is retried after a
+ * failure, so an MCP server can start and answer `tools/list` straight away
+ * even when the Volt is slow, down, or waiting for the identity to be approved.
+ *
+ * The configuration is the same `volt.config.json` the other Volt clients use
+ * and holds the identity this connector acts as: it can only reach the drives
+ * (and documents) that identity has been granted access to, so give it a
+ * dedicated identity with just the access you want an AI client to have.
+ *
+ * @param {string} configPath
+ * @param {object} [settings]
+ * @param {Partial<import("./drive-service.js").DriveService["options"]>} [settings.options]
+ * @param {object} [settings.logger]
+ * @returns {DriveService}
+ */
+export function createDriveService(configPath, { options, logger } = {}) {
+  const client = new VoltClient(grpc);
+
+  const connect = async () => {
+    logger?.info?.(`connecting to the Volt using ${configPath}`);
+    await client.initialise(configPath);
+    logger?.info?.(
+      `connected to ${client.voltConfig?.display_name ?? client.voltConfig?.id}`
+    );
+  };
+
+  return new DriveService({ client, Y, SyncProvider, connect, options, logger });
+}
+
+/** Like `createDriveService`, but resolves once the connection is up. */
+export async function connectDriveService(configPath, settings) {
+  const service = createDriveService(configPath, settings);
+  await service.ensureConnected();
+  return service;
+}

package/src/doc-state.js

@@ -0,0 +1,131 @@
+import { DriveError, timeout as timeoutError } from "./errors.js";
+
+/**
+ * Synapse metadata replicates ahead of content, so a drive can list a file
+ * whose bytes this Volt does not hold yet (most visibly just after cloning a
+ * large drive). Reading such a file would return an empty document or fail on
+ * a missing blob, so reads wait for the document to become ready.
+ *
+ * The state is checked once with `GetSynapseDocumentState`; only when the
+ * content is still in flight does the wait subscribe to
+ * `WatchSynapseDocumentState` to be told when it arrives.
+ */
+
+export const DocumentState = {
+  UNKNOWN: "SYNAPSE_DOCUMENT_STATE_UNKNOWN",
+  ABSENT: "SYNAPSE_DOCUMENT_STATE_ABSENT",
+  DRAFT: "SYNAPSE_DOCUMENT_STATE_DRAFT",
+  ANNOUNCED: "SYNAPSE_DOCUMENT_STATE_ANNOUNCED",
+  READY: "SYNAPSE_DOCUMENT_STATE_READY",
+  DELETED: "SYNAPSE_DOCUMENT_STATE_DELETED"
+};
+
+const notYetSynced = () =>
+  timeoutError(
+    "the file's content has not finished syncing to this Volt yet; try again shortly"
+  );
+
+/** What a state means for a reader: "wait", "gone" or "ready". */
+function classify(state) {
+  if (state === DocumentState.ABSENT || state === DocumentState.DELETED) {
+    return "gone";
+  }
+  // `ready`, `draft` (an empty file) and any state this client does not
+  // understand can be read now.
+  return state === DocumentState.ANNOUNCED ? "wait" : "ready";
+}
+
+function assertPresent(outcome) {
+  if (outcome === "gone") {
+    throw new DriveError("file is no longer in the drive", "not_found");
+  }
+}
+
+/**
+ * Wait until a watch on `documentId` reports a state other than `announced`.
+ * Resolves with "ready" or "gone". If the watch cannot be used, resolves with
+ * "ready": reading anyway beats blocking on a signal that is not coming.
+ */
+function watchUntilSettled(client, synapseId, documentId, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let call;
+    let finished = false;
+    let timer;
+
+    const finish = (outcome, error) => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      clearTimeout(timer);
+      try {
+        call?.write({ stop: true });
+      } catch {
+        // The call is already closed.
+      }
+      if (error) {
+        reject(error);
+      } else {
+        resolve(outcome);
+      }
+    };
+
+    timer = setTimeout(() => finish(null, notYetSynced()), timeoutMs);
+
+    try {
+      call = client.WatchSynapseDocumentState({
+        start: { synapse_id: synapseId, document_id: [documentId] }
+      });
+    } catch {
+      finish("ready");
+      return;
+    }
+
+    call.on("data", (payload) => {
+      const update = payload?.update;
+      if (!update || (update.document_id && update.document_id !== documentId)) {
+        return;
+      }
+      const outcome = classify(update.state);
+      if (outcome !== "wait") {
+        finish(outcome);
+      }
+    });
+    call.on("error", () => finish("ready"));
+    call.on("end", () => finish("ready"));
+  });
+}
+
+/**
+ * Resolve once this Volt holds the document's content.
+ *
+ * - `announced`: the content is still in flight, wait for it.
+ * - `absent` / `deleted`: the file is gone, reject.
+ * - anything else can be read now.
+ *
+ * If the state cannot be queried at all the wait is skipped.
+ */
+export async function waitForDocumentReady(
+  client,
+  synapseId,
+  documentId,
+  { timeoutMs = 30_000 } = {}
+) {
+  let response;
+  try {
+    response = await client.GetSynapseDocumentState({
+      synapse_id: synapseId,
+      document_id: documentId
+    });
+  } catch {
+    return;
+  }
+
+  const outcome = classify(response?.state);
+  assertPresent(outcome);
+  if (outcome === "ready") {
+    return;
+  }
+
+  assertPresent(await watchUntilSettled(client, synapseId, documentId, timeoutMs));
+}