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

package/src/paths.js

@@ -0,0 +1,145 @@
+import { invalid } from "./errors.js";
+
+const MAX_PATH_LENGTH = 4096;
+const MAX_SEGMENT_LENGTH = 255;
+
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+
+/**
+ * Normalise a user supplied drive path into the canonical form used in the
+ * drive index: forward slashes, no leading or trailing slash, no empty, `.` or
+ * `..` segments. The drive root is the empty string.
+ *
+ * Drive paths are relative to the root of the drive and are also materialised
+ * as paths on the local disk by the VoltDrive daemon, so anything that could
+ * escape the root (`..`, absolute paths, drive letters) is rejected outright
+ * rather than being silently rewritten.
+ *
+ * @param {unknown} input
+ * @param {object} [options]
+ * @param {boolean} [options.allowRoot] - permit the empty path (the drive root).
+ * @returns {string}
+ */
+export function normalizeDrivePath(input, { allowRoot = false } = {}) {
+  if (input === undefined || input === null) {
+    input = "";
+  }
+  if (typeof input !== "string") {
+    throw invalid("path must be a string");
+  }
+
+  if (CONTROL_CHARS.test(input)) {
+    throw invalid("path contains control characters");
+  }
+
+  if (input.length > MAX_PATH_LENGTH) {
+    throw invalid("path is too long");
+  }
+
+  const unified = input.replace(/\\/g, "/");
+
+  if (/^[A-Za-z]:/.test(unified)) {
+    throw invalid("path must be relative to the drive root (no drive letters)");
+  }
+
+  const segments = [];
+  for (const segment of unified.split("/")) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      throw invalid("path must not contain '..' segments");
+    }
+    if (segment.length > MAX_SEGMENT_LENGTH) {
+      throw invalid("path segment is too long");
+    }
+    segments.push(segment);
+  }
+
+  const normalized = segments.join("/");
+  if (!normalized && !allowRoot) {
+    throw invalid("path must not be empty");
+  }
+  return normalized;
+}
+
+/** The last segment of a normalised path. */
+export function basename(path) {
+  const slash = path.lastIndexOf("/");
+  return slash < 0 ? path : path.slice(slash + 1);
+}
+
+/** The parent folder of a normalised path ("" for top level items). */
+export function parentOf(path) {
+  const slash = path.lastIndexOf("/");
+  return slash < 0 ? "" : path.slice(0, slash);
+}
+
+/** Every ancestor folder of `path`, outermost first, excluding `path` itself. */
+export function ancestorsOf(path) {
+  const result = [];
+  let slash = path.indexOf("/");
+  while (slash > 0) {
+    result.push(path.slice(0, slash));
+    slash = path.indexOf("/", slash + 1);
+  }
+  return result;
+}
+
+/** True when `path` equals `folder` or lies underneath it. */
+export function isWithin(path, folder) {
+  if (!folder) {
+    return true;
+  }
+  return path === folder || path.startsWith(`${folder}/`);
+}
+
+/**
+ * Stable ordering for drive paths: case-insensitive first, then exact, so the
+ * listing order does not depend on the locale of the host.
+ */
+export function compareDrivePaths(a, b) {
+  const la = a.toLowerCase();
+  const lb = b.toLowerCase();
+  if (la < lb) {
+    return -1;
+  }
+  if (la > lb) {
+    return 1;
+  }
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+}
+
+/**
+ * Compile a glob (`*` any run within a segment, `**` any run across segments,
+ * `?` a single character) into a case-insensitive regular expression anchored
+ * to the whole path.
+ */
+export function globToRegExp(glob) {
+  let source = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        source += ".*";
+        i++;
+        if (glob[i + 1] === "/") {
+          // `**/` also matches zero directories.
+          i++;
+          source = source.slice(0, -2) + "(?:.*/)?";
+        }
+      } else {
+        source += "[^/]*";
+      }
+    } else if (ch === "?") {
+      source += "[^/]";
+    } else {
+      source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${source}$`, "i");
+}

package/src/server.js

@@ -0,0 +1,338 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { DriveError } from "./errors.js";
+
+export const SERVER_NAME = "volt-drive";
+export const SERVER_VERSION = "0.1.0";
+
+const SERVER_INSTRUCTIONS = [
+  "Access to VoltDrive drives: folders of files stored in a Volt and synced to the devices of the people who share them.",
+  "Call list_drives first to find the drive to use, then browse with list_directory, search with search_files, and read with read_file.",
+  "Paths are relative to the drive root, use forward slashes, and never start with a slash.",
+  "Edits sync to every device that has the drive, so prefer small targeted changes, and never overwrite or delete a file unless asked to."
+].join(" ");
+
+const drive = z
+  .string()
+  .describe("The drive to use: its id, alias or exact name (see list_drives).");
+
+const path = z
+  .string()
+  .describe("Path relative to the drive root, e.g. 'notes/todo.md'. Use forward slashes.");
+
+const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const ADDITIVE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+const IDEMPOTENT_ADDITIVE = { ...ADDITIVE, idempotentHint: true };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
+
+const text = (value) => ({ type: "text", text: value });
+const json = (value) => text(JSON.stringify(value, null, 2));
+
+/** A result for a successful call that returns a JSON document. */
+const jsonResult = (value) => ({ content: [json(value)] });
+
+/** A tool failure the model can read and act on. */
+const errorResult = (message) => ({
+  isError: true,
+  content: [text(message)]
+});
+
+/**
+ * File reads return the file's content as its own text block, exactly as
+ * stored, followed by a small JSON block of metadata. That avoids escaping the
+ * content inside a JSON string, which wastes tokens and invites mistakes.
+ */
+function fileResult(result) {
+  const { content, ...meta } = result;
+  if (content === null || content === undefined) {
+    return { content: [json(meta)] };
+  }
+  if (meta.truncated) {
+    meta.nextOffset = meta.offset + meta.returned;
+  }
+  return { content: [text(content), json(meta)] };
+}
+
+/**
+ * Every tool the connector offers. `write` tools are only registered when the
+ * service is not read-only, so a read-only deployment never even advertises
+ * them to the model.
+ */
+export function defineTools(service) {
+  return [
+    {
+      name: "list_drives",
+      title: "List drives",
+      description:
+        "List the VoltDrive drives available to this connector. Returns each drive's id, name and aliases. Start here.",
+      inputSchema: {},
+      annotations: READ,
+      handler: async () => jsonResult({ drives: await service.listDrives() })
+    },
+    {
+      name: "get_drive_status",
+      title: "Get drive status",
+      description:
+        "Summary of a drive: number of files and folders, total size, its sync settings (size limit, binary files, versioning) and whether a VoltDrive client on the connected Volt is idle or still syncing.",
+      inputSchema: { drive },
+      annotations: READ,
+      handler: async ({ drive: ref }) => jsonResult(await service.getDriveStatus(ref))
+    },
+    {
+      name: "list_directory",
+      title: "List a folder",
+      description:
+        "List the files and folders directly inside a folder of a drive (the drive root if path is empty). Set recursive to list everything beneath it.",
+      inputSchema: {
+        drive,
+        path: z.string().optional().describe("Folder path; omit or leave empty for the drive root."),
+        recursive: z.boolean().optional().describe("List all descendants, not just direct children. Default false."),
+        max_entries: z.number().int().min(1).max(2000).optional().describe("Most entries to return. Default 500.")
+      },
+      annotations: READ,
+      handler: async (args) =>
+        jsonResult(
+          await service.listDirectory(args.drive, args.path ?? "", {
+            recursive: args.recursive ?? false,
+            maxEntries: args.max_entries ?? 500
+          })
+        )
+    },
+    {
+      name: "read_file",
+      title: "Read a file",
+      description:
+        "Read a file from a drive. Text files are returned as text. Binary files return only their metadata unless encoding is 'base64'. Large files are returned in pieces: when the result is truncated, call again with offset set to nextOffset.",
+      inputSchema: {
+        drive,
+        path,
+        offset: z.number().int().min(0).optional().describe("Where to start: character offset for text, byte offset for base64. Default 0."),
+        limit: z.number().int().min(1).optional().describe("Most characters (text) or bytes (base64) to return. Capped by the server."),
+        encoding: z.enum(["utf-8", "base64"]).optional().describe("'utf-8' (default) for text, 'base64' to fetch the raw bytes of a binary file.")
+      },
+      annotations: READ,
+      handler: async (args) =>
+        fileResult(
+          await service.readFile(args.drive, args.path, {
+            offset: args.offset ?? 0,
+            limit: args.limit,
+            encoding: args.encoding ?? "utf-8"
+          })
+        )
+    },
+    {
+      name: "search_files",
+      title: "Search files",
+      description:
+        "Find files in a drive by name and/or by text content. name_pattern is a substring or a glob such as '*.md' or 'docs/**/*.txt'. content_query is a case-insensitive text search that scans text files only (binary and very large files are skipped and counted in the result).",
+      inputSchema: {
+        drive,
+        name_pattern: z.string().optional().describe("Substring or glob to match against file names or paths."),
+        content_query: z.string().optional().describe("Text to look for inside files."),
+        path: z.string().optional().describe("Only search beneath this folder."),
+        max_results: z.number().int().min(1).max(500).optional().describe("Most results to return. Default 50.")
+      },
+      annotations: READ,
+      handler: async (args) =>
+        jsonResult(
+          await service.searchFiles(args.drive, {
+            namePattern: args.name_pattern ?? "",
+            contentQuery: args.content_query ?? "",
+            path: args.path ?? "",
+            maxResults: args.max_results ?? 50
+          })
+        )
+    },
+    {
+      name: "list_file_versions",
+      title: "List file versions",
+      description:
+        "List the saved versions of a file, newest first. Only available on drives that have file versioning enabled.",
+      inputSchema: {
+        drive,
+        path,
+        limit: z.number().int().min(1).max(200).optional().describe("Most versions to return. Default 50."),
+        offset: z.number().int().min(0).optional().describe("Versions to skip from the newest. Default 0.")
+      },
+      annotations: READ,
+      handler: async (args) =>
+        jsonResult(
+          await service.listFileVersions(args.drive, args.path, {
+            limit: args.limit ?? 50,
+            offset: args.offset ?? 0
+          })
+        )
+    },
+    {
+      name: "read_file_version",
+      title: "Read an earlier version of a file",
+      description:
+        "Read the text of a file as it was at a saved version (see list_file_versions). Text files only.",
+      inputSchema: {
+        drive,
+        path,
+        version_id: z.string().describe("A versionId from list_file_versions."),
+        offset: z.number().int().min(0).optional().describe("Character offset to start from. Default 0."),
+        limit: z.number().int().min(1).optional().describe("Most characters to return. Capped by the server.")
+      },
+      annotations: READ,
+      handler: async (args) =>
+        fileResult(
+          await service.readFileVersion(args.drive, args.path, args.version_id, {
+            offset: args.offset ?? 0,
+            limit: args.limit
+          })
+        )
+    },
+
+    // ----------------------------------------------------------- write tools
+    {
+      name: "write_file",
+      title: "Create or replace a file",
+      description:
+        "Create a file, or replace the whole content of an existing one. Existing files are only replaced when overwrite is true, so read the file first and keep unrelated content. Missing parent folders are created. For binary data pass base64 content with encoding 'base64'. The change syncs to everyone who has the drive.",
+      write: true,
+      inputSchema: {
+        drive,
+        path,
+        content: z.string().describe("The complete new content of the file."),
+        encoding: z.enum(["utf-8", "base64"]).optional().describe("How content is encoded: 'utf-8' (default) for text, 'base64' for bytes."),
+        overwrite: z.boolean().optional().describe("Replace the file if it already exists. Default false.")
+      },
+      annotations: DESTRUCTIVE,
+      handler: async (args) =>
+        jsonResult(
+          await service.writeFile(args.drive, args.path, {
+            content: args.content,
+            encoding: args.encoding ?? "utf-8",
+            overwrite: args.overwrite ?? false
+          })
+        )
+    },
+    {
+      name: "create_folder",
+      title: "Create a folder",
+      description:
+        "Create a folder, including any missing parents. Does nothing if the folder already exists.",
+      write: true,
+      inputSchema: { drive, path },
+      annotations: IDEMPOTENT_ADDITIVE,
+      handler: async (args) => jsonResult(await service.createFolder(args.drive, args.path))
+    },
+    {
+      name: "move_path",
+      title: "Move or rename a file or folder",
+      description:
+        "Rename or move a file or folder to a new full path. The destination must not already exist. Moving a folder moves everything in it.",
+      write: true,
+      inputSchema: {
+        drive,
+        from: z.string().describe("Current path of the file or folder."),
+        to: z.string().describe("New full path, including the new name.")
+      },
+      annotations: ADDITIVE,
+      handler: async (args) => jsonResult(await service.movePath(args.drive, args.from, args.to))
+    },
+    {
+      name: "delete_path",
+      title: "Delete a file or folder",
+      description:
+        "Delete a file, or a folder and everything in it. A folder that is not empty is only deleted when recursive is true. Deleting syncs to everyone who has the drive; confirm with the user first unless they have clearly asked for it.",
+      write: true,
+      inputSchema: {
+        drive,
+        path,
+        recursive: z.boolean().optional().describe("Allow deleting a folder that contains files. Default false.")
+      },
+      annotations: DESTRUCTIVE,
+      handler: async (args) =>
+        jsonResult(
+          await service.deletePath(args.drive, args.path, {
+            recursive: args.recursive ?? false
+          })
+        )
+    },
+    {
+      name: "create_file_version",
+      title: "Save a version of a file",
+      description:
+        "Save a named checkpoint of a file's current content so it can be restored later. Only available on drives with file versioning enabled.",
+      write: true,
+      inputSchema: {
+        drive,
+        path,
+        label: z.string().optional().describe("A short description of this version.")
+      },
+      annotations: ADDITIVE,
+      handler: async (args) =>
+        jsonResult(await service.createFileVersion(args.drive, args.path, args.label ?? ""))
+    },
+    {
+      name: "revert_file_version",
+      title: "Revert a file to a saved version",
+      description:
+        "Replace a file's content with that of a saved version (see list_file_versions). Current content is replaced, so save a version first if it should be kept.",
+      write: true,
+      inputSchema: {
+        drive,
+        path,
+        version_id: z.string().describe("A versionId from list_file_versions.")
+      },
+      annotations: DESTRUCTIVE,
+      handler: async (args) =>
+        jsonResult(await service.revertFileVersion(args.drive, args.path, args.version_id))
+    }
+  ];
+}
+
+/**
+ * Turn anything a tool throws into a result with `isError`. Errors the
+ * connector raises itself (`DriveError`) carry messages written for the model;
+ * anything else is reported with its message but logged in full.
+ */
+function guard(handler, name, logger) {
+  return async (args) => {
+    try {
+      return await handler(args ?? {});
+    } catch (err) {
+      if (err instanceof DriveError) {
+        return errorResult(err.message);
+      }
+      logger?.error?.(`tool ${name} failed: ${err?.stack ?? err}`);
+      return errorResult(`${name} failed: ${err?.message ?? String(err)}`);
+    }
+  };
+}
+
+/**
+ * Build an MCP server exposing `service`'s drives. Contains no transport
+ * logic, so the same server is served over stdio or HTTP.
+ *
+ * @param {import("./drive-service.js").DriveService} service
+ * @param {{ logger?: object }} [options]
+ * @returns {McpServer}
+ */
+export function createServer(service, { logger } = {}) {
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
+
+  for (const tool of defineTools(service)) {
+    if (tool.write && service.readOnly) {
+      continue;
+    }
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: tool.annotations
+      },
+      guard(tool.handler, tool.name, logger)
+    );
+  }
+
+  return server;
+}