check_system

Instructions

Implementation Reference

• src/index.ts:1071-1079 (schema)

  Registration of the 'check_system' tool in ListToolsRequestSchema handler. Defines the tool name, description (detect GPU hardware, VRAM, Vulkan status, recommended model), and empty inputSchema.

  {
    name: "check_system",
    description:
      "Detect GPU hardware and verify Vulkan acceleration is available. " +
      "Reports GPU name, VRAM, whether the Vulkan binary is installed, " +
      "and recommends the best Whisper model for your hardware. " +
      "Run this if you want to confirm GPU acceleration is working or diagnose why it isn't.",
    inputSchema: { type: "object", properties: {} },
  },

• src/index.ts:1262-1297 (handler)

  Handler for the 'check_system' tool in CallToolRequestSchema. Calls hasVulkanDll() to check for ggml-vulkan.dll, calls detectGpus() to get GPU info via wmic, formats output with GPU name, VRAM, recommended model, and Vulkan status.

  // check_system
  // -------------------------------------------------------------------------
  if (name === "check_system") {
    const vulkan = hasVulkanDll();
    const gpus = await detectGpus();
  
    let gpuLines = "";
    if (gpus.length === 0) {
      gpuLines = "⚠️  No GPU detected via wmic — this may indicate a driver issue.\n";
    } else {
      for (const gpu of gpus) {
        const vramStr = formatVram(gpu.vramBytes);
        gpuLines += `🖥️  GPU:   ${gpu.name}\n`;
        gpuLines += `💾  VRAM:  ${vramStr} (reported by Windows — may be half of actual on AMD cards)\n`;
        if (gpu.vramBytes > 0) {
          gpuLines += `📦  Recommended model: ${recommendedModel(gpu.vramBytes)}\n`;
        }
        gpuLines += "\n";
      }
    }
  
    const vulkanLine = vulkan
      ? `✅ Vulkan binary:  ggml-vulkan.dll found — GPU acceleration is active`
      : `❌ Vulkan binary:  ggml-vulkan.dll NOT found — whisper is running CPU-only\n\n` +
        `   To enable GPU acceleration:\n` +
        `   Download whisper-vulkan-win-x64.zip from:\n` +
        `   https://github.com/eviscerations/whisper-windows-mcp/releases\n` +
        `   Extract to: ${dirname(WHISPER_CLI_PATH)}`;
  
    return {
      content: [{
        type: "text",
        text: `System check\n${"─".repeat(40)}\n\n${gpuLines}${vulkanLine}`,
      }],
    };
  }

• src/index.ts:504-530 (helper)

  The detectGpus() helper function used by check_system. Runs 'wmic path win32_VideoController get name,AdapterRAM /format:csv' to enumerate GPUs and their VRAM.

  interface GpuInfo {
    name: string;
    vramBytes: number;
  }
  
  async function detectGpus(): Promise<GpuInfo[]> {
    try {
      const { stdout } = await execFileAsync(
        "wmic",
        ["path", "win32_VideoController", "get", "name,AdapterRAM", "/format:csv"],
        { windowsHide: true }
      );
      const gpus: GpuInfo[] = [];
      for (const line of stdout.split(/\r?\n/)) {
        const trimmed = line.trim();
        if (!trimmed || trimmed.startsWith("Node") || trimmed.startsWith(",AdapterRAM")) continue;
        const parts = trimmed.split(",");
        if (parts.length < 3) continue;
        const vramBytes = parseInt(parts[1] ?? "0", 10) || 0;
        const name = (parts[2] ?? "").trim();
        if (name && name !== "Name") gpus.push({ name, vramBytes });
      }
      return gpus;
    } catch {
      return [];
    }
  }

• src/index.ts:532-536 (helper)

  The formatVram() helper used by check_system to format VRAM bytes into human-readable string.

  function formatVram(bytes: number): string {
    if (!bytes || bytes < 1024 * 1024) return "Unknown";
    const gb = bytes / (1024 * 1024 * 1024);
    return gb >= 1 ? `${gb.toFixed(1)} GB` : `${Math.round(bytes / (1024 * 1024))} MB`;
  }

• src/index.ts:538-544 (helper)

  The recommendedModel() helper used by check_system to recommend a Whisper model based on VRAM size.

  function recommendedModel(vramBytes: number): string {
    const gb = vramBytes / (1024 * 1024 * 1024);
    if (gb >= 6) return "large-v3-turbo (ggml-large-v3-turbo.bin) — ~6x faster than large-v3, minimal accuracy loss for English";
    if (gb >= 4) return "medium.en (ggml-medium.en.bin) — good fit for your VRAM";
    if (gb >= 2) return "small.en (ggml-small.en.bin) — safe choice for your VRAM";
    return "base.en (ggml-base.en.bin) — recommended for limited VRAM";
  }