whisper-windows-mcp 1.9.0 → 2.2.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Something isn't working correctly
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## What happened
+
+<!-- Describe what went wrong -->
+
+## Steps to reproduce
+
+1. 
+2. 
+3. 
+
+## Expected behavior
+
+<!-- What should have happened instead -->
+
+## Environment
+
+- **OS:** Windows [version — run `winver`]
+- **Node.js:** [run `node --version`]
+- **whisper-windows-mcp version:** [shown in Claude Desktop Settings → Developer]
+- **GPU:** [model name]
+- **Vulkan build:** Yes / No
+- **Model:** [e.g. ggml-medium.en.bin, ggml-large-v3.bin]
+
+## Error output
+
+<!-- Paste any error messages here -->
+
+```
+error output here
+```
+
+## Additional context
+
+<!-- Anything else that might help — file format, file duration, language, etc. -->

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature request
+about: Suggest a new feature or improvement
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## What problem would this solve
+
+<!-- Describe the use case. What are you trying to do that isn't possible or is difficult right now? -->
+
+## Proposed solution
+
+<!-- How would you like this to work? Be as specific as you can. -->
+
+## Alternatives considered
+
+<!-- Have you tried other approaches? What didn't work? -->
+
+## Hardware context
+
+<!-- Relevant if this is GPU/model related -->
+- GPU: 
+- Model size you're using:
+
+## Additional context
+
+<!-- Anything else — links to similar implementations, whisper.cpp flags that might support this, etc. -->

package/.github/ISSUE_TEMPLATE/gpu_test_result.md

@@ -0,0 +1,32 @@
+---
+name: GPU test result
+about: Share your GPU acceleration test results to help other users
+title: '[GPU] '
+labels: hardware-report
+assignees: ''
+---
+
+## Hardware
+
+- **GPU:** 
+- **VRAM:** 
+- **CPU:** 
+- **RAM:** 
+
+## Test
+
+- **Model used:** [e.g. ggml-medium.en.bin, ggml-large-v3.bin]
+- **File duration:** [e.g. 5 minutes]
+- **Language:** 
+
+## Results
+
+- **GPU utilization during transcription:** [e.g. 20%]
+- **Time to complete:** 
+- **CPU utilization during transcription:** 
+- **Vulkan build:** Yes / No
+- **Any issues:** 
+
+## Notes
+
+<!-- Anything else worth knowing for users with similar hardware -->

package/.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## What this PR does
+
+<!-- Brief description of the change -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Other
+
+## Testing
+
+- [ ] Tested on Windows
+- [ ] Built successfully (`npm run build`)
+- [ ] Tested in Claude Desktop with a real audio file
+
+## Checklist
+
+- [ ] Version bumped in `package.json` and `src/index.ts`
+- [ ] README updated if new tools or parameters added
+- [ ] TROUBLESHOOTING.md updated if fixing a known issue
+- [ ] No new external runtime dependencies added
+
+## Related issues
+
+<!-- Closes #xxx -->

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+## Our standards
+
+This project is built to be useful to a wide range of people — developers, journalists, legal professionals, researchers, language students, video editors, and anyone else who needs local audio transcription on Windows.
+
+We expect contributors and community members to:
+
+- Be respectful and constructive in issues and pull requests
+- Focus feedback on the work, not the person
+- Accept that different people have different use cases and hardware setups
+- Help newcomers get set up — not everyone is a developer
+
+## Unacceptable behavior
+
+- Harassment, personal attacks, or discriminatory language
+- Dismissing bug reports because they involve non-English languages or non-NVIDIA hardware
+- Spam or off-topic promotion
+
+## Enforcement
+
+Issues or pull requests that violate these standards will be closed. Repeat violations may result in being blocked from the repository.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, open a private vulnerability report or contact the maintainer directly through GitHub.
+
+---
+
+This Code of Conduct is intentionally minimal. The goal is a functional, welcoming project — not bureaucracy.

package/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to whisper-windows-mcp
+
+Thanks for your interest in contributing. This is a Windows-native MCP server for local audio transcription — contributions that improve Windows compatibility, GPU support, and usability for non-technical users are especially welcome.
+
+---
+
+## Before you start
+
+Check the [open issues](https://github.com/eviscerations/whisper-windows-mcp/issues) before starting work to avoid duplicating effort. If you want to work on something not listed, open an issue first to discuss it.
+
+See [ROADMAP.md](ROADMAP.md) for planned features and known bugs.
+
+---
+
+## What we need most
+
+- **GPU acceleration testing** — if you've tested on NVIDIA, Intel Arc, or AMD hardware not listed in the README, please share your results (GPU model, VRAM, model size, observed throughput)
+- **Bug reports with reproduction steps** — especially for Windows-specific issues
+- **Multilingual testing** — results with non-English audio and the large-v3 model
+- **Documentation improvements** — especially for non-English speakers
+
+---
+
+## Development setup
+
+```
+git clone https://github.com/eviscerations/whisper-windows-mcp
+cd whisper-windows-mcp
+npm install
+npm run build
+```
+
+The server is a single TypeScript file at `src/index.ts`. The compiled output goes to `dist/`.
+
+To test locally, update your `claude_desktop_config.json` to point at the local build:
+
+```json
+{
+  "mcpServers": {
+    "whisper": {
+      "command": "node",
+      "args": ["C:\\path\\to\\whisper-windows-mcp\\dist\\index.js"],
+      "env": {
+        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
+        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-medium.en.bin"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after each build to pick up changes.
+
+---
+
+## Pull request guidelines
+
+- Keep PRs focused — one fix or feature per PR
+- Test on Windows (this is a Windows-only tool)
+- If adding a new tool, update the tool list in README.md
+- If fixing a bug, add a note to TROUBLESHOOTING.md if it's something other users will hit
+- Bump the version in `package.json` and the version string in `src/index.ts` before submitting
+
+---
+
+## Code style
+
+- TypeScript, no external runtime dependencies beyond `@modelcontextprotocol/sdk`
+- All file I/O must handle non-ASCII filenames (Unicode, Japanese, Chinese, emoji)
+- New tools go in the `CallToolRequestSchema` handler following the existing pattern
+- Error messages should be actionable — tell the user what to do, not just what went wrong
+
+---
+
+## Reporting bugs
+
+Open an issue with:
+- Your OS version (`winver`)
+- Node.js version (`node --version`)
+- whisper-windows-mcp version
+- GPU model and whether you're using the Vulkan build
+- Exact steps to reproduce
+- Full error output if available
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT license.

package/README.ja.md

@@ -0,0 +1,397 @@
+# whisper-windows-mcp
+
+Windows向けのネイティブMCP（Model Context Protocol）サーバーです。[whisper.cpp](https://github.com/ggml-org/whisper.cpp)を使用して、Claude Desktopで音声・動画ファイルをローカルに文字起こしできます。GPU加速、多言語対応、バッチ処理に対応しています。インターネット接続は不要です。音声データが外部に送信されることは一切ありません。
+
+> **なぜこのパッケージが存在するのか？**
+> 人気の`whisper-mcp`パッケージはmacOS向けに構築されており、Unix環境を前提としています。Windowsでは動作しません。このパッケージは、Claude DesktopでローカルなウィンドウズネイティブのAI文字起こしを求めるWindowsユーザーのために作られました。
+
+---
+
+## できること
+
+インストール後、Claude Desktopで以下のように話しかけるだけで使えます：
+
+- *「C:\Users\Me\Downloads\meeting.mp3を文字起こしして」*
+- *「このフォルダの録音ファイルをすべて文字起こしして、それぞれテキストファイルに保存して」*
+- *「このビデオの日本語と英語の字幕を生成して」*
+- *「このフォルダのバッチ文字起こしを開始して」*
+- *「これらのファイルの文字起こしにかかる時間はどれくらい？」*
+- *「GPU加速が有効か確認して」*
+- *「インストール済みのモデルを一覧表示して」*
+- *「large-v3-turboをダウンロードして」*
+- *「large-v3-turboモデルに切り替えて」*
+
+---
+
+## 必要条件
+
+1. **Node.js 18以降** — [nodejs.org](https://nodejs.org)
+2. **Vulkan GPU対応のwhisper.cppバイナリ** — ステップ1参照
+3. **Whisperモデルファイル** — ステップ2参照
+4. **FFmpeg** — 動画ファイルと非WAV/MP3音声に必要
+
+---
+
+## ステップ1 — whisper.cppバイナリのインストール
+
+### オプションA — ビルド済みVulkanリリース（推奨）
+
+[リリースページ](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0)から`whisper-vulkan-win-x64.zip`をダウンロードしてください。
+
+これは**Vulkan GPU加速**が有効なカスタムビルドです。AMD、NVIDIA、Intel GPUで動作します — ベンダー固有のSDKは不要です。
+
+`C:\whisper\Release\`に展開してください。以下のファイルが揃っているか確認してください：
+
+```
+C:\whisper\Release\whisper-cli.exe
+C:\whisper\Release\ggml-vulkan.dll
+C:\whisper\Release\ggml.dll
+C:\whisper\Release\ggml-base.dll
+C:\whisper\Release\ggml-cpu.dll
+C:\whisper\Release\whisper.dll
+```
+
+GPU加速は自動で有効になります — 追加設定は不要です。
+
+### オプションB — ソースからビルド
+
+必要なもの：Git、CMake、Visual Studio Build Tools 2022+（「C++によるデスクトップ開発」）、[lunarg.com](https://vulkan.lunarg.com/sdk/home#windows)のVulkan SDK。
+
+```
+git clone https://github.com/ggml-org/whisper.cpp
+cd whisper.cpp
+cmake -B build -DGGML_VULKAN=ON -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release --target whisper-cli
+```
+
+`build\bin\Release\`からバイナリを`C:\whisper\Release\`にコピーしてください。
+
+> **注意：** GitHubの公式whisper.cpp WindowsリリースにはVulkanビルドが含まれていません。上記のビルド済みリリースを使用するか、`-DGGML_VULKAN=ON`でソースからコンパイルする必要があります。
+
+---
+
+## ステップ2 — Whisperモデルのダウンロード
+
+| モデル | サイズ | 速度 | 精度 | 用途 |
+|---|---|---|---|---|
+| `ggml-tiny.en.bin` | 75 MB | 非常に高速 | 基本 | 動作確認 |
+| `ggml-base.en.bin` | 142 MB | 高速 | 良好 | 日常的な英語 |
+| `ggml-small.en.bin` | 466 MB | 中程度 | より良好 | 重要な録音 |
+| `ggml-medium.en.bin` | 1.5 GB | GPUで高速 | 非常に良好 | 最高品質の英語 |
+| `ggml-large-v3-turbo.bin` | 1.6 GB | GPUで高速 | 優秀 | **英語GPUバッチ処理の推奨 — large-v3の約6倍高速で精度損失は最小限** |
+| `ggml-large-v3.bin` | 2.9 GB | GPUで高速 | 優秀 | 多言語、最高精度 |
+| `ggml-medium.en-q5_0.bin` | 514 MB | 高速 | 非常に良好 | **CPU専用英語の最良選択 — 低メモリで高精度** |
+| `ggml-large-v3-turbo-q5_0.bin` | 547 MB | 高速 | 優秀 | **CPU専用多言語の最良選択** |
+| `ggml-large-v3-q5_0.bin` | 1.1 GB | CPUで中程度 | 優秀 | 多言語、CPU対応 |
+
+Claude Desktopで`download_model`を使用して直接インストールできます。**英語専用**の場合：`large-v3-turbo`（GPU）または`medium.en-q5_0`（CPU）がおすすめです。**多言語**の場合：`large-v3-turbo`または`large-v3-turbo-q5_0`（CPU）が必要です。英語専用モデル（`*.en.bin`）は英語以外の音声に`[FOREIGN]`を出力し、他の言語には使用できません。
+
+---
+
+## ステップ3 — FFmpegのインストール
+
+FFmpegは動画ファイルと非ネイティブ音声フォーマットに必要です。
+
+wingetでインストール：
+```
+winget install ffmpeg
+```
+
+または[ffmpeg.org](https://ffmpeg.org/download.html)からダウンロードしてPATHに追加してください。
+
+確認：
+```
+ffmpeg -version
+```
+
+---
+
+## ステップ4 — MCPサーバーのインストール
+
+```
+npm install -g whisper-windows-mcp
+```
+
+---
+
+## ステップ5 — Claude Desktopの設定
+
+Claude Desktop → 設定 → 開発者 → 設定を編集。
+
+`whisper`エントリを追加してください：
+
+```json
+{
+  "mcpServers": {
+    "whisper": {
+      "command": "npx",
+      "args": ["-y", "whisper-windows-mcp"],
+      "env": {
+        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
+        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-medium.en.bin"
+      }
+    }
+  }
+}
+```
+
+設定ファイルの場所：`C:\Users\ユーザー名\AppData\Roaming\Claude\claude_desktop_config.json`
+
+> すべてのパスに**バックスラッシュを2つ**使用してください。
+
+保存後、Claude Desktopを**完全に再起動**してください。設定 → 開発者で**whisper**が緑色の実行中バッジで表示されるはずです。
+
+---
+
+## ステップ6 — セットアップの確認
+
+Claude Desktopで以下を確認してください：
+
+> *「whisperの設定を確認して」*
+
+次に：
+
+> *「システムハードウェアを確認して」*
+
+GPUが検出されVulkan加速が有効になっていることを確認します。
+
+---
+
+## 利用可能なツール
+
+### `transcribe_audio`
+単一ファイルを文字起こしします。長いファイルにはブロッキング（デフォルト）またはバックグラウンドモードに対応しています。
+
+| パラメータ | 説明 |
+|---|---|
+| `file_path` | ファイルへの絶対パス（必須） |
+| `language` | 言語コード（`en`、`ja`、`es`など）または`auto`で自動検出。デフォルト：`en` |
+| `output_format` | `text`（デフォルト）、`timestamps`、`json`、`srt` |
+| `save_to_file` | ソースファイルの隣にtxtとして保存 |
+| `background` | バックグラウンドジョブとして実行 — ジョブIDを即座に返します。`check_progress`で監視。10分以上のファイルに推奨。 |
+| `threads` | CPUスレッド数の上書き |
+| `temperature` | サンプリング温度0.0〜1.0。デフォルト0.0（決定論的）。高い値はノイズの多い音声でのハルシネーションを軽減します。 |
+| `prompt` | 事前コンテキスト文字列 — ドメイン固有の語彙や話者名の精度を向上させます。例：`"名前：Keemstar、DramaAlert"` |
+| `condition_on_prev_text` | セグメント間のコンテキスト条件付けを再有効化。デフォルトfalse。 |
+| `beam_size` | ビームサーチの幅。高いほど精度向上、処理速度低下。デフォルト5。 |
+| `best_of` | 評価する候補シーケンス数。デフォルト5。 |
+| `gpu_device` | マルチGPUシステムのGPUデバイスインデックス。デフォルト0。 |
+| `processors` | 並列プロセッサ数。デフォルト1。 |
+| `word_timestamps` | タイムスタンプ付き1単語ごとのセグメント出力。クリップ位置合わせに有用。 |
+| `max_segment_length` | セグメントの最大文字数。 |
+| `diarize` | ステレオ話者識別 — 別々のチャンネルに話者が録音されたステレオ音声が必要。 |
+| `vad_model` | Silero VADモデル.binへのパス。文字起こし前に無音を除去してハルシネーションを軽減します。 |
+| `offset_t` | 開始オフセット（ミリ秒）。 |
+| `duration` | オフセットからの処理時間（ミリ秒）。 |
+
+---
+
+### `check_progress`
+`transcribe_audio`（background=true）で開始したバックグラウンド文字起こしジョブを監視します。
+
+経過時間、最後に処理されたタイムスタンプ、完了時のトランスクリプト全文を返します。
+
+| パラメータ | 説明 |
+|---|---|
+| `job_id` | `transcribe_audio`が返したジョブID |
+
+---
+
+### `list_models`
+モデルディレクトリにインストール済みのWhisperモデルファイルを一覧表示します。ファイル名、サイズ、現在アクティブかどうか、量子化状態、推奨用途を表示します。ネットワーク接続不要。
+
+---
+
+### `download_model`
+Hugging Faceからモデルファイルを直接モデルディレクトリにダウンロードします。モデル名（例：`large-v3-turbo`、`medium.en-q5_0`）を受け取り、ダウンロードを自動処理します。信頼されたHugging Faceネームスペースからのみダウンロードします。ダウンロード後、`switch_model`でアクティベートしてください。
+
+| パラメータ | 説明 |
+|---|---|
+| `model_name` | ダウンロードするモデル名（例：`large-v3-turbo`、`large-v3-turbo-q5_0`、`medium.en-q5_0`） |
+
+---
+
+### `switch_model`
+Claude Desktopを再起動せずに現在のセッションのアクティブモデルを切り替えます。変更はセッションスコープです — 再起動後には保存されません。永続的にするには、設定の`WHISPER_MODEL`を更新してください。
+
+| パラメータ | 説明 |
+|---|---|
+| `model_name` | モデルファイル名（例：`ggml-large-v3-turbo.bin`）または完全パス。設定済みモデルディレクトリ内の`.bin`ファイルである必要があります。 |
+
+---
+
+### `start_batch`
+フォルダ内の未文字起こしファイルをすべて自動順次バッチ文字起こしします。時間順（短いものから）にソートし、バックグラウンドジョブとして1つずつ処理し、各出力を検証します。
+
+| パラメータ | 説明 |
+|---|---|
+| `folder_path` | フォルダへのパス（必須） |
+| `language` | 言語コード。デフォルト：`en` |
+| `threads` | CPUスレッド数の上書き |
+
+---
+
+### `check_batch_progress`
+実行中のバッチを監視します。現在のファイルが完了すると自動的に次のファイルに進みます。全体の進捗、タイムスタンプ付きの現在ファイル、ETA、失敗したファイルを返します。
+
+| パラメータ | 説明 |
+|---|---|
+| `batch_id` | `start_batch`が返したバッチID |
+
+---
+
+### `transcribe_batch`（インタラクティブ）
+プレビューと確認を行いながら1ファイルずつ処理します。進めながらレビューしたい場合に便利です。
+
+| パラメータ | 説明 |
+|---|---|
+| `folder_path` | フォルダへのパス（必須） |
+| `file_index` | 処理するファイル（1始まり）。省略するとファイル一覧を表示。 |
+| `language` | 言語コード。デフォルト：`en` |
+| `recursive` | サブフォルダを含める |
+
+---
+
+### `generate_subtitles`
+字幕ファイルを生成します。`language='auto'`で話されている言語を自動検出できます。`translate_to_english=true`で英語翻訳字幕ファイルも生成します。
+
+両方をリクエストした場合、2つの.srtファイルが保存されます：
+- `ファイル名.ja.srt` — 原語
+- `ファイル名.en.srt` — 英語翻訳
+
+> Whisperの組み込み翻訳は**英語へのみ**対応しています。他の言語への翻訳は、.srtファイルの内容を別途翻訳してください。
+
+| パラメータ | 説明 |
+|---|---|
+| `file_path` | ファイルへのパス（必須） |
+| `language` | 言語コードまたは`auto`で自動検出。デフォルト：`en` |
+| `translate_to_english` | 英語翻訳.srtも生成。ソースが英語以外の場合のみ適用。 |
+| `background` | バックグラウンドジョブとして実行。10分以上のファイルに推奨。 |
+| `threads` | CPUスレッド数の上書き |
+| `temperature` | サンプリング温度0.0〜1.0。デフォルト0.0。 |
+| `prompt` | ドメイン固有の語彙や話者名のための事前コンテキスト文字列。 |
+| `beam_size` | ビームサーチの幅。デフォルト5。 |
+| `diarize` | ステレオ話者識別。 |
+| `vad_model` | Silero VADモデルへのパス。 |
+
+---
+
+### `analyze_media`
+文字起こし前にファイルを分析します。時間、サイズ、コーデック、推定文字起こし時間（CPUとGPU）を返します。フォルダの場合、文字起こし状態付きの全ファイル一覧を表示します。
+
+| パラメータ | 説明 |
+|---|---|
+| `path` | 単一ファイルまたはフォルダへのパス（必須） |
+| `sort_by` | フォルダの場合：`duration`（デフォルト）、`name`、`size` |
+
+---
+
+### `check_config`
+whisper-cli.exe、モデルファイル、FFmpegがすべてアクセス可能か確認します。問題が発生した場合はまずこれを実行してください。
+
+---
+
+### `check_system`
+GPUハードウェアを検出しVulkan加速が利用可能か確認します。GPU名、VRAM、`ggml-vulkan.dll`の有無を報告し、ハードウェアに最適なモデルサイズを推奨します。
+
+---
+
+## 対応フォーマット
+
+| 種類 | フォーマット |
+|---|---|
+| ネイティブ（変換不要） | `mp3`、`wav` |
+| 動画（FFmpegで自動変換） | `mp4`、`mkv`、`avi`、`mov`、`webm`、`flv`、`wmv`、`m4v`、`ts`、`3gp` |
+| 音声（FFmpegで自動変換） | `m4a`、`ogg`、`flac` |
+
+---
+
+## GPU加速
+
+ビルド済みVulkanリリースはGPU加速を自動で有効にします。AMD Radeon RX Vega 56（GCN第5世代）でテスト済み。Vulkan 1.0+をサポートするすべてのGPU（NVIDIAおよびIntel Arcを含む）で動作するはずです。
+
+**パフォーマンス比較（medium.enモデル、約5分の音声ファイル）：**
+
+| ハードウェア | 処理時間 |
+|---|---|
+| CPUのみ（Ryzen 7 2700x、8スレッド） | 8〜12分 |
+| GPU（Vega 56 via Vulkan） | 20〜40秒 |
+
+文字起こし中のGPU使用率は通常15〜20%で、ファイル間はアイドル状態に戻ります。CPUは約15%を維持します。
+
+---
+
+## 多言語対応
+
+Whisperは話されている言語を自動検出し、その言語で文字起こしできます。組み込みの翻訳モデルは**英語へのみ**翻訳します。
+
+最高の多言語精度には`large-v3-turbo`モデルを使用してください。英語専用モデル（`*.en.bin`）は他の言語を検出・文字起こしできません。
+
+**例 — 字幕付き外国語動画：**
+1. `language=auto`と`translate_to_english=true`で字幕生成を依頼
+2. Whisperが言語を検出し、原語SRTを生成
+3. 2回目のパスで英語翻訳SRTを生成
+4. VLCで「字幕」→「字幕ファイルを追加」からいずれかのファイルを読み込み
+
+---
+
+## セキュリティ
+
+whisper-windows-mcpはセキュリティを核心的な原則として設計されています。
+
+**すべての処理はローカル。** 音声、トランスクリプト、ファイルパスが外部に送信されることは一切ありません。テレメトリなし。コア機能にクラウドAPIは不要。
+
+**入力検証。** すべてのファイルパスは使用前に検証されます — UNCパス（`\\server\share`）とディレクトリトラバーサル（`..`）は拒否されます。10GBを超えるファイルはリソース枯渇を防ぐために拒否されます。
+
+**トランスクリプトインジェクション対応。** 音声ファイルには、文字起こし時に指示のように見える内容が含まれる場合があります。Claudeの組み込み防御がこれを処理しますが、MCPサーバー自体はトランスクリプトの内容をデータとして扱い、指示として解釈しないことを知っておく価値があります。
+
+**モデルダウンロードの制限。** `download_model`ツールは信頼された2つのHugging Faceネームスペース（`ggerganov/whisper.cpp`と`ggml-org`）からのみダウンロードします。任意のURLは拒否されます。リダイレクトはフォロー前に許可リストで検証されます。
+
+**モデル切り替えのサンドボックス化。** `switch_model`は設定済みモデルディレクトリ内の`.bin`ファイルのみ受け付けます。そのディレクトリ外のパスは拒否されます。
+
+**新しいネットワーク依存なし。** モデルダウンロードはNode.js組み込みの`https`を使用 — 外部HTTPライブラリはパッケージに追加されません。
+
+---
+
+## フリープランユーザー向け設計
+
+このツールはClaude APIとのやり取りを最小限に抑えるよう設計されています。文字起こしワークフロー全体（スキャン、分析、キュー管理、実行、検証）は、できるだけ少ないClaude操作で完了できるよう設計されています。重い処理はすべてローカルマシンで実行されます。
+
+---
+
+## オプションの環境変数
+
+| 変数 | 説明 |
+|---|---|
+| `WHISPER_CLI_PATH` | whisper-cli.exeへのパス（必須） |
+| `WHISPER_MODEL` | モデル.binファイルへのパス（必須） |
+| `WHISPER_THREADS` | CPUスレッド数の上書き |
+| `FFMPEG_PATH` | ffmpegがシステムPATHにない場合のパス |
+
+---
+
+## トラブルシューティング
+
+詳細な解決策については[TROUBLESHOOTING.md](TROUBLESHOOTING.md)を参照してください。
+
+クイックチェックリスト：
+- 設定のパスに**バックスラッシュを2つ**使用している（`C:\\whisper\\...`）
+- `whisper-cli.exe`が設定されたパスに存在する
+- モデル`.bin`ファイルが設定されたパスに存在する
+- FFmpegがインストールされPATHに含まれている（`ffmpeg -version`が動作する）
+- 設定編集後にClaude Desktopを完全に再起動した
+- 設定 → 開発者でwhisperが**実行中**（緑色バッジ）で表示されている
+
+---
+
+## ライセンス
+
+MIT
+
+---
+
+## コントリビュート
+
+プルリクエスト歓迎です。[ROADMAP.md](ROADMAP.md)で計画中の機能を確認してください。
+
+上記以外のハードウェアでGPU加速をテストした方は、GPU型番、VRAM、モデルサイズ、確認したスループットをIssueで報告してください。