whisper-windows-mcp 2.2.2 → 2.4.0

package/dist/lib.d.ts

@@ -0,0 +1,37 @@
+/** Coerce a tool arg to a finite number, or undefined if it isn't one (rejects NaN/Infinity from bad input). */
+export declare function coerceNum(v: unknown): number | undefined;
+/**
+ * Write JSON atomically (unique temp file + rename).
+ * The rename makes the swap atomic at the filesystem level so a reader in ANOTHER
+ * process never sees a half-written, torn file. The random temp suffix keeps two
+ * writing processes from colliding on a shared temp name.
+ * (Within a single Node process these writes are already serialized — writeFileSync
+ * is synchronous and cannot interleave with another call on the event loop.)
+ */
+export declare function writeJsonAtomic(path: string, obj: unknown): void;
+/** Estimate word count from transcript text. */
+export declare function estimateWordCount(text: string): number;
+/**
+ * Deterministic serialization with sorted keys: the SAME logical arguments produce the
+ * SAME string regardless of the order the JSON keys were emitted in.
+ */
+export declare function stableStringify(value: unknown): string;
+/** Stable identity for a single privacy-gated operation: tool name + the full argument set. */
+export declare function opKeyFor(tool: string, args: unknown): string;
+/**
+ * True if `child` resolves to a path strictly inside `parent` (not parent itself).
+ * Normalizes both paths and uses relative() so a sibling-prefix dir ("models-evil")
+ * cannot satisfy the check the way a naive startsWith(parent) would. Windows-safe
+ * (drive-letter case handled by resolve/relative). NOTE: this is path-string
+ * containment, not symlink-resolved — a junction inside parent is not followed.
+ */
+export declare function isInsideDir(child: string, parent: string): boolean;
+/** Recover the timestamped transcript lines from a whisper-cli log (drops diagnostic noise). */
+export declare function extractTranscriptFromLog(logContent: string): string;
+/** Largest start-timestamp (in whole seconds) seen in a whisper-cli log — the progress signal. */
+export declare function parseLastTimestamp(logContent: string): number;
+/** Format seconds as M:SS, or H:MM:SS past an hour. Zero/falsy → "?:??". */
+export declare function formatDuration(sec: number): string;
+export declare function estimateSec(durationSec: number, gpu: boolean): number;
+/** estimateSec as a short human string ("~45s" / "~6m"); "?" when the duration is unknown. */
+export declare function estimateTime(durationSec: number, gpu: boolean): string;

package/dist/lib.js

@@ -0,0 +1,123 @@
+/**
+ * whisper-windows-mcp — pure logic library
+ *
+ * Side-effect-free (or fs-only) functions extracted from index.ts so they can be
+ * unit-tested directly. No MCP/server/process state lives here. index.ts imports
+ * these; the test suite (test/lib.test.mjs) imports the compiled dist/lib.js.
+ */
+import { resolve, relative, isAbsolute } from "path";
+import { writeFileSync, renameSync } from "fs";
+import { createHash, randomUUID } from "crypto";
+/** Coerce a tool arg to a finite number, or undefined if it isn't one (rejects NaN/Infinity from bad input). */
+export function coerceNum(v) {
+    // Only accept real numbers and numeric strings. Reject null / "" / booleans / arrays /
+    // objects — Number() would silently coerce null, "", and [] to 0, which is loose input
+    // we do not want reaching whisper-cli as a deliberate-looking 0.
+    if (typeof v !== "number" && typeof v !== "string")
+        return undefined;
+    if (typeof v === "string" && v.trim() === "")
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Write JSON atomically (unique temp file + rename).
+ * The rename makes the swap atomic at the filesystem level so a reader in ANOTHER
+ * process never sees a half-written, torn file. The random temp suffix keeps two
+ * writing processes from colliding on a shared temp name.
+ * (Within a single Node process these writes are already serialized — writeFileSync
+ * is synchronous and cannot interleave with another call on the event loop.)
+ */
+export function writeJsonAtomic(path, obj) {
+    const tmp = `${path}.${randomUUID().slice(0, 8)}.tmp`;
+    writeFileSync(tmp, JSON.stringify(obj, null, 2), "utf8");
+    renameSync(tmp, path);
+}
+/** Estimate word count from transcript text. */
+export function estimateWordCount(text) {
+    return text.split(/\s+/).filter((w) => w.trim().length > 0).length;
+}
+/**
+ * Deterministic serialization with sorted keys: the SAME logical arguments produce the
+ * SAME string regardless of the order the JSON keys were emitted in.
+ */
+export function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return "[" + value.map(stableStringify).join(",") + "]";
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return "{" + keys.map(k => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+/** Stable identity for a single privacy-gated operation: tool name + the full argument set. */
+export function opKeyFor(tool, args) {
+    return createHash("sha256").update(tool + "\0" + stableStringify(args)).digest("hex");
+}
+/**
+ * True if `child` resolves to a path strictly inside `parent` (not parent itself).
+ * Normalizes both paths and uses relative() so a sibling-prefix dir ("models-evil")
+ * cannot satisfy the check the way a naive startsWith(parent) would. Windows-safe
+ * (drive-letter case handled by resolve/relative). NOTE: this is path-string
+ * containment, not symlink-resolved — a junction inside parent is not followed.
+ */
+export function isInsideDir(child, parent) {
+    const rel = relative(resolve(parent), resolve(child));
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/** Recover the timestamped transcript lines from a whisper-cli log (drops diagnostic noise). */
+export function extractTranscriptFromLog(logContent) {
+    return logContent
+        .split(/\r?\n/)
+        .filter((l) => /^\[\d{2}:\d{2}:\d{2}\.\d{3} --> /.test(l))
+        .join("\n");
+}
+/** Largest start-timestamp (in whole seconds) seen in a whisper-cli log — the progress signal. */
+export function parseLastTimestamp(logContent) {
+    const re = /\[(\d{2}):(\d{2}):(\d{2})\.\d{3} -->/g;
+    let lastSec = 0;
+    let m;
+    while ((m = re.exec(logContent)) !== null) {
+        const sec = parseInt(m[1], 10) * 3600 + parseInt(m[2], 10) * 60 + parseInt(m[3], 10);
+        if (sec > lastSec)
+            lastSec = sec;
+    }
+    return lastSec;
+}
+/** Format seconds as M:SS, or H:MM:SS past an hour. Zero/falsy → "?:??". */
+export function formatDuration(sec) {
+    if (!sec)
+        return "?:??";
+    const h = Math.floor(sec / 3600);
+    const m = Math.floor((sec % 3600) / 60);
+    const s = Math.floor(sec % 60);
+    if (h > 0)
+        return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+    return `${m}:${String(s).padStart(2, "0")}`;
+}
+/**
+ * Rough transcription-time estimate in SECONDS = a fixed model-LOAD cost + a per-second transcribe
+ * rate. The load cost is what actually drives timeouts: whisper-cli reloads the model on EVERY
+ * invocation (it is a one-shot CLI, no daemon), and loading large-v3 (2.9 GB) into a memory-
+ * constrained GPU was MEASURED at ~2 min on a Vega 56 — so a 7:29 file's whisper-cli ran 3:56 total
+ * (≈2 min load + ~2 min transcribe), tipping just past the 4-min MCP wall. Transcription speed was
+ * never the bottleneck; the reload tax was. Conservative so it does not under-predict; the real
+ * figures vary by model + hardware. (Calibration history: 0.12 then 0.40 then 0.60 single-ratio
+ * guesses all mis-modeled this as a realtime factor before the components were measured.)
+ */
+const MODEL_LOAD_SEC_GPU = 110; // fixed per-invocation model-load allowance, GPU (measured ~120s on a constrained 8 GB card)
+const MODEL_LOAD_SEC_CPU = 30; // CPU loads from system RAM — far cheaper than a constrained VRAM upload
+export function estimateSec(durationSec, gpu) {
+    if (!durationSec)
+        return 0;
+    const load = gpu ? MODEL_LOAD_SEC_GPU : MODEL_LOAD_SEC_CPU;
+    const transcribeRatio = gpu ? 0.3 : 1.5;
+    return Math.round(load + durationSec * transcribeRatio);
+}
+/** estimateSec as a short human string ("~45s" / "~6m"); "?" when the duration is unknown. */
+export function estimateTime(durationSec, gpu) {
+    if (!durationSec)
+        return "?";
+    const est = estimateSec(durationSec, gpu);
+    return est < 60 ? `~${est}s` : `~${Math.round(est / 60)}m`;
+}

package/package.json

@@ -1,45 +1,46 @@
-{
-  "name": "whisper-windows-mcp",
-  "version": "2.2.2",
-  "description": "Windows-native MCP server for local audio transcription using whisper.cpp with Vulkan GPU acceleration",
-  "main": "dist/index.js",
-  "bin": {
-    "whisper-windows-mcp": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js"
-  },
-  "keywords": [
-    "mcp",
-    "whisper",
-    "windows",
-    "transcription",
-    "speech-to-text",
-    "audio",
-    "video",
-    "claude",
-    "claude-desktop",
-    "model-context-protocol",
-    "whisper-cpp",
-    "vulkan",
-    "gpu",
-    "local-ai",
-    "batch-transcription",
-    "subtitle",
-    "srt",
-    "multilingual"
-  ],
-  "author": "eviscerations",
-  "license": "SEE LICENSE IN LICENSE",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "@types/node": "^20.0.0"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "whisper-windows-mcp",
+  "version": "2.4.0",
+  "description": "Windows-native MCP server for local audio transcription using whisper.cpp with Vulkan GPU acceleration",
+  "main": "dist/index.js",
+  "bin": {
+    "whisper-windows-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "tsc && node --test"
+  },
+  "keywords": [
+    "mcp",
+    "whisper",
+    "windows",
+    "transcription",
+    "speech-to-text",
+    "audio",
+    "video",
+    "claude",
+    "claude-desktop",
+    "model-context-protocol",
+    "whisper-cpp",
+    "vulkan",
+    "gpu",
+    "local-ai",
+    "batch-transcription",
+    "subtitle",
+    "srt",
+    "multilingual"
+  ],
+  "author": "eviscerations",
+  "license": "SEE LICENSE IN LICENSE",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/patch_roadmaps.py

@@ -1,72 +0,0 @@
-#!/usr/bin/env python3
-"""
-patch_roadmaps.py
-Adds new language entries to the multilingual documentation tracking section
-in existing ROADMAP files. Run from the repo root. Outputs to ./patched_output/.
-
-NOTE: ROADMAP.pl.md and ROADMAP.ro.md are NOT in the target list because those
-files were generated fresh with the complete language list already included.
-Only the previously-existing ROADMAPs need patching.
-"""
-
-import os
-
-NEW_ENTRIES = [
-    "**Polish (`*.pl.md`)** — `README.pl.md` / `TROUBLESHOOTING.pl.md` / `ROADMAP.pl.md` / `PRIVACY.pl.md` / `SECURITY.pl.md`",
-    "**Romanian (`*.ro.md`)** — `README.ro.md` / `TROUBLESHOOTING.ro.md` / `ROADMAP.ro.md` / `PRIVACY.ro.md` / `SECURITY.ro.md`",
-]
-
-# Only patch the previously-existing ROADMAPs.
-# ROADMAP.pl.md and ROADMAP.ro.md are excluded — they were generated with
-# the full language list already in their native languages.
-ROADMAP_FILES = {
-    "ROADMAP.md":       "Community contributions for other languages welcome.",
-    "ROADMAP.ja.md":    "他の言語へのコミュニティ貢献を歓迎します。",
-    "ROADMAP.ko.md":    "다른 언어로의 커뮤니티 기여를 환영합니다.",
-    "ROADMAP.vi.md":    "Chào mừng đóng góp cộng đồng cho các ngôn ngữ khác.",
-    "ROADMAP.id.md":    "Kontribusi komunitas untuk bahasa lain disambut.",
-    "ROADMAP.uk.md":    "Внески спільноти для інших мов вітаються.",
-    "ROADMAP.pt-BR.md": "Contribuições da comunidade para outros idiomas são bem-vindas.",
-    "ROADMAP.es.md":    "Las contribuciones de la comunidad para otros idiomas son bienvenidas.",
-}
-
-OUTPUT_DIR = "patched_output"
-
-def patch_roadmap(filename, marker, entries):
-    with open(filename, "r", encoding="utf-8") as f:
-        content = f.read()
-    if marker not in content:
-        print(f"  WARNING: marker not found in {filename} — skipping")
-        return None
-    to_insert = [e for e in entries if e.split("(")[0].strip() not in content]
-    if not to_insert:
-        print(f"  INFO: all entries already present in {filename} — skipping")
-        return content
-    insert_block = "\n".join(to_insert) + "\n\n"
-    return content.replace(marker, f"{insert_block}{marker}")
-
-def main():
-    os.makedirs(OUTPUT_DIR, exist_ok=True)
-    print(f"Output directory: {OUTPUT_DIR}/")
-    print(f"Processing {len(ROADMAP_FILES)} ROADMAP files...\n")
-    success = 0
-    for filename, marker in ROADMAP_FILES.items():
-        if not os.path.exists(filename):
-            print(f"  MISSING: {filename} — skipping")
-            continue
-        print(f"  Patching {filename}...")
-        patched = patch_roadmap(filename, marker, NEW_ENTRIES)
-        if patched is None:
-            continue
-        out_path = os.path.join(OUTPUT_DIR, filename)
-        with open(out_path, "w", encoding="utf-8") as f:
-            f.write(patched)
-        print(f"  OK -> {out_path}")
-        success += 1
-    print(f"\nDone. {success}/{len(ROADMAP_FILES)} files patched.")
-    print(f"\nReview files in ./{OUTPUT_DIR}/ before replacing originals.")
-    print("To replace originals (cmd.exe):")
-    print(f"  copy /Y {OUTPUT_DIR}\\ROADMAP*.md .")
-
-if __name__ == "__main__":
-    main()