使用说明
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 包裹。
安装
- 构建插件。
- 打开生成的
.nvda-addon文件。 - 重新启动NVDA。
当NVDA加载插件时，HTTP侦听器启动。
API终点
GET/健康
未经身份验证的健康检查。
GET/工具
返回发现的工具和元数据。
需要标题：
X-NVDA-Bridge-Token: <token>
POST/操作
运行一个动作。
需要标题：
X-NVDA-Bridge-Token: <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/–工具发现和执行
发展
要添加新操作，请执行以下操作：
- 在中实现该功能
nvda_bridge.py - 在中添加相应的工具
tools/builtin_tools.py - 确保NVDA API访问发生在主线程上
- 返回JSON可序列化数据
局限性
- 仅限本地主机
- 单个HTTP侦听器
- 静态令牌，除非在代码中修改
- 无内置MCP协议实现
