{
  "markdown": "# windy-word-mcp\n\nAn MCP (Model Context Protocol) server that turns [Windy Word](https://windyword.ai) — 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.\n\nWindy 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).\n\n[![npm](https://img.shields.io/npm/v/windy-word-mcp.svg)](https://www.npmjs.com/package/windy-word-mcp)\n[![mcp registry](https://img.shields.io/badge/mcp%20registry-active-brightgreen)](https://registry.modelcontextprotocol.io)\n\n---\n\n## Install\n\nFor most users:\n\n```bash\nclaude mcp add windy-word --command \"npx\" --args \"-y\" \"windy-word-mcp\"\n```\n\nOr in `~/.claude.json` / `~/.config/claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"windy-word\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"windy-word-mcp\"]\n    }\n  }\n}\n```\n\nLocal-dev (cloned repo):\n\n```bash\ngit clone https://github.com/sneakyfree/windy-word-mcp && cd windy-word-mcp\nnpm install\nclaude mcp add windy-word --command \"node\" --args \"$(pwd)/bin/windy-word-mcp.js\"\n```\n\n## Requirements\n\n- Node.js ≥ 18\n- Windy Word running locally (Electron app — the HTTP control server binds automatically at startup)\n\n## Environment overrides\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `WINDY_WORD_MCP_HOST` | `127.0.0.1` | Override the control-server host |\n| `WINDY_WORD_MCP_PORT` | `18765` | Override the control-server port |\n| `WINDY_WORD_MCP_TIMEOUT_MS` | `5000` | Default per-request timeout (the install + transcribe tools override this internally for long ops) |\n\n---\n\n## Tool catalog (115 tools, 22 categories)\n\n> Regenerate this section's tool count any time with `npm run test:list-tools`\n> (`node scripts/list-tools.js`), which enumerates the live server's registered tools.\n\n### Platform (1)\n| Tool | What it does |\n|---|---|\n| `get_platform` | OS, arch, distro, display server, desktop env, xdotool/ydotool presence |\n\n### Paste strategies (9)\n12 platform-specific paste backends (macOS / Windows / Linux X11 / Linux Wayland) with capability metadata, hotkey-collision auto-detection, and a verified fallback chain.\n\n| Tool | What it does |\n|---|---|\n| `list_paste_strategies` | All 12 strategies + per-strategy availability + resolved chain + collision flag |\n| `get_active_paste_strategy` | Current selection + resolved chain |\n| `set_paste_strategy` | Switch active (or `\"auto\"`) |\n| `test_paste_strategy` | Fire a specific strategy at the focused window (injects text!) |\n| `auto_paste` | Run the auto-execute chain with explicit candidates |\n| `run_paste_injection_test` | Real end-to-end test — spawns Tk target, fires paste, diffs result |\n| `get_paste_history` / `clear_paste_history` | In-memory audit log |\n| `get_paste_target` | XWayland vs Wayland-native detection |\n\n### Hotkeys (3)\n| Tool | What it does |\n|---|---|\n| `list_hotkeys` | Current bindings + available actions + reserved combos |\n| `set_hotkey` | Rebind a global shortcut (Electron accelerator format) |\n| `reset_hotkeys` | Restore all global shortcuts to catalog defaults + re-register |\n\n### Transcription engine (3)\n| Tool | What it does |\n|---|---|\n| `list_models` | Whisper model catalog + current + WindyTune ladder |\n| `set_model` | Switch (hot-reloads Python engine over WebSocket) |\n| `get_windytune_state` | Auto-tune state, ladder, recent-timing history |\n\n### Recording verbs (8)\n| Tool | What it does |\n|---|---|\n| `start_recording` | Begin a mode-aware recording (batch / streaming / API engine) |\n| `stop_recording` | End the recording → trigger transcription + paste pipeline |\n| `cancel_recording` | Abort an in-flight recording without saving |\n| `get_recording_state` | isRecording + pythonEngineRunning + mode snapshot |\n| `toggle_recording` | Start/stop (same effect as the global hotkey) |\n| `paste_transcript` | Re-paste the most recent transcript |\n| `set_language` | Set the Whisper transcription language (ISO 639-1) |\n| `set_panel_visibility` | Configure a bottom panel row (`always` / `hover` / off) |\n\n### Audio devices (1)\n| Tool | What it does |\n|---|---|\n| `list_audio_devices` | Enumerate microphones available to Windy Word |\n\n### `install_dependency` family (8)\nAgent 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`.\n\n| Tool | What it does |\n|---|---|\n| `list_installable_dependencies` | What's installable on this machine right now |\n| `install_dependency` | Synchronous install (whitelist + dryRun) |\n| `install_dependency_async` | Fire-and-poll variant — returns jobId |\n| `get_install_status` | Poll a job |\n| `list_install_jobs` | All in-memory jobs |\n| `get_install_history` / `clear_install_history` | Audit log |\n| `setup_install_polkit_rule` | Install/remove the Linux polkit auto-approve rule |\n\n**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](./PUBLISHING.md#polkit-rule-for-linux-install-without-prompts).\n\n### Windy Doctor — local + cloud (3)\n**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.\n\n| Tool | What it does |\n|---|---|\n| `run_diagnostics` | Run the local battery; return structured findings + actionable remediations |\n| `list_diagnostic_checks` | What checks exist + which apply to this platform |\n| `cloud_diagnose` | LLM-augment via the `windy-fix-me` Cloudflare Worker (Claude Haiku 4.5 via OpenRouter) |\n\n### Settings catalog (5) — typed/validated agent surface\n49 typed catalog entries with tags (`archive`, `voice-clone`, `transcription`, `paste`, `hotkey`, `ui`, `geometry`, `lifecycle`, `license`). Validation runs server-side before any write.\n\n| Tool | What it does |\n|---|---|\n| `list_settings` | Catalog + current live values + available tags. Supports `?tag=X` filter |\n| `describe_setting` | Single entry + current value |\n| `set_setting` | Validate + apply + return side effects |\n| `get_config` | Full electron-store dump (low-level escape hatch) |\n| `set_config` | Patch by dotted path, no validation (low-level escape hatch) |\n\n### Settings undo (2)\n| Tool | What it does |\n|---|---|\n| `undo_last_setting_change` | Revert the most recent catalog-validated setting change this session |\n| `list_recent_setting_changes` | List session setting changes, oldest first |\n\n### Archive surface (8) — opaque-id session catalog\nAgents work with opaque `arc:YYYY-MM-DD:HHMMSS.md` ids, never filesystem paths. Path-confined deletes.\n\n| Tool | What it does |\n|---|---|\n| `list_archive_entries` | List recordings with transcripts + metadata |\n| `get_archive_stats` | totalFiles/sizeMB/days/words/sessions (30s server-side cache) |\n| `read_archive_entry` | Base64 audio or video for an entry |\n| `delete_archive_entry` | Tear down md + audio + video |\n| `open_archive_folder` | Pop OS file manager at the archive root |\n| `search_archives` | Full-text substring search across every transcript |\n| `archives_by_date_range` | Sessions whose start timestamp falls within `[from, to]` |\n| `bulk_delete_archives` | Tear down multiple entries in one call |\n\n### Voice clones (10 — Phase 1 + Phase 2)\n| Tool | What it does |\n|---|---|\n| `list_voice_clones` | All clones + activeId (no audio bytes) |\n| `get_active_voice_clone` | Currently-active clone (or null) |\n| `set_active_voice_clone` | Switch active (or deactivate with `null`) |\n| `create_voice_clone_from_path` | Create from an audio file on disk (path-confined copy) |\n| `delete_voice_clone` | Irreversible teardown |\n| `preview_voice_clone` | Metadata + optional base64 audio |\n| `list_clone_bundles` | Training-bundle catalog |\n| `submit_voice_clone_to_cloud` | Submit a local clone to Windy Clone for ElevenLabs training |\n| `get_cloud_clone_order_status` | Poll Windy Clone for ElevenLabs training progress |\n| `bulk_ingest_to_clone` | Copy a batch of audio files into the voice-samples store as clones |\n\n### Bulk clone ingest + watchers (3)\n| Tool | What it does |\n|---|---|\n| `scan_folder_for_media` | Scan a folder (recursive) for audio + video files |\n| `watch_folder_for_recordings` | Start/stop a folder watcher that auto-ingests new audio |\n| `list_clone_watchers` | List active folder watchers |\n\n### Translation (5)\n| Tool | What it does |\n|---|---|\n| `translate_text` | TM-cache-first → Groq/OpenAI fallback (auto-populates cache) |\n| `lookup_translation_memory` | Local cache query, no API |\n| `save_translation_memory` | Manual upsert |\n| `get_translation_memory_stats` | Total / topPairs / recentEntries |\n| `clear_translation_memory` | Wipe (destructive) |\n\n### Documents (3)\n| Tool | What it does |\n|---|---|\n| `extract_document_text` | Path-based, supports txt/md/csv/html/pdf/docx (5MB default, 20MB cap) |\n| `save_text_file` | Path-based write; refuses overwrite unless flagged |\n| `transcribe_audio_file` | Any audio file → Whisper transcript via warm WebSocket engine (~5× real-time on CPU) |\n\n### Sound effects (7)\n| Tool | What it does |\n|---|---|\n| `get_sound_effect_state` | Per-hook-stage enabled/volume settings (6 lifecycle stages) |\n| `set_sound_hook` | Configure a single sound-effect hook stage |\n| `set_active_sound_pack` | Switch the active sound pack |\n| `set_master_sfx_volume` | Set master SFX volume (0-100) |\n| `set_sound_effect_mode` | Switch EffectsEngine mode (silent / classic / surprise / custom / pack) |\n| `list_sound_effect_packs` | List known sound-effect packs |\n| `get_widget_state` | Mini-widget (tornado) runtime state via the renderer bridge |\n\n### System utilities (3) + Forma Animae (1)\n| Tool | What it does |\n|---|---|\n| `detect_hardware` | RAM, CPU, GPU (nvidia-smi + Apple Silicon detect), disk free |\n| `get_autostart_status` | Is Windy Word configured to launch on login |\n| `set_autostart` | Toggle login-item / .desktop entry |\n| `export_soul_file_to_path` | Forma Animae: zip the whole archive (audio + video + transcripts + manifest) for the digital-twin pipeline |\n\n### Window + app lifecycle (16)\n| Tool | What it does |\n|---|---|\n| `get_window_state` | Snapshot of maximized/minimized/focused/visible/fullScreen |\n| `minimize_window` / `maximize_window` / `unmaximize_window` | Title-bar window controls |\n| `bring_window_to_front` | Restore + show + raise (does not steal keyboard focus) |\n| `set_window_geometry` | Set position + size in screen pixels (live + persisted) |\n| `set_video_fullscreen` | Toggle native OS-level fullscreen |\n| `set_always_on_top` | Keep the window above others |\n| `set_opacity` | Set window opacity (0.1-1.0) |\n| `set_theme` | dark / light / auto |\n| `set_font_size` | UI zoom factor (70-150%) |\n| `show_hide_window` | Cycle main → tornado → hidden → main |\n| `quick_translate` | Open the Quick Translate mini-window |\n| `restart_app` / `quit_app` | Relaunch / quit Windy Word (destructive) |\n\n### App info + notifications (5)\n| Tool | What it does |\n|---|---|\n| `get_version` | Windy Word + Electron + Node versions |\n| `check_for_updates` | Trigger electron-updater's update check |\n| `set_analytics_enabled` | Opt in/out of anonymous usage analytics |\n| `open_url` | Open an http/https URL or a Windy ecosystem scheme |\n| `send_notification` | Show an OS-native notification |\n\n### Account + billing (6)\n| Tool | What it does |\n|---|---|\n| `get_my_plan` | Signed-in identity + license tier |\n| `get_billing_history` | Purchase / transaction history |\n| `get_billing_summary` | Tier + lifetime spend + next renewal |\n| `open_upgrade_checkout` | Open Stripe Checkout for an upgrade |\n| `open_billing_portal` | Open the Stripe Customer Portal |\n| `logout_account` | Sign the user out |\n\n### TTS (3)\n| Tool | What it does |\n|---|---|\n| `speak_text` | Speak text aloud through the OS system TTS |\n| `stop_speaking` | Silence in-flight TTS playback |\n| `list_tts_voices` | List installed system TTS voices |\n\n### Music ducking (2)\n| Tool | What it does |\n|---|---|\n| `pause_other_audio` | Pause music/media in other apps (Spotify, Apple Music, browsers, VLC) |\n| `resume_other_audio` | Resume what `pause_other_audio` paused |\n\n---\n\n## Architecture\n\n```\n┌──────────────────────────┐\n│  Agent (Claude Code etc) │\n└──────────┬───────────────┘\n           │ MCP over stdio\n           ▼\n┌─────────────────────────────────────────┐\n│  windy-word-mcp (this package)          │\n│  - 115 zod-validated tool schemas       │\n│  - Per-tool timeout overrides           │\n│  - Structured 4xx body pass-through     │\n│  - \"Windy Word not running\" detection   │\n└──────────┬──────────────────────────────┘\n           │ HTTP localhost:18765\n           ▼\n┌─────────────────────────────────────────┐\n│  Windy Word (Electron) — windy-pro repo │\n│  - 49-entry settings catalog            │\n│  - 13 Doctor checks                     │\n│  - Paste-strategy registry (12 backends)│\n│  - Whisper Python engine (WebSocket)    │\n│  - Voice clone + archive on-disk state  │\n└──────────┬──────────────────────────────┘\n           │ HTTPS (only for cloud-diagnose)\n           ▼\n┌─────────────────────────────────────────┐\n│  windy-fix-me CF Worker                 │\n│  - SHARED_SECRET auth                   │\n│  - 20 req/IP/min rate limit             │\n│  - Claude Haiku 4.5 via OpenRouter      │\n└─────────────────────────────────────────┘\n```\n\n## Coverage\n\n**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.\n\n## Quality bar\n\n`scripts/stress-test.js` exercises every safe tool, including:\n- Whitelist rejection at the MCP zod layer\n- Structured 4xx error pass-through for validation failures\n- Cross-OS rejection (cliclick on Linux, wtype on macOS)\n- Real paste injection round-trip (Tk capture + diff)\n- Concurrency burst (20 parallel `get_platform` calls)\n- Idempotent installs (alreadyInstalled detection)\n\n**67/67 passing** at v1.0.0 release.\n\nKnown intermittent: `run_paste_injection_test` ~1-in-5 hits a Mutter focus-handoff race on Wayland+GNOME. Re-run is clean. Not a regression.\n\n## Sibling components\n\nThese are private repositories — the names are here so the architecture reads clearly, not as links.\n\n- **`windy-pro`** — the Electron app (Windy Word). Contains the control server, settings catalog, install registry, Doctor checks, paste strategies, archive scanner, voice-clone CRUD.\n- **`windy-fix-me`** — the cloud-relay Cloudflare Worker. Receives Doctor findings + platform context, returns LLM-augmented remediation.\n\nThis server is the public, supported interface to Windy Word. You do not need either of the above to use it — install from npm as shown at the top.\n\n## Version history\n\nSee [CHANGELOG.md](./CHANGELOG.md) for the per-version details. Tool count progression:\n\n```\nv0.1.0  20    foundation\nv0.2.0  24    install_dependency + polkit auto-approve\nv0.3.0  27    settings catalog\nv0.4.0  33    async install + Windy Doctor + cross-platform\nv0.5.0  34    cloud_diagnose\nv0.6.0  35    paste injection + tag filter\nv0.7.0  41    voice clones Phase 1\nv0.8.0  46    archive surface\nv0.9.0  53    translation + documents\nv0.10.0 56    utilities + OC5 macOS Doctor merge\nv0.11.0 57    transcribe_audio_file\nv0.12.0 60    soul-file export + voice-clone Phase 2 starters\nv1.0.0  60    stable API surface declared\nv1.5.0  95    Waves W1–W6: window/state, archive search, lifecycle, recording verbs, cloud submit\nv1.6.0  104   account / billing / plan surface\nv1.7.0  107   TTS round-trip\nv1.8.0  109   settings undo + audit log\nv1.9.0  111   music ducking\nv1.10.0 115   bulk clone-ingest\n```\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n\n## Contributing\n\nBug reports + tool additions welcome. See [PUBLISHING.md](./PUBLISHING.md) for the release recipe.\n",
  "bytes": 16733,
  "sha": "694d4535cde6d7373cc419594a0fc68000da41138a6e857a4f92d53429c412ac",
  "repo_slug": "sneakyfree/windy-word-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sneakyfree_windy_word_mcp_487a9ee9/readme"
}