Windy Word

windy-word-mcp

一个 MCP（Model Context Protocol）服务，可将 Windy Word——这款语音转文本桌面应用——变为可由 Agent 控制的平台。115 个工具，涵盖粘贴 / 快捷键 / 转录 / 录音操作 / 音频设备 / 安装 / 诊断 / 归档 / 语音克隆 / 翻译 / 文档 / 系统 / 窗口 / 账户 + 账单 / TTS / 设置撤销 / 音乐闪避 / 批量克隆导入 / soul 文件导出。

Windy Word 在 127.0.0.1:18765 上运行本地 HTTP 控制服务。此软件包是其经过架构验证的 MCP 封装。Agent 调用 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	操作系统、架构、发行版、显示服务器、桌面环境、是否存在 xdotool/ydotool

粘贴策略（9）

12 种特定于平台的粘贴后端（macOS / Windows / Linux X11 / Linux Wayland），支持能力元数据、快捷键冲突自动检测以及经过验证的回退链。

工具	功能
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）

Agent 安装缺失的系统工具（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）

13 项基于规则的本地检查，涵盖粘贴栈工具、/dev/uinput 权限、polkit 规则是否存在（支持容忍 EACCES 的检测）、Python 引擎是否运行、Mutter 快捷键冲突、macOS 辅助功能 + 麦克风权限、Homebrew 是否存在、cliclick 是否存在。

工具	功能
run_diagnostics	运行本地检查集；返回结构化发现结果 + 可执行的修复措施
list_diagnostic_checks	查看有哪些检查，以及哪些适用于此平台
cloud_diagnose	通过 windy-fix-me Cloudflare Worker 使用大模型增强诊断（经由 OpenRouter 调用 Claude Haiku 4.5）

设置目录（5）— 类型化 / 已验证的 Agent 接口

49 个带标签的类型化目录条目（archive、voice-clone、transcription、paste、hotkey、ui、geometry、lifecycle、license）。任何写入操作前都会在服务端进行验证。

工具	功能
list_settings	目录 + 当前实时值 + 可用标签。支持 ?tag=X 筛选
describe_setting	单个条目 + 当前值
set_setting	验证 + 应用 + 返回副作用
get_config	Agent 可按路径读取的设置（个人值已隐藏；不会返回令牌和同意信息）
set_config	已停用：返回 retired，请改用 set_setting

设置撤销（2）

工具	功能
undo_last_setting_change	撤销本会话中最近一次经目录验证的设置更改
list_recent_setting_changes	按时间从早到晚列出本会话的设置更改

存档接口（8）— 不透明 ID 会话目录

Agent 使用不透明的 arc:YYYY-MM-DD:HHMMSS.md ID，从不使用文件系统路径。删除操作限制在指定路径内。

工具	功能
list_archive_entries	列出包含转录文本和元数据的录音
get_archive_stats	总文件数/大小（MB）/天数/字数/会话数（服务端缓存 30s）
read_archive_entry	获取条目的 Base64 音频或视频
delete_archive_entry	删除 md、音频和视频
open_archive_folder	在存档根目录打开 Pop OS 文件管理器
search_archives	对所有转录文本进行全文子串搜索
archives_by_date_range	开始时间戳位于 [from, to] 范围内的会话
bulk_delete_archives	一次调用删除多个条目

语音克隆（10 — Phase 1 + Phase 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	将本地克隆提交给 Windy Clone，用于 ElevenLabs 训练
get_cloud_clone_order_status	查询 Windy Clone 上的 ElevenLabs 训练进度
bulk_ingest_to_clone	将一批音频文件复制到语音样本存储区，作为克隆

批量导入克隆 + 监视器（3）

工具	功能
scan_folder_for_media	递归扫描文件夹中的音频和视频文件
watch_folder_for_recordings	启动/停止文件夹监视器，自动导入新音频
list_clone_watchers	列出活动的文件夹监视器

翻译（5）

工具	功能
translate_text	优先使用翻译记忆缓存 → 失败时回退到 Groq/OpenAI（自动填充缓存）
lookup_translation_memory	查询本地缓存，无需 API
save_translation_memory	手动插入或更新
get_translation_memory_stats	总数/热门语言对/最近条目
clear_translation_memory	清空（破坏性操作）

文档（3）

工具	功能
extract_document_text	基于路径，支持 txt/md/csv/html/pdf/docx（默认 5MB，上限 20MB）
save_text_file	基于路径写入；除非指定标记，否则拒绝覆盖
transcribe_audio_file	将任意音频文件转换为 Whisper 转录文本，通过预热的 WebSocket 引擎处理（CPU 上约为实时速度的 5 倍）

音效（7）

工具	功能
get_sound_effect_state	获取各钩子阶段的启用/音量设置（6 个生命周期阶段）
set_sound_hook	配置单个音效钩子阶段
set_active_sound_pack	切换当前音效包
set_master_sfx_volume	设置主音效音量（0-100）
set_sound_effect_mode	切换 EffectsEngine 模式（silent / classic / surprise / custom / pack）
list_sound_effect_packs	列出已知音效包
get_widget_state	通过渲染器桥接获取迷你小组件（tornado）的运行时状态

系统实用工具（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：将整个存档（音频 + 视频 + 转录文本 + manifest）打包为 zip，供数字分身工作流使用

窗口与应用生命周期（16）

工具	功能
get_window_state	获取窗口最大化、最小化、聚焦、可见和全屏状态的快照
minimize_window / maximize_window / unmaximize_window	标题栏窗口控制
bring_window_to_front	还原 + 显示 + 提升窗口层级（不会抢占键盘焦点）
set_window_geometry	设置屏幕像素中的位置 + 尺寸（实时生效并持久化）
set_video_fullscreen	切换原生操作系统级全屏
set_always_on_top	让窗口始终置于其他窗口上方
set_opacity	设置窗口不透明度（0.1-1.0）
set_theme	深色 / 浅色 / 自动
set_font_size	UI 缩放比例（70-150%）
show_hide_window	在主窗口 → tornado → 隐藏 → 主窗口之间循环切换
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	显示操作系统原生通知

账户与账单（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	通过操作系统系统级 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 桌面应用的 Agent 控制功能，包括粘贴、快捷键、转录、录音操作、音频设备、安装 / Doctor、归档、语音克隆（Phase 1 + Phase 2 云端训练）、翻译、文档、音效、窗口与应用生命周期、账户与账单、TTS、设置撤销、音乐音量闪避、批量克隆导入和 soul-file 导出。按照设计，内部不可由 Agent 调用的渲染进程事件不在此列。

质量标准

scripts/stress-test.js 会测试每个安全工具，包括：

• 在 MCP zod 层拒绝不在白名单中的内容
• 验证失败时透传结构化 4xx 错误
• 跨操作系统拒绝（Linux 上的 cliclick，macOS 上的 wtype）
• 真实粘贴注入往返测试（Tk 捕获 + 差异对比）
• 并发突发测试（20 个并行 get_platform 调用）
• 安装幂等性（检测 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 检查结果 + 平台上下文，并返回经大模型增强的修复建议。

此服务是 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。

贡献

欢迎提交 Bug 报告和新增工具。发布流程请参阅 PUBLISHING.md。