switch_model

Instructions

Implementation Reference

• src/index.ts:1107-1127 (registration)

  Tool registration/definition for switch_model in ListToolsRequestSchema handler. Defines name, description, and inputSchema (model_name required string ending in .bin).

      {
        name: "switch_model",
        description:
          "Switch the active Whisper model for the current session without restarting Claude Desktop. " +
          "Accepts a model filename (e.g. ggml-large-v3-turbo.bin) or full path. " +
          "The model must already be installed in your models directory. " +
          "Use list_models to see installed models, download_model to add new ones. " +
          "Change is session-scoped — does not persist after Claude Desktop restarts.",
        inputSchema: {
          type: "object",
          properties: {
            model_name: {
              type: "string",
              description: "Model filename (e.g. ggml-large-v3-turbo.bin) or full path. Must be a .bin file in the configured models directory.",
            },
          },
          required: ["model_name"],
        },
      },
    ],
  }));

• src/index.ts:1478-1549 (handler)

  Handler function for switch_model called via CallToolRequestSchema. Validates input (must end in .bin, no path traversal), resolves to full path within models directory, checks model file exists and no transcription is running, then updates the mutable WHISPER_MODEL variable.

  if (name === "switch_model") {
    const modelInput = (args?.model_name as string)?.trim();
    if (!modelInput) return { content: [{ type: "text", text: "model_name is required." }], isError: true };
  
    // Security: must end in .bin
    if (!modelInput.endsWith(".bin")) {
      return {
        content: [{ type: "text", text: `Invalid model: "${modelInput}"\nModel files must end in .bin` }],
        isError: true,
      };
    }
  
    // Security: reject path traversal
    if (UNSAFE_PATH_RE.test(modelInput)) {
      return {
        content: [{ type: "text", text: `Invalid path: "${modelInput}"\nPaths containing ".." or UNC paths are not allowed.` }],
        isError: true,
      };
    }
  
    // Resolve to full path — either absolute or relative to models dir
    const modelsDir = dirname(WHISPER_MODEL);
    const resolvedPath = modelInput.includes("\\") || modelInput.includes("/")
      ? modelInput
      : join(modelsDir, modelInput);
  
    // Security: must live within the configured models directory
    if (!resolvedPath.startsWith(modelsDir)) {
      return {
        content: [{ type: "text", text: `Security error: model must be within the configured models directory (${modelsDir}).` }],
        isError: true,
      };
    }
  
    if (!existsSync(resolvedPath)) {
      return {
        content: [{
          type: "text",
          text:
            `Model not found: ${resolvedPath}\n\n` +
            `Use list_models to see installed models, or download_model to install a new one.`,
        }],
        isError: true,
      };
    }
  
    // Process lock — don't switch mid-transcription
    if (await isWhisperRunning()) {
      return {
        content: [{ type: "text", text: "Cannot switch model while a transcription is in progress. Wait for the current job to finish first." }],
        isError: true,
      };
    }
  
    const previousModel = basename(WHISPER_MODEL);
    WHISPER_MODEL = resolvedPath;
    const newModel = basename(WHISPER_MODEL);
    const sizeMb = (statSync(resolvedPath).size / (1024 * 1024)).toFixed(0);
    const known = MODEL_REGISTRY.find(m => m.filename === newModel);
  
    return {
      content: [{
        type: "text",
        text:
          `✅ Model switched!\n\n` +
          `Previous: ${previousModel}\n` +
          `Active:   ${newModel} (${sizeMb} MB)\n` +
          (known ? `Use case: ${known.useCase}\n` : "") +
          `\nThis change is session-scoped. To make it permanent, update WHISPER_MODEL in claude_desktop_config.json.`,
      }],
    };
  }

• src/index.ts:32-33 (helper)

  Mutable WHISPER_MODEL variable declared using 'let' (not const) to allow runtime update by switch_model handler. Initialized from WHISPER_MODEL environment variable.

  let WHISPER_MODEL =
    process.env.WHISPER_MODEL ?? "C:\\whisper\\models\\ggml-base.en.bin";