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

package/src/drive-session.js

@@ -0,0 +1,283 @@
+import { DriveError, timeout as timeoutError } from "./errors.js";
+import {
+  FOLDERS_BRANCH,
+  FOLDERS_DOCUMENT_ID,
+  FOLDERS_STATE_BRANCH,
+  IDX_BRANCH,
+  META_DOCUMENT_ID,
+  readDriveEntries,
+  readDriveFolders
+} from "./drive-index.js";
+import { createProvider, startAndWaitForSync, stopAndWait } from "./sync-doc.js";
+
+const LEGACY_IMPORTED_KEY = "legacyImported";
+
+/**
+ * A live, synced view of one drive's index.
+ *
+ * Opening a session starts two long lived Volt sync streams: the `__meta`
+ * document (the file index, read only for clients) and the `folders` document
+ * (explicit folders, writable). Both are kept up to date by the Volt, and the
+ * derived file and folder lists are recomputed lazily when they change.
+ */
+export class DriveSession {
+  /**
+   * @param {object} ctx - { Y, SyncProvider, client, logger }
+   * @param {object} resource - the drive resource as returned by the Volt.
+   * @param {object} options
+   * @param {boolean} options.readOnly - never create or write the folders document.
+   * @param {number} options.syncTimeoutMs
+   */
+  constructor(ctx, resource, { readOnly = false, syncTimeoutMs = 30_000 } = {}) {
+    this.ctx = ctx;
+    this.resource = resource;
+    this.readOnly = readOnly;
+    this.syncTimeoutMs = syncTimeoutMs;
+
+    this.metaDoc = null;
+    this.metaProvider = null;
+    this.foldersDoc = null;
+    this.foldersProvider = null;
+    this.foldersMap = null;
+    this.foldersWritable = false;
+
+    this._opening = null;
+    this._metaSynced = false;
+    this._dirty = true;
+    this._entries = [];
+    this._folders = [];
+    this._waiters = new Set();
+    this._writeChain = Promise.resolve();
+  }
+
+  get id() {
+    return this.resource.id;
+  }
+
+  get metaSynced() {
+    return this._metaSynced;
+  }
+
+  /** Open the session (idempotent; concurrent callers share one attempt). */
+  open() {
+    if (!this._opening) {
+      this._opening = this._open().catch((err) => {
+        // Allow a later call to try again.
+        this._opening = null;
+        throw err;
+      });
+    }
+    return this._opening;
+  }
+
+  async _open() {
+    const { Y } = this.ctx;
+
+    this.metaDoc = new Y.Doc();
+    this.metaDoc.guid = META_DOCUMENT_ID;
+    this.metaProvider = createProvider(this.ctx, this.id, this.metaDoc);
+    this.metaProvider.on("sync", (synced) => {
+      this._metaSynced = Boolean(synced);
+    });
+
+    await startAndWaitForSync(
+      this.metaProvider,
+      this.syncTimeoutMs,
+      `drive ${this.id} metadata`
+    );
+
+    const idx = this.metaDoc.getMap(IDX_BRANCH);
+    idx.observeDeep(() => this._changed());
+
+    await this._openFolders(idx);
+
+    this._changed();
+  }
+
+  async _openFolders(idx) {
+    const { Y, client, logger } = this.ctx;
+
+    if (!idx.has(FOLDERS_DOCUMENT_ID) && !this.readOnly) {
+      // The folders document is created on first use.
+      try {
+        await client.SetSynapseDocumentMetadata({
+          synapse_id: this.id,
+          document_id: FOLDERS_DOCUMENT_ID,
+          metadata: [
+            { name: FOLDERS_BRANCH, type: "map" },
+            { name: FOLDERS_STATE_BRANCH, type: "map" }
+          ],
+          publish_hash: true
+        });
+      } catch (err) {
+        logger?.debug?.(`could not create folders document: ${err.message}`);
+      }
+    }
+
+    this.foldersDoc = new Y.Doc();
+    this.foldersDoc.guid = FOLDERS_DOCUMENT_ID;
+    const provider = createProvider(this.ctx, this.id, this.foldersDoc);
+
+    try {
+      await startAndWaitForSync(provider, Math.min(this.syncTimeoutMs, 10_000), "folders");
+    } catch (err) {
+      // No folders document for this identity (or none yet): show the folders
+      // recorded by earlier versions in `__meta`, read only.
+      logger?.debug?.(`folders document unavailable: ${err.message}`);
+      this.foldersDoc = null;
+      this.foldersMap = this.metaDoc.getMap(FOLDERS_BRANCH);
+      this.foldersMap.observeDeep(() => this._changed());
+      this.foldersWritable = false;
+      return;
+    }
+
+    this.foldersProvider = provider;
+    this.foldersMap = this.foldersDoc.getMap(FOLDERS_BRANCH);
+    this.foldersWritable = !provider.isReadOnly && !this.readOnly;
+
+    if (this.foldersWritable) {
+      const state = this.foldersDoc.getMap(FOLDERS_STATE_BRANCH);
+      if (!state.has(LEGACY_IMPORTED_KEY)) {
+        // One-off: carry over folders recorded in `__meta` by earlier
+        // versions. Idempotent, so concurrent importers are harmless.
+        const legacy = this.metaDoc.getMap(FOLDERS_BRANCH);
+        this.foldersDoc.transact(() => {
+          for (const path of legacy.keys()) {
+            if (path && !this.foldersMap.has(path)) {
+              this.foldersMap.set(path, true);
+            }
+          }
+          state.set(LEGACY_IMPORTED_KEY, true);
+        });
+      }
+    }
+
+    this.foldersMap.observeDeep(() => this._changed());
+  }
+
+  _changed() {
+    this._dirty = true;
+    for (const waiter of [...this._waiters]) {
+      waiter();
+    }
+  }
+
+  _refresh() {
+    if (!this._dirty || !this.metaDoc) {
+      return;
+    }
+    this._entries = readDriveEntries(this.metaDoc.getMap(IDX_BRANCH));
+    this._folders = this.foldersMap ? readDriveFolders(this.foldersMap) : [];
+    this._dirty = false;
+  }
+
+  /** Make sure the session is open and its metadata stream is live. */
+  async ensureReady() {
+    await this.open();
+    if (!this.metaSynced) {
+      // The stream dropped (for example the Volt connection was reset).
+      await startAndWaitForSync(
+        this.metaProvider,
+        this.syncTimeoutMs,
+        `drive ${this.id} metadata`
+      );
+      this._changed();
+    }
+  }
+
+  /** @returns {import("./drive-index.js").DriveEntry[]} */
+  get entries() {
+    this._refresh();
+    return this._entries;
+  }
+
+  /** @returns {string[]} */
+  get folders() {
+    this._refresh();
+    return this._folders;
+  }
+
+  /**
+   * Resolve once `predicate()` is true. The index is updated asynchronously by
+   * the Volt after a write, so callers use this to read their own writes.
+   */
+  waitFor(predicate, timeoutMs = 10_000, what = "the drive index to update") {
+    if (predicate()) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._waiters.delete(check);
+        reject(timeoutError(`timed out waiting for ${what}`));
+      }, timeoutMs);
+      const check = () => {
+        if (predicate()) {
+          clearTimeout(timer);
+          this._waiters.delete(check);
+          resolve();
+        }
+      };
+      this._waiters.add(check);
+    });
+  }
+
+  /**
+   * Run `fn` with exclusive access to this drive's write path so concurrent tool
+   * calls cannot interleave their check-then-write sequences.
+   */
+  exclusive(fn) {
+    const run = this._writeChain.then(fn, fn);
+    this._writeChain = run.catch(() => {});
+    return run;
+  }
+
+  /** Mutate the folders map in one transaction and wait for it to be sent. */
+  async mutateFolders(fn) {
+    if (!this.foldersWritable) {
+      throw new DriveError(
+        "the folders list of this drive is read-only for the current identity",
+        "forbidden"
+      );
+    }
+    this.foldersDoc.transact(() => fn(this.foldersMap));
+    await this.foldersProvider.whenOutboundDrained();
+  }
+
+  /** Add `paths` (and nothing else) to the explicit folders list. */
+  async addFolders(paths) {
+    if (!this.foldersWritable) {
+      // Folders are implied by the files they contain, so this only matters
+      // for empty folders; a read only folders list is not an error here.
+      return false;
+    }
+    await this.mutateFolders((map) => {
+      for (const path of paths) {
+        if (path && !map.has(path)) {
+          map.set(path, true);
+        }
+      }
+    });
+    return true;
+  }
+
+  /** Remove `paths` from the explicit folders list. */
+  async removeFolders(paths) {
+    if (!this.foldersWritable) {
+      return false;
+    }
+    await this.mutateFolders((map) => {
+      for (const path of paths) {
+        map.delete(path);
+      }
+    });
+    return true;
+  }
+
+  async close() {
+    const providers = [this.foldersProvider, this.metaProvider].filter(Boolean);
+    this.foldersProvider = null;
+    this.metaProvider = null;
+    this._opening = null;
+    await Promise.all(providers.map((provider) => stopAndWait(provider, 3_000)));
+  }
+}

package/src/errors.js

@@ -0,0 +1,23 @@
+/**
+ * An error whose message is safe and useful to show to the model. The MCP layer
+ * converts these into tool results with `isError: true` so the model can read
+ * the message and correct its call, rather than failing the protocol request.
+ */
+export class DriveError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [code] - short machine readable code, e.g. "not_found".
+   */
+  constructor(message, code = "error") {
+    super(message);
+    this.name = "DriveError";
+    this.code = code;
+  }
+}
+
+export const notFound = (message) => new DriveError(message, "not_found");
+export const invalid = (message) => new DriveError(message, "invalid");
+export const conflict = (message) => new DriveError(message, "conflict");
+export const forbidden = (message) => new DriveError(message, "forbidden");
+export const tooLarge = (message) => new DriveError(message, "too_large");
+export const timeout = (message) => new DriveError(message, "timeout");

package/src/http.js

@@ -0,0 +1,229 @@
+/**
+ * Streamable HTTP front end for the connector.
+ *
+ * The server is stateless: every POST gets its own `McpServer` and transport,
+ * all sharing one `DriveService`, so the Volt connection and the open drive
+ * sessions are reused across requests and clients. There are no MCP sessions
+ * to track and nothing to clean up when a client disappears.
+ *
+ * Because this is a network service in front of someone's files it defends
+ * itself: it binds to loopback by default, requires a bearer token (always,
+ * unless bound to loopback with none configured), and checks the Host and
+ * Origin headers so a web page cannot reach it through DNS rebinding.
+ */
+
+import { createServer as createHttpServer } from "node:http";
+import { timingSafeEqual, createHash } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "./server.js";
+
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost", "[::1]"]);
+
+export function isLoopbackHost(host) {
+  return LOOPBACK_HOSTS.has(host);
+}
+
+/** Compare secrets without leaking their length or content through timing. */
+function secretsMatch(given, expected) {
+  const a = createHash("sha256").update(given).digest();
+  const b = createHash("sha256").update(expected).digest();
+  return timingSafeEqual(a, b);
+}
+
+/** Host name of a Host header value ("example.com:3333" -> "example.com"). */
+function hostName(headerValue) {
+  const value = String(headerValue ?? "").toLowerCase();
+  if (value.startsWith("[")) {
+    const end = value.indexOf("]");
+    return end === -1 ? value : value.slice(0, end + 1);
+  }
+  return value.split(":")[0];
+}
+
+function sendJson(res, status, body, headers = {}) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+    ...headers
+  });
+  res.end(payload);
+}
+
+function jsonRpcError(res, status, code, message, headers) {
+  sendJson(res, status, { jsonrpc: "2.0", error: { code, message }, id: null }, headers);
+}
+
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) {
+      const err = new Error("request body is too large");
+      err.status = 413;
+      throw err;
+    }
+    chunks.push(chunk);
+  }
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!text) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    const err = new Error("request body is not valid JSON");
+    err.status = 400;
+    throw err;
+  }
+}
+
+/**
+ * Validate the HTTP settings and fill in defaults.
+ * @param {{ host?: string, port?: number, path?: string, token?: string, allowedHosts?: string[] }} http
+ */
+export function resolveHttpSettings(http = {}) {
+  const settings = {
+    host: http.host ?? "127.0.0.1",
+    port: http.port ?? 3333,
+    path: http.path ?? "/mcp",
+    token: http.token ?? "",
+    allowedHosts: (http.allowedHosts ?? []).map((h) => h.toLowerCase())
+  };
+  if (!settings.path.startsWith("/")) {
+    settings.path = `/${settings.path}`;
+  }
+  if (!settings.token && !isLoopbackHost(settings.host)) {
+    throw new Error(
+      `refusing to listen on ${settings.host} without a token: pass --token or set VOLT_DRIVE_MCP_TOKEN`
+    );
+  }
+  return settings;
+}
+
+/**
+ * Create (but do not start) the HTTP server.
+ *
+ * @param {import("./drive-service.js").DriveService} service
+ * @param {Parameters<typeof resolveHttpSettings>[0]} httpSettings
+ * @param {{ logger?: import("./logger.js").Logger }} [deps]
+ */
+export function createHttpApp(service, httpSettings, { logger } = {}) {
+  const settings = resolveHttpSettings(httpSettings);
+  const loopbackOnly = isLoopbackHost(settings.host);
+
+  // Names the Host header may carry: loopback names and the bind address, plus
+  // whatever the operator allowed for a reverse proxy.
+  const allowedHostNames = new Set([
+    ...LOOPBACK_HOSTS,
+    settings.host.toLowerCase(),
+    ...settings.allowedHosts
+  ]);
+
+  const hostAllowed = (req) => {
+    // A remote deployment is protected by its token; a Host allow-list there
+    // would only get in the way unless the operator asked for one.
+    if (!loopbackOnly && settings.allowedHosts.length === 0) {
+      return true;
+    }
+    return allowedHostNames.has(hostName(req.headers.host));
+  };
+
+  const originAllowed = (req) => {
+    const origin = req.headers.origin;
+    if (!origin) {
+      return true; // not a browser
+    }
+    try {
+      const url = new URL(origin);
+      return allowedHostNames.has(url.hostname.toLowerCase());
+    } catch {
+      return false;
+    }
+  };
+
+  const authorised = (req) => {
+    if (!settings.token) {
+      return true;
+    }
+    const header = String(req.headers.authorization ?? "");
+    const match = /^Bearer\s+(.+)$/i.exec(header);
+    return Boolean(match) && secretsMatch(match[1].trim(), settings.token);
+  };
+
+  const handle = async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname !== settings.path) {
+      sendJson(res, 404, { error: "not found" });
+      return;
+    }
+    if (!hostAllowed(req) || !originAllowed(req)) {
+      jsonRpcError(res, 403, -32000, "Forbidden: unexpected Host or Origin");
+      return;
+    }
+    if (!authorised(req)) {
+      jsonRpcError(res, 401, -32001, "Unauthorized", {
+        "www-authenticate": 'Bearer realm="volt-drive-mcp"'
+      });
+      return;
+    }
+    if (req.method !== "POST") {
+      // Stateless: there is no server-initiated stream and no session to end.
+      jsonRpcError(res, 405, -32000, "Method not allowed", { allow: "POST" });
+      return;
+    }
+
+    let body;
+    try {
+      body = await readBody(req);
+    } catch (err) {
+      jsonRpcError(res, err.status ?? 400, -32700, err.message);
+      return;
+    }
+
+    const server = createServer(service, { logger });
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true
+    });
+    res.on("close", () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+  };
+
+  return createHttpServer((req, res) => {
+    handle(req, res).catch((err) => {
+      logger?.error(`request failed: ${err?.stack ?? err}`);
+      if (!res.headersSent) {
+        jsonRpcError(res, 500, -32603, "Internal server error");
+      } else {
+        res.end();
+      }
+    });
+  });
+}
+
+/**
+ * Start listening. Resolves with the server and the actual port (useful with
+ * port 0).
+ */
+export async function startHttpServer(service, httpSettings, deps = {}) {
+  const settings = resolveHttpSettings(httpSettings);
+  const httpServer = createHttpApp(service, settings, deps);
+  await new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(settings.port, settings.host, () => {
+      httpServer.off("error", reject);
+      resolve();
+    });
+  });
+  const address = httpServer.address();
+  const port = typeof address === "object" && address ? address.port : settings.port;
+  return { httpServer, port, settings };
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { connectDriveService, createDriveService } from "./connect.js";
+export { DEFAULT_OPTIONS, DriveService } from "./drive-service.js";
+export { DriveError } from "./errors.js";
+export { createServer, defineTools } from "./server.js";

package/src/logger.js

@@ -0,0 +1,38 @@
+/**
+ * Logging for a process whose stdout may be the MCP protocol channel.
+ *
+ * Everything goes to stderr, never stdout: on the stdio transport a stray line
+ * on stdout corrupts the JSON-RPC stream. The level comes from
+ * `VOLT_DRIVE_MCP_LOG` (error | info | debug), default info.
+ */
+
+const LEVELS = { error: 0, info: 1, debug: 2 };
+
+export function createLogger(level = process.env.VOLT_DRIVE_MCP_LOG || "info") {
+  const threshold = LEVELS[level] ?? LEVELS.info;
+
+  const write = (name, message) => {
+    if (LEVELS[name] > threshold) {
+      return;
+    }
+    process.stderr.write(`[volt-drive-mcp] ${name}: ${message}\n`);
+  };
+
+  return {
+    error: (message) => write("error", message),
+    info: (message) => write("info", message),
+    debug: (message) => write("debug", message)
+  };
+}
+
+/**
+ * Make `console.log` and friends write to stderr. Third party code (and the
+ * Volt client's dependencies) occasionally logs to stdout, which on the stdio
+ * transport would break the protocol.
+ */
+export function redirectConsoleToStderr() {
+  const toStderr = (...args) => console.error(...args);
+  console.log = toStderr;
+  console.info = toStderr;
+  console.debug = toStderr;
+}