REMnux MCP Server

Instructions

Implementation Reference

• src/handlers/get-tool-help.ts:9-82 (handler)

  Main handler implementation that executes a REMnux tool with --help or -h flags to retrieve usage information. Validates tool name format, handles timeouts, detects if tool is not installed (exit code 127), and returns formatted response with help output or appropriate error messages.

  export async function handleGetToolHelp(
    deps: HandlerDeps,
    args: GetToolHelpArgs,
  ) {
    const startTime = Date.now();
    try {
      const { connector } = deps;
      const tool = args.tool;
  
      if (!TOOL_NAME_RE.test(tool)) {
        return formatError("get_tool_help", new REMnuxError(
          `Invalid tool name: "${tool}". Use a simple name like 'capa' or 'pdfid.py' (no paths, flags, or shell metacharacters).`,
          "INVALID_INPUT",
          "validation",
          "Provide just the tool name, e.g., 'olevba' not 'olevba -a'",
        ), startTime);
      }
  
      // Try --help first, fall back to -h
      let output = "";
      let exitCode = 0;
  
      for (const flag of ["--help", "-h"]) {
        try {
          const result = await connector.execute([tool, flag], { timeout: 10000 });
          const combined = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
          exitCode = result.exitCode;
  
          // Detect tool not installed (exit code 127 is the standard shell signal)
          if (result.exitCode === 127) {
            return formatError("get_tool_help", new REMnuxError(
              `Tool '${tool}' not found. It may not be installed on this REMnux system.`,
              "NOT_FOUND",
              "not_found",
              "Use check_tools to see installed tools, or install with apt/pip",
            ), startTime);
          }
  
          if (combined) {
            output = combined;
            break;
          }
        } catch (error) {
          const msg = error instanceof Error ? error.message : String(error);
          if (/timeout/i.test(msg)) {
            return formatError("get_tool_help", new REMnuxError(
              `Timed out running '${tool} ${flag}'`,
              "COMMAND_TIMEOUT",
              "timeout",
              "The tool may require input or not support help flags",
            ), startTime);
          }
          // Continue to next flag
        }
      }
  
      if (!output) {
        return formatError("get_tool_help", new REMnuxError(
          `No help output from '${tool}'. The tool may not be installed or may not support --help/-h.`,
          "EMPTY_OUTPUT",
          "tool_failure",
          "Check that the tool is installed with check_tools, or try run_tool with a specific command",
        ), startTime);
      }
  
      return formatResponse("get_tool_help", {
        tool,
        help: output,
        exit_code: exitCode,
      }, startTime);
    } catch (error) {
      return formatError("get_tool_help", toREMnuxError(error, deps.config.mode), startTime);
    }
  }

• src/schemas/tools.ts:86-91 (schema)

  Schema definition for get_tool_help tool. Defines a single 'tool' parameter as a string that accepts tool names like 'capa', 'pdfid.py', or 'olevba' and returns the tool's --help output.

  export const getToolHelpSchema = z.object({
    tool: z.string().describe(
      "Tool name (e.g., 'capa', 'pdfid.py', 'olevba'). Returns the tool's --help output."
    ),
  });
  export type GetToolHelpArgs = z.infer<typeof getToolHelpSchema>;

• src/index.ts:208-215 (registration)

  Tool registration in the MCP server. Registers 'get_tool_help' with a description explaining it returns --help output to understand available flags, options, and usage patterns, using the getToolHelpSchema for input validation and handleGetToolHelp as the handler function.

  // Tool: get_tool_help - Get usage help for a REMnux tool
  server.tool(
    "get_tool_help",
    "Get usage help for a REMnux tool. Returns the tool's --help output " +
    "so you can understand available flags, options, and usage patterns.",
    getToolHelpSchema.shape,
    (args) => handleGetToolHelp(deps, args)
  );