REMnux MCP Server

Instructions

Implementation Reference

• src/handlers/download-from-url.ts:95-219 (handler)

  Main handler function handleDownloadFromUrl that implements the download_from_url tool. Validates URL/headers/filename, executes download via curl or thug, gathers file metadata, and returns formatted response. Includes helper functions validateUrl (33-51), validateHeader (57-69), deriveFilename (75-93), handleThugDownload (224-314), and gatherFileInfo (319-365).
  export async function handleDownloadFromUrl( deps: HandlerDeps, args: DownloadFromUrlArgs, ) { const startTime = Date.now(); const { connector, config } = deps; const method = args.method ?? "curl"; try { // Validate URL const urlValidation = validateUrl(args.url); if (!urlValidation.valid) { return formatError("download_from_url", new REMnuxError( urlValidation.error!, "INVALID_URL", "validation", "Provide a valid http:// or https:// URL", ), startTime); } // Validate headers if provided const headers = args.headers ?? []; for (const h of headers) { const hv = validateHeader(h); if (!hv.valid) { return formatError("download_from_url", new REMnuxError( hv.error!, "INVALID_HEADER", "validation", "Headers must be 'Name: value' format without control characters or single quotes", ), startTime); } } // Determine filename const filename = args.filename ?? deriveFilename(args.url); const fnValidation = validateFilename(filename); if (!fnValidation.valid) { return formatError("download_from_url", new REMnuxError( fnValidation.error || "Invalid filename", "INVALID_FILENAME", "validation", "Use alphanumeric characters, hyphens, underscores, and dots only", ), startTime); } const filePath = `${config.samplesDir}/${filename}`; // Check if file exists (unless overwrite) if (!args.overwrite) { try { const checkResult = await connector.execute(["test", "-e", filePath], { timeout: 5000 }); if (checkResult.exitCode === 0) { return formatError("download_from_url", new REMnuxError( `File already exists: ${filename}. Use overwrite=true to replace.`, "FILE_EXISTS", "validation", "Set overwrite=true or choose a different filename", ), startTime); } } catch { // test command failed — file doesn't exist, proceed } } // Ensure samples dir exists try { await connector.execute(["mkdir", "-p", config.samplesDir], { timeout: 5000 }); } catch { // ignore — real errors surface below } if (method === "thug") { return await handleThugDownload(deps, args, headers, filename, filePath, startTime); } // ── Curl path ────────────────────────────────────────────────────────── const timeoutSecs = args.timeout ?? config.timeout; // Build curl command const headerFlags = headers.map(h => `-H '${h}'`).join(" "); const curlCmd = [ "curl -sSfL", `--max-filesize ${MAX_FILESIZE}`, `--max-redirs ${MAX_REDIRS}`, `--max-time ${timeoutSecs}`, headerFlags, `-o '${filePath}'`, `'${args.url}'`, ].filter(Boolean).join(" "); const result = await connector.executeShell(curlCmd, { timeout: (timeoutSecs + 10) * 1000, // shell timeout slightly longer than curl timeout cwd: config.samplesDir, }); if (result.exitCode !== 0) { // Clean up partial file left by curl try { await connector.execute(["rm", "-f", filePath], { timeout: 5000 }); } catch { /* ignore cleanup errors */ } const curlError = CURL_ERRORS[result.exitCode] || `curl failed with exit code ${result.exitCode}`; const stderr = result.stderr?.trim() || ""; return formatError("download_from_url", new REMnuxError( `Download failed: ${curlError}${stderr ? ` — ${stderr}` : ""}`, "DOWNLOAD_FAILED", "tool_failure", "Check that the URL is accessible and the server is responding", ), startTime); } // Gather file info (same pattern as get-file-info.ts) const info = await gatherFileInfo(connector, filePath, filename); return formatResponse("download_from_url", { method: "curl", url: args.url, ...info, }, startTime); } catch (error) { return formatError("download_from_url", toREMnuxError(error, deps.config.mode), startTime); } }
• src/schemas/tools.ts:64-84 (schema)

  Zod schema definition for downloadFromUrlSchema with fields: url (required), filename (optional), headers (optional array), method (optional: 'curl' or 'thug'), overwrite (optional boolean), and timeout (optional number). Also exports DownloadFromUrlArgs type.
  export const downloadFromUrlSchema = z.object({ url: z.string().url().describe("URL to download (http or https only)"), filename: z.string().optional().describe( "Override filename in samples dir. If omitted, derived from URL path." ), headers: z.array(z.string()).optional().describe( "Custom HTTP headers as 'Name: value' strings. " + "Example: ['User-Agent: Mozilla/5.0', 'X-Auth-Token: abc123']" ), method: z.enum(["curl", "thug"]).optional().default("curl").describe( "Download method. 'curl' (default) for direct HTTP download. " + "'thug' for sites requiring JavaScript execution (uses thug honeyclient)." ), overwrite: z.boolean().optional().default(false).describe( "Whether to overwrite if file exists. Default: false" ), timeout: z.number().optional().describe( "Download timeout in seconds (default: server timeout)" ), }); export type DownloadFromUrlArgs = z.input<typeof downloadFromUrlSchema>;
• src/index.ts:158-166 (registration)

  Tool registration in the MCP server where download_from_url is registered with description, schema shape, and handler function mapping to handleDownloadFromUrl.
  // Tool: download_from_url - Download a file from a URL into samples server.tool( "download_from_url", "Download a file from a URL into the samples directory for analysis. " + "Returns file metadata (hashes, type, size). Supports custom HTTP headers " + "and an optional thug mode for sites requiring JavaScript execution.", downloadFromUrlSchema.shape, (args) => handleDownloadFromUrl(deps, args) );