Nvda MCP Bridge

nvda mcp大桥

一个NVDA插件，它公开了一个用于MCP服务器的本地HTTP接口。

该插件在NVDA内部运行并监听：

http://127.0.0.1:8765

它提供了一个基于JSON的小型API，单独的MCP服务器进程可以调用该API来访问选定的NVDA功能。

______________________________________________________________________

目的

nvda-mcp-bridge:

• 在NVDA中作为全局插件运行
• 暴露仅限本地主机的HTTP端点
• 允许外部MCP服务器调用NVDA操作
• 将NVDA API调用分派到主线程

它本身不实现MCP协议。 它被设计为由单独运行的MCP服务器使用。

______________________________________________________________________

建筑

LLM / Client
      ↓
MCP Server (separate process)
      ↓ HTTP (localhost)
nvda-mcp-bridge (inside NVDA)
      ↓
NVDA APIs

MCP服务器处理协议和工具暴露。 网桥接收HTTP请求并运行相应的NVDA操作。

______________________________________________________________________

需求

• NVDA 2026.1或更高版本
• Python 3.7+（用于构建）
• SCons(pip install scons)
• 兼容的MCP服务器

______________________________________________________________________

构建

git clone https://github.com/adil-adysh/nvda-mcp-bridge.git
cd nvda-mcp-bridge
scons

这产生了 .nvda-addon 包裹。

______________________________________________________________________

安装

1. 构建插件。
2. 打开生成的 .nvda-addon 文件。
3. 重新启动NVDA。

当NVDA加载插件时，HTTP侦听器启动。

______________________________________________________________________

API终点

GET/健康

未经身份验证的健康检查。

GET/工具

返回发现的工具和元数据。

需要标题：

X-NVDA-Bridge-Token: 

POST/操作

运行一个动作。

需要标题：

X-NVDA-Bridge-Token: 

请求正文：

{
  "action": "action_name",
  "params": {}
}

笔记：

• action 是必需的。
• params 是可选的，默认为 {}.
• params 提供时必须是JSON对象。

例子：

Invoke-WebRequest `
  -Uri http://127.0.0.1:8765/action `
  -Method POST `
  -Headers @{ "X-NVDA-Bridge-Token" = "nvda-bridge-secret-change-me" } `
  -Body '{"action":"get_window_title","params":{}}' `
  -ContentType "application/json"

成功信封：

{
  "success": true,
  "action": "get_window_title",
  "duration_ms": 12.34,
  "result": {
    "title": "pwsh",
    "handle": 2296154,
    "className": "CASCADIA_HOSTING_WINDOW_CLASS"
  }
}

错误信封：

{
  "success": false,
  "action": "move_focus",
  "duration_ms": 1.23,
  "error": "Missing required parameter: direction",
  "error_type": "validation"
}

______________________________________________________________________

动作和参数

• get_current_focus\

描述：获取当前聚焦的UI元素的信息。\ 参数：无。

• read_current_line\

描述：从聚焦对象读取当前行。\ 参数：无。

• speak_text\

说明：使用NVDA朗读文本。\ 必需参数： text （字符串）。

• get_window_title\

描述：获取前台窗口标题/详细信息。\ 参数：无。

• move_focus\

描述：将焦点移动到下一个或上一个对象。\ 必需参数： direction （字符串： next 或 previous).

• get_navigator_object\

描述：获取当前导航器对象的详细信息。\ 参数：无。

• get_desktop_object\

描述：获取桌面对象详细信息。\ 参数：无。

• show_message\

说明：显示UI消息。\ 必需参数： message （字符串）。

• reload_plugins\

说明：重新加载全局插件和应用程序模块。\ 参数：无。

• restart_nvda\

说明：重新启动NVDA。\ 可选参数： disable_addons （布尔）， debug_logging （布尔）。

• get_logs\

说明：读取最近的NVDA日志行。\ 可选参数： max_lines （int，默认值100）， filter_level （字符串或空）， use_tail （bool，默认为true）。

______________________________________________________________________

项目结构

addon/
└── globalPlugins/
    └── nvdaMcp-bridge/
        ├── __init__.py
        ├── nvda_http_bridge.py
        ├── nvda_bridge.py
        ├── tool_registry.py
        └── tools/
            └── builtin_tools.py

• __init__.py –插件生命周期
• nvda_http_bridge.py –HTTP服务器和路由
• nvda_bridge.py –NVDA动作包装
• tool_registry.py / tools/ –工具发现和执行

______________________________________________________________________

发展

要添加新操作，请执行以下操作：

1. 在中实现该功能 nvda_bridge.py
2. 在中添加相应的工具 tools/builtin_tools.py
3. 确保NVDA API访问发生在主线程上
4. 返回JSON可序列化数据

______________________________________________________________________

局限性

• 仅限本地主机
• 单个HTTP侦听器
• 静态令牌，除非在代码中修改
• 无内置MCP协议实现

______________________________________________________________________

许可证

GPL v2 https://www.gnu.org/licenses/gpl-2.0.html