Windy Word

windy-word-mcp

Windy Word — 音声をテキストに変換するデスクトップアプリ — をエージェントが操作できるプラットフォームにする MCP（Model Context Protocol）サーバーです。115 個のツールで、貼り付け／ホットキー／文字起こし／録音操作／オーディオデバイス／インストール／診断／アーカイブ／ボイスクローン／翻訳／ドキュメント／システム／ウィンドウ／アカウントと請求／TTS／設定の取り消し／音楽の音量調整／ボイスクローンの一括取り込み／ソウルファイルのエクスポートに対応します。

Windy Word は 127.0.0.1:18765 でローカル HTTP 制御サーバーを起動します。このパッケージは、そのサーバーをスキーマ検証付きでラップする MCP サーバーです。エージェントは MCP ツールを呼び出し、サーバーは localhost 経由で Windy Word にリクエストを転送します。すべてユーザーのマシン上で実行されます（状態の照会にネットワーク往復はありません）。

---

インストール

ほとんどのユーザー向け：

claude mcp add windy-word --command "npx" --args "-y" "windy-word-mcp"

または、~/.claude.json / ~/.config/claude/claude_desktop_config.json に記述します。

{
  "mcpServers": {
    "windy-word": {
      "command": "npx",
      "args": ["-y", "windy-word-mcp"]
    }
  }
}

ローカル開発（リポジトリをクローン）：

git clone https://github.com/sneakyfree/windy-word-mcp && cd windy-word-mcp
npm install
claude mcp add windy-word --command "node" --args "$(pwd)/bin/windy-word-mcp.js"

必要条件

• Node.js ≥ 18
• Windy Word がローカルで起動していること（Electron アプリ — HTTP 制御サーバーは起動時に自動的にバインドされます）

環境変数による上書き

変数	デフォルト	用途
WINDY_WORD_MCP_HOST	127.0.0.1	制御サーバーのホストを上書きします
WINDY_WORD_MCP_PORT	18765	制御サーバーのポートを上書きします
WINDY_WORD_MCP_TIMEOUT_MS	5000	リクエストごとのデフォルトのタイムアウト（インストールと文字起こしのツールは、時間のかかる操作に対して内部でこの値を上書きします）

---

ツール一覧（115 個のツール、22 カテゴリ）

npm run test:list-tools を実行すると、ツール数をいつでも再生成できます。 （node scripts/list-tools.js）。ライブサーバーに登録されているツールを列挙します。

プラットフォーム（1）

ツール	説明
get_platform	OS、アーキテクチャ、ディストリビューション、ディスプレイサーバー、デスクトップ環境、xdotool/ydotool の有無

貼り付け方式（9）

macOS／Windows／Linux X11／Linux Wayland に対応したプラットフォーム固有の貼り付けバックエンドが 12 種類あります。機能メタデータ、ホットキーの競合の自動検出、検証済みのフォールバックチェーンを備えています。

ツール	説明
list_paste_strategies	12 種類すべての方式、方式ごとの利用可否、解決済みチェーン、競合フラグ
get_active_paste_strategy	現在の選択と解決済みチェーン
set_paste_strategy	使用する方式を切り替えます（または "auto" を指定）
test_paste_strategy	指定した方式をフォーカス中のウィンドウで実行します（テキストを入力します！）
auto_paste	明示的な候補を使って自動実行チェーンを実行します
run_paste_injection_test	実際のエンドツーエンドテスト — Tk のターゲットを起動し、貼り付けを実行して、結果の差分を確認します
get_paste_history / clear_paste_history	メモリ内の監査ログ
get_paste_target	XWayland と Wayland ネイティブの判定

ホットキー（3）

ツール	説明
list_hotkeys	現在の割り当て、利用可能なアクション、予約済みのキーの組み合わせ
set_hotkey	グローバルショートカットを再割り当てします（Electron のアクセラレータ形式）
reset_hotkeys	すべてのグローバルショートカットをカタログのデフォルトに戻し、再登録します

文字起こしエンジン（3）

ツール	説明
list_models	Whisper モデルのカタログ、現在のモデル、WindyTune の段階
set_model	モデルを切り替えます（WebSocket 経由で Python エンジンをホットリロードします）
get_windytune_state	自動調整の状態、段階、最近の処理時間の履歴

録音動詞（8）

ツール	機能
start_recording	モードに応じた録音を開始します（バッチ／ストリーミング／API エンジン）
stop_recording	録音を終了し、文字起こし＋貼り付けのパイプラインを起動します
cancel_recording	保存せずに進行中の録音を中止します
get_recording_state	isRecording ＋ pythonEngineRunning ＋ モードのスナップショットを取得します
toggle_recording	録音を開始／停止します（グローバルホットキーと同じ動作です）
paste_transcript	直近の文字起こし結果を再度貼り付けます
set_language	Whisper の文字起こし言語を設定します（ISO 639-1）
set_panel_visibility	下部パネルの行の表示方法を設定します（always／hover／オフ）

オーディオデバイス（1）

ツール	機能
list_audio_devices	Windy Word が利用できるマイクを列挙します

install_dependency ファミリー（8）

エージェントが、不足しているシステムツールをインストールします（Linux／macOS／Windows のパッケージマネージャー）。Linux では pkexec、macOS ではユーザースコープの brew、Windows では winget を使用します。許可リストにあるもののみが対象です：wtype、ydotool、wl-clipboard、xdotool、cliclick、ffmpeg。

ツール	機能
list_installable_dependencies	現在、このマシンにインストールできるものを確認します
install_dependency	同期インストール（許可リスト＋dryRun）
install_dependency_async	実行してポーリングする方式で、jobId を返します
get_install_status	ジョブをポーリングします
list_install_jobs	メモリ内のすべてのジョブを一覧表示します
get_install_history / clear_install_history	監査ログ
setup_install_polkit_rule	Linux の polkit 自動承認ルールをインストール／削除します

Polkit のセットアップ（Linux）： setup_install_polkit_rule は、インストール時のプロンプトを不要にするため、マシンごとに一度 /etc/polkit-1/rules.d/49-windy-install-deps.rules をインストールします。ルールのスニペットを参照してください。

Windy Doctor — ローカル＋クラウド（3）

ペーストスタックのツール、/dev/uinput の権限、polkit ルールの有無（EACCES を許容する検出）、Python エンジンの稼働状況、Mutter のホットキー競合、macOS のアクセシビリティとマイクの権限、Homebrew の有無、cliclick の有無を対象とする、ローカルのルールベースのチェックが 13 件あります。

ツール	機能
run_diagnostics	ローカルの診断一式を実行し、構造化された検出結果と実行可能な対処法を返します
list_diagnostic_checks	利用可能なチェックと、このプラットフォームに適用されるチェックを確認します
cloud_diagnose	windy-fix-me Cloudflare Worker（OpenRouter 経由の Claude Haiku 4.5）を通じて LLM による補強を行います

設定カタログ（5）— 型付き／検証済みのエージェント向けインターフェース

タグ（archive、voice-clone、transcription、paste、hotkey、ui、geometry、lifecycle、license）付きの型付きカタログ項目が 49 件あります。書き込み前にサーバー側で検証されます。

ツール	機能
list_settings	カタログ、現在のライブ値、利用可能なタグを表示します。?tag=X フィルターに対応しています
describe_setting	単一の項目と現在の値を表示します
set_setting	検証して適用し、副作用を返します
get_config	パスを指定して、エージェントが読み取れる設定を取得します（個人の値は伏せられ、トークンと同意情報は返されません）
set_config	廃止済みです。retired を返します。set_setting を使用してください

設定の取り消し（2）

ツール	機能
undo_last_setting_change	このセッションで最後に行った、カタログ検証済みの設定変更を元に戻します
list_recent_setting_changes	セッション中の設定変更を古い順に一覧表示します

アーカイブ関連（8）— 不透明 ID のセッションカタログ

エージェントはファイルシステムのパスではなく、不透明な arc:YYYY-MM-DD:HHMMSS.md ID を使用します。削除対象は指定パス内に限定されます。

ツール	機能
list_archive_entries	文字起こしとメタデータを含む録音を一覧表示します
get_archive_stats	totalFiles/sizeMB/days/words/sessions（サーバー側で30秒間キャッシュ）
read_archive_entry	エントリの音声または動画を Base64 で取得します
delete_archive_entry	md ファイル、音声、動画を削除します
open_archive_folder	アーカイブのルートで OS のファイルマネージャーを開きます
search_archives	すべての文字起こしを対象に全文部分一致検索します
archives_by_date_range	開始タイムスタンプが [from, to] の範囲内にあるセッションを取得します
bulk_delete_archives	1回の呼び出しで複数のエントリを削除します

ボイスクローン（10 — フェーズ 1 + フェーズ 2）

ツール	機能
list_voice_clones	すべてのクローンと activeId を取得します（音声データは含みません）
get_active_voice_clone	現在有効なクローンを取得します（または null）
set_active_voice_clone	有効なクローンを切り替えます（null で無効化）
create_voice_clone_from_path	ディスク上の音声ファイルから作成します（コピー先は指定パス内に限定）
delete_voice_clone	取り消しできない削除を実行します
preview_voice_clone	メタデータと、オプションで Base64 音声を取得します
list_clone_bundles	トレーニングバンドルのカタログを一覧表示します
submit_voice_clone_to_cloud	ElevenLabs のトレーニング用に、ローカルクローンを Windy Clone に送信します
get_cloud_clone_order_status	ElevenLabs のトレーニングの進捗状況を Windy Clone に問い合わせます
bulk_ingest_to_clone	複数の音声ファイルをクローンとして音声サンプルストアにコピーします

クローンの一括取り込み + 監視（3）

ツール	機能
scan_folder_for_media	フォルダー内の音声・動画ファイルを再帰的にスキャンします
watch_folder_for_recordings	新しい音声を自動取り込みするフォルダー監視を開始／停止します
list_clone_watchers	有効なフォルダー監視を一覧表示します

翻訳（5）

ツール	機能
translate_text	TM キャッシュを優先し、次に Groq/OpenAI にフォールバックします（キャッシュに自動登録）
lookup_translation_memory	ローカルキャッシュを検索します。API は使用しません
save_translation_memory	手動で upsert します
get_translation_memory_stats	合計数／topPairs／最近のエントリを取得します
clear_translation_memory	消去します（破壊的操作）

ドキュメント（3）

ツール	機能
extract_document_text	パスを指定して抽出します。txt/md/csv/html/pdf/docx に対応（デフォルト 5MB、上限 20MB）
save_text_file	パスを指定して書き込みます。フラグを指定しない限り上書きを拒否します
transcribe_audio_file	任意の音声ファイルを、ウォーム状態の WebSocket エンジンで Whisper 文字起こしに変換します（CPU でリアルタイムの約5倍）

効果音（7）

ツール	機能
get_sound_effect_state	フック段階ごとの有効／音量設定を取得します（ライフサイクルの6段階）
set_sound_hook	効果音フックの段階を1つ設定します
set_active_sound_pack	有効なサウンドパックを切り替えます
set_master_sfx_volume	SFX のマスター音量を設定します（0～100）
set_sound_effect_mode	EffectsEngine のモードを切り替えます（silent / classic / surprise / custom / pack）
list_sound_effect_packs	既知の効果音パックを一覧表示します
get_widget_state	レンダラーブリッジ経由でミニウィジェット（竜巻）の実行時状態を取得します

システムユーティリティ（3）+ Forma Animae（1）

ツール	機能
detect_hardware	RAM、CPU、GPU（nvidia-smi と Apple Silicon の検出）、空きディスク容量を取得します
get_autostart_status	Windy Word がログイン時に起動するよう設定されているかを確認します
set_autostart	ログイン項目／.desktop エントリを切り替えます
export_soul_file_to_path	Forma Animae：アーカイブ全体（音声 + 動画 + 文字起こし + マニフェスト）を zip 形式でデジタルツインのパイプライン用に出力します

ウィンドウとアプリのライフサイクル（16）

ツール	機能
get_window_state	最大化／最小化／フォーカス／表示／フルスクリーン状態のスナップショット
minimize_window / maximize_window / unmaximize_window	タイトルバーのウィンドウ操作
bring_window_to_front	復元＋表示＋最前面への移動（キーボードフォーカスは奪いません）
set_window_geometry	画面ピクセル単位で位置とサイズを設定（即時反映＋保存）
set_video_fullscreen	OS ネイティブのフルスクリーンを切り替え
set_always_on_top	ウィンドウを常に最前面に表示
set_opacity	ウィンドウの不透明度を設定（0.1～1.0）
set_theme	ダーク／ライト／自動
set_font_size	UI のズーム倍率（70～150％）
show_hide_window	メイン → トルネード → 非表示 → メインの順に切り替え
quick_translate	クイック翻訳のミニウィンドウを開く
restart_app / quit_app	Windy Word を再起動／終了（破壊的操作）

アプリ情報と通知（5）

ツール	機能
get_version	Windy Word、Electron、Node のバージョン
check_for_updates	electron-updater の更新チェックを実行
set_analytics_enabled	匿名の利用状況分析への参加／不参加を設定
open_url	http/https URL または Windy エコシステムのスキームを開く
send_notification	OS ネイティブの通知を表示

アカウントと請求（6）

ツール	機能
get_my_plan	サインイン中のユーザー情報とライセンスのティア
get_billing_history	購入／取引履歴
get_billing_summary	ティア、生涯利用額、次回の更新
open_upgrade_checkout	アップグレード用の Stripe Checkout を開く
open_billing_portal	Stripe Customer Portal を開く
logout_account	ユーザーをサインアウト

TTS（3）

ツール	機能
speak_text	OS のシステム TTS でテキストを読み上げる
stop_speaking	再生中の TTS を停止
list_tts_voices	インストール済みのシステム TTS 音声を一覧表示

音楽の音量抑制（2）

ツール	機能
pause_other_audio	他のアプリ（Spotify、Apple Music、ブラウザー、VLC）の音楽／メディアを一時停止
resume_other_audio	pause_other_audio で一時停止した音声を再開

---

アーキテクチャ

┌──────────────────────────┐
│  Agent (Claude Code etc) │
└──────────┬───────────────┘
           │ MCP over stdio
           ▼
┌─────────────────────────────────────────┐
│  windy-word-mcp (this package)          │
│  - 115 zod-validated tool schemas       │
│  - Per-tool timeout overrides           │
│  - Structured 4xx body pass-through     │
│  - "Windy Word not running" detection   │
└──────────┬──────────────────────────────┘
           │ HTTP localhost:18765
           ▼
┌─────────────────────────────────────────┐
│  Windy Word (Electron) — windy-pro repo │
│  - 49-entry settings catalog            │
│  - 13 Doctor checks                     │
│  - Paste-strategy registry (12 backends)│
│  - Whisper Python engine (WebSocket)    │
│  - Voice clone + archive on-disk state  │
└──────────┬──────────────────────────────┘
           │ HTTPS (only for cloud-diagnose)
           ▼
┌─────────────────────────────────────────┐
│  windy-fix-me CF Worker                 │
│  - SHARED_SECRET auth                   │
│  - 20 req/IP/min rate limit             │
│  - Claude Haiku 4.5 via OpenRouter      │
└─────────────────────────────────────────┘

対応範囲

115 個の MCP ツールにより、Windy Word デスクトップアプリのエージェント制御機能を利用できます。対象は、貼り付け、ホットキー、文字起こし、録音操作、オーディオデバイス、インストール／Doctor、アーカイブ、音声クローン（フェーズ 1 とフェーズ 2 のクラウドトレーニング）、翻訳、ドキュメント、効果音、ウィンドウとアプリのライフサイクル、アカウントと請求、TTS、設定の取り消し、音楽の音量抑制、一括クローン取り込み、ソウルファイルのエクスポートです。設計上、エージェントから呼び出せない内部のレンダラーイベントは意図的に除外しています。

品質基準

scripts/stress-test.js では、安全なツールをすべてテストします。内容は次のとおりです。

• MCP の zod レイヤーでのホワイトリスト拒否
• 検証エラー時の構造化された 4xx エラーのパススルー
• OS 間の拒否（Linux での cliclick、macOS での wtype）
• 実際の貼り付け注入のラウンドトリップ（Tk によるキャプチャ＋差分）
• 同時実行バースト（get_platform を 20 件並列呼び出し）
• 冪等なインストール（alreadyInstalled の検出）

v1.0.0 のリリース時点で 67/67 件が合格しています。

既知の断続的な問題：run_paste_injection_test では約 5 回に 1 回、Wayland＋GNOME で Mutter のフォーカス引き継ぎ競合が発生します。再実行すれば問題ありません。リグレッションではありません。

関連コンポーネント

これらは非公開リポジトリです。名前はアーキテクチャを分かりやすくするために記載しており、リンクではありません。

• windy-pro — Electron アプリ（Windy Word）です。制御サーバー、設定カタログ、インストールレジストリ、Doctor チェック、貼り付け方式、アーカイブスキャナー、音声クローンの CRUD が含まれています。
• windy-fix-me — クラウドリレーを担う Cloudflare Worker です。Doctor の検出結果とプラットフォームのコンテキストを受け取り、LLM による補強を加えた修復方法を返します。

このサーバーは、Windy Word の公開済み公式インターフェースです。利用に上記のコンポーネントは必要ありません。冒頭の手順に従って npm からインストールしてください。

バージョン履歴

バージョンごとの詳細は CHANGELOG.md を参照してください。ツール数の推移：

v0.1.0  20    foundation
v0.2.0  24    install_dependency + polkit auto-approve
v0.3.0  27    settings catalog
v0.4.0  33    async install + Windy Doctor + cross-platform
v0.5.0  34    cloud_diagnose
v0.6.0  35    paste injection + tag filter
v0.7.0  41    voice clones Phase 1
v0.8.0  46    archive surface
v0.9.0  53    translation + documents
v0.10.0 56    utilities + OC5 macOS Doctor merge
v0.11.0 57    transcribe_audio_file
v0.12.0 60    soul-file export + voice-clone Phase 2 starters
v1.0.0  60    stable API surface declared
v1.5.0  95    Waves W1–W6: window/state, archive search, lifecycle, recording verbs, cloud submit
v1.6.0  104   account / billing / plan surface
v1.7.0  107   TTS round-trip
v1.8.0  109   settings undo + audit log
v1.9.0  111   music ducking
v1.10.0 115   bulk clone-ingest

ライセンス

MIT です。LICENSE を参照してください。

貢献

バグの報告やツールの追加を歓迎します。リリース手順については、PUBLISHING.mdをご覧ください。