REMnux MCP Server

Instructions

Implementation Reference

• src/handlers/list-files.ts:7-77 (handler)

  The main handler implementation that executes the list_files tool logic. It runs 'ls -la' on the specified directory (samples or output), parses the output into structured entries with name, size, date, type, and permissions, and returns formatted response or error.

  export async function handleListFiles(
    deps: HandlerDeps,
    args: ListFilesArgs
  ) {
    const startTime = Date.now();
    const { connector, config } = deps;
    const dir = args.directory === "samples" ? config.samplesDir : config.outputDir;
  
    try {
      const result = await connector.execute(["ls", "-la", dir], { timeout: 30000 });
  
      if (result.exitCode !== 0) {
        const stderr = result.stderr || "";
        const notFound = stderr.includes("No such file") || stderr.includes("cannot access");
        return formatError("list_files", new REMnuxError(
          notFound ? `Directory does not exist: ${dir}` : `ls failed: ${stderr}`,
          notFound ? "DIR_NOT_FOUND" : "COMMAND_FAILED",
          notFound ? "not_found" : "tool_failure",
          notFound ? "Upload a file first, or check the directory path" : undefined,
        ), startTime);
      }
  
      const raw = result.stdout || "";
  
      // Parse ls -la output into structured entries
      const lines = raw.split("\n").filter((l) => l.trim() !== "");
      const entries: Array<{ name: string; size: number; date: string; type: string; permissions: string }> = [];
  
      for (const line of lines) {
        // Skip "total N" line
        if (line.startsWith("total ")) continue;
  
        // ls -la format: permissions links owner group size month day time/year name
        const match = line.match(
          /^([drwxlsStT\-]+)\s+\d+\s+\S+\s+\S+\s+(\d+)\s+(\w+\s+\d+\s+\S+)\s+(.+)$/
        );
        if (match) {
          const [, permissions, size, date, name] = match;
          // Skip . and ..
          if (name === "." || name === "..") continue;
  
          // Strip symlink target (e.g., "link -> /outside/sandbox/target")
          let cleanName = name;
          if (permissions.startsWith("l") && name.includes(" -> ")) {
            cleanName = name.split(" -> ")[0];
          }
  
          let type = "file";
          if (permissions.startsWith("d")) type = "directory";
          else if (permissions.startsWith("l")) type = "symlink";
  
          entries.push({
            name: cleanName,
            size: parseInt(size, 10),
            date,
            type,
            permissions,
          });
        }
      }
  
      return formatResponse("list_files", {
        directory: args.directory,
        path: dir,
        entries,
        entry_count: entries.length,
      }, startTime);
    } catch (error) {
      return formatError("list_files", toREMnuxError(error), startTime);
    }
  }

• src/schemas/tools.ts:15-18 (schema)

  Schema definition for the list_files tool. Defines the input validation accepting a 'directory' parameter that must be either 'samples' or 'output', defaulting to 'samples'. Also exports the ListFilesArgs type inferred from the schema.

  export const listFilesSchema = z.object({
    directory: z.enum(["samples", "output"]).default("samples").describe("Which directory to list"),
  });
  export type ListFilesArgs = z.infer<typeof listFilesSchema>;

• src/index.ts:111-117 (registration)

  Registration of the list_files tool with the MCP server. Defines the tool name as 'list_files', provides a description, uses listFilesSchema.shape for input validation, and connects it to the handleListFiles handler function.

  // Tool: list_files - List files in samples or output directory
  server.tool(
    "list_files",
    "List files in samples or output directory",
    listFilesSchema.shape,
    (args) => handleListFiles(deps, args)
  );