windy-word-mcp

An MCP (Model Context Protocol) server that turns Windy Word — the voice-to-text desktop app — into an agent-controllable platform. 115 tools spanning paste / hotkeys / transcription / recording verbs / audio devices / install / diagnostics / archive / voice clones / translation / documents / system / window / account + billing / TTS / settings-undo / music-ducking / bulk-clone-ingest / soul-file export.

Windy Word ships a local HTTP control server on 127.0.0.1:18765. This package is a schema-validated MCP wrapper around it. Agents call MCP tools; the server forwards to Windy Word over localhost; everything happens on the user's machine (no network round-trips for state queries).

---

Install

For most users:

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

Or in ~/.claude.json / ~/.config/claude/claude_desktop_config.json:

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

Local-dev (cloned repo):

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"

Requirements

• Node.js ≥ 18
• Windy Word running locally (Electron app — the HTTP control server binds automatically at startup)

Environment overrides

Variable	Default	Purpose
WINDY_WORD_MCP_HOST	127.0.0.1	Override the control-server host
WINDY_WORD_MCP_PORT	18765	Override the control-server port
WINDY_WORD_MCP_TIMEOUT_MS	5000	Default per-request timeout (the install + transcribe tools override this internally for long ops)

---

Tool catalog (115 tools, 22 categories)

Regenerate this section's tool count any time with npm run test:list-tools (node scripts/list-tools.js), which enumerates the live server's registered tools.

Platform (1)

Tool	What it does
get_platform	OS, arch, distro, display server, desktop env, xdotool/ydotool presence

Paste strategies (9)

12 platform-specific paste backends (macOS / Windows / Linux X11 / Linux Wayland) with capability metadata, hotkey-collision auto-detection, and a verified fallback chain.

Tool	What it does
list_paste_strategies	All 12 strategies + per-strategy availability + resolved chain + collision flag
get_active_paste_strategy	Current selection + resolved chain
set_paste_strategy	Switch active (or "auto")
test_paste_strategy	Fire a specific strategy at the focused window (injects text!)
auto_paste	Run the auto-execute chain with explicit candidates
run_paste_injection_test	Real end-to-end test — spawns Tk target, fires paste, diffs result
get_paste_history / clear_paste_history	In-memory audit log
get_paste_target	XWayland vs Wayland-native detection

Hotkeys (3)

Tool	What it does
list_hotkeys	Current bindings + available actions + reserved combos
set_hotkey	Rebind a global shortcut (Electron accelerator format)
reset_hotkeys	Restore all global shortcuts to catalog defaults + re-register

Transcription engine (3)

Tool	What it does
list_models	Whisper model catalog + current + WindyTune ladder
set_model	Switch (hot-reloads Python engine over WebSocket)
get_windytune_state	Auto-tune state, ladder, recent-timing history

Recording verbs (8)

Tool	What it does
start_recording	Begin a mode-aware recording (batch / streaming / API engine)
stop_recording	End the recording → trigger transcription + paste pipeline
cancel_recording	Abort an in-flight recording without saving
get_recording_state	isRecording + pythonEngineRunning + mode snapshot
toggle_recording	Start/stop (same effect as the global hotkey)
paste_transcript	Re-paste the most recent transcript
set_language	Set the Whisper transcription language (ISO 639-1)
set_panel_visibility	Configure a bottom panel row (always / hover / off)

Audio devices (1)

Tool	What it does
list_audio_devices	Enumerate microphones available to Windy Word

install_dependency family (8)

Agent installs missing system tools (Linux/macOS/Windows package managers). Linux uses pkexec; macOS uses user-scope brew; Windows uses winget. Whitelist-only: wtype, ydotool, wl-clipboard, xdotool, cliclick, ffmpeg.

Tool	What it does
list_installable_dependencies	What's installable on this machine right now
install_dependency	Synchronous install (whitelist + dryRun)
install_dependency_async	Fire-and-poll variant — returns jobId
get_install_status	Poll a job
list_install_jobs	All in-memory jobs
get_install_history / clear_install_history	Audit log
setup_install_polkit_rule	Install/remove the Linux polkit auto-approve rule

Polkit setup (Linux): setup_install_polkit_rule installs /etc/polkit-1/rules.d/49-windy-install-deps.rules once per machine to make installs prompt-free. See the rule snippet.

Windy Doctor — local + cloud (3)

13 local rule-based checks covering paste-stack tooling, /dev/uinput permissions, polkit rule presence (with EACCES-tolerant detection), Python engine liveness, Mutter hotkey collision, macOS Accessibility + Microphone permissions, Homebrew presence, cliclick presence.

Tool	What it does
run_diagnostics	Run the local battery; return structured findings + actionable remediations
list_diagnostic_checks	What checks exist + which apply to this platform
cloud_diagnose	LLM-augment via the windy-fix-me Cloudflare Worker (Claude Haiku 4.5 via OpenRouter)

Settings catalog (5) — typed/validated agent surface

49 typed catalog entries with tags (archive, voice-clone, transcription, paste, hotkey, ui, geometry, lifecycle, license). Validation runs server-side before any write.

Tool	What it does
list_settings	Catalog + current live values + available tags. Supports ?tag=X filter
describe_setting	Single entry + current value
set_setting	Validate + apply + return side effects
get_config	Full electron-store dump (low-level escape hatch)
set_config	Patch by dotted path, no validation (low-level escape hatch)

Settings undo (2)

Tool	What it does
undo_last_setting_change	Revert the most recent catalog-validated setting change this session
list_recent_setting_changes	List session setting changes, oldest first

Archive surface (8) — opaque-id session catalog

Agents work with opaque arc:YYYY-MM-DD:HHMMSS.md ids, never filesystem paths. Path-confined deletes.

Tool	What it does
list_archive_entries	List recordings with transcripts + metadata
get_archive_stats	totalFiles/sizeMB/days/words/sessions (30s server-side cache)
read_archive_entry	Base64 audio or video for an entry
delete_archive_entry	Tear down md + audio + video
open_archive_folder	Pop OS file manager at the archive root
search_archives	Full-text substring search across every transcript
archives_by_date_range	Sessions whose start timestamp falls within [from, to]
bulk_delete_archives	Tear down multiple entries in one call

Voice clones (10 — Phase 1 + Phase 2)

Tool	What it does
list_voice_clones	All clones + activeId (no audio bytes)
get_active_voice_clone	Currently-active clone (or null)
set_active_voice_clone	Switch active (or deactivate with null)
create_voice_clone_from_path	Create from an audio file on disk (path-confined copy)
delete_voice_clone	Irreversible teardown
preview_voice_clone	Metadata + optional base64 audio
list_clone_bundles	Training-bundle catalog
submit_voice_clone_to_cloud	Submit a local clone to Windy Clone for ElevenLabs training
get_cloud_clone_order_status	Poll Windy Clone for ElevenLabs training progress
bulk_ingest_to_clone	Copy a batch of audio files into the voice-samples store as clones

Bulk clone ingest + watchers (3)

Tool	What it does
scan_folder_for_media	Scan a folder (recursive) for audio + video files
watch_folder_for_recordings	Start/stop a folder watcher that auto-ingests new audio
list_clone_watchers	List active folder watchers

Translation (5)

Tool	What it does
translate_text	TM-cache-first → Groq/OpenAI fallback (auto-populates cache)
lookup_translation_memory	Local cache query, no API
save_translation_memory	Manual upsert
get_translation_memory_stats	Total / topPairs / recentEntries
clear_translation_memory	Wipe (destructive)

Documents (3)

Tool	What it does
extract_document_text	Path-based, supports txt/md/csv/html/pdf/docx (5MB default, 20MB cap)
save_text_file	Path-based write; refuses overwrite unless flagged
transcribe_audio_file	Any audio file → Whisper transcript via warm WebSocket engine (~5× real-time on CPU)

Sound effects (7)

Tool	What it does
get_sound_effect_state	Per-hook-stage enabled/volume settings (6 lifecycle stages)
set_sound_hook	Configure a single sound-effect hook stage
set_active_sound_pack	Switch the active sound pack
set_master_sfx_volume	Set master SFX volume (0-100)
set_sound_effect_mode	Switch EffectsEngine mode (silent / classic / surprise / custom / pack)
list_sound_effect_packs	List known sound-effect packs
get_widget_state	Mini-widget (tornado) runtime state via the renderer bridge

System utilities (3) + Forma Animae (1)

Tool	What it does
detect_hardware	RAM, CPU, GPU (nvidia-smi + Apple Silicon detect), disk free
get_autostart_status	Is Windy Word configured to launch on login
set_autostart	Toggle login-item / .desktop entry
export_soul_file_to_path	Forma Animae: zip the whole archive (audio + video + transcripts + manifest) for the digital-twin pipeline

Window + app lifecycle (16)

Tool	What it does
get_window_state	Snapshot of maximized/minimized/focused/visible/fullScreen
minimize_window / maximize_window / unmaximize_window	Title-bar window controls
bring_window_to_front	Restore + show + raise (does not steal keyboard focus)
set_window_geometry	Set position + size in screen pixels (live + persisted)
set_video_fullscreen	Toggle native OS-level fullscreen
set_always_on_top	Keep the window above others
set_opacity	Set window opacity (0.1-1.0)
set_theme	dark / light / auto
set_font_size	UI zoom factor (70-150%)
show_hide_window	Cycle main → tornado → hidden → main
quick_translate	Open the Quick Translate mini-window
restart_app / quit_app	Relaunch / quit Windy Word (destructive)

App info + notifications (5)

Tool	What it does
get_version	Windy Word + Electron + Node versions
check_for_updates	Trigger electron-updater's update check
set_analytics_enabled	Opt in/out of anonymous usage analytics
open_url	Open an http/https URL or a Windy ecosystem scheme
send_notification	Show an OS-native notification

Account + billing (6)

Tool	What it does
get_my_plan	Signed-in identity + license tier
get_billing_history	Purchase / transaction history
get_billing_summary	Tier + lifetime spend + next renewal
open_upgrade_checkout	Open Stripe Checkout for an upgrade
open_billing_portal	Open the Stripe Customer Portal
logout_account	Sign the user out

TTS (3)

Tool	What it does
speak_text	Speak text aloud through the OS system TTS
stop_speaking	Silence in-flight TTS playback
list_tts_voices	List installed system TTS voices

Music ducking (2)

Tool	What it does
pause_other_audio	Pause music/media in other apps (Spotify, Apple Music, browsers, VLC)
resume_other_audio	Resume what pause_other_audio paused

---

Architecture

┌──────────────────────────┐
│  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      │
└─────────────────────────────────────────┘

Coverage

115 MCP tools now surface the Windy Word desktop app's agent-control surface — paste, hotkeys, transcription, recording verbs, audio devices, install/Doctor, archive, voice clones (Phase 1 + Phase 2 cloud training), translation, documents, sound effects, window + app lifecycle, account + billing, TTS, settings-undo, music-ducking, bulk-clone-ingest, and soul-file export. Internal renderer events that are not agent-callable RPCs by design are intentionally excluded.

Quality bar

scripts/stress-test.js exercises every safe tool, including:

• Whitelist rejection at the MCP zod layer
• Structured 4xx error pass-through for validation failures
• Cross-OS rejection (cliclick on Linux, wtype on macOS)
• Real paste injection round-trip (Tk capture + diff)
• Concurrency burst (20 parallel get_platform calls)
• Idempotent installs (alreadyInstalled detection)

67/67 passing at v1.0.0 release.

Known intermittent: run_paste_injection_test ~1-in-5 hits a Mutter focus-handoff race on Wayland+GNOME. Re-run is clean. Not a regression.

Sibling repos

• sneakyfree/windy-pro — the Electron app (Windy Word). Contains the control server, settings catalog, install registry, Doctor checks, paste strategies, archive scanner, voice-clone CRUD. npm install + npm start to run.
• sneakyfree/windy-fix-me — the cloud-relay Cloudflare Worker. Receives Doctor findings + platform context, returns LLM-augmented remediation via OpenRouter.

Version history

See CHANGELOG.md for the per-version details. Tool count progression:

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

License

MIT. See LICENSE.

Contributing

Bug reports + tool additions welcome. See PUBLISHING.md for the release recipe.