nova-act-mcp

一个 MCP 服务器，提供使用 Amazon Nova Act SDK 控制 Web 浏览器的工具。通过 MCP 实现交互式浏览器自动化，并提供透明的代理推理过程。

目录

• 什么是 nova-act-mcp?
• 前提条件
• 安装
• 快速开始
• 理解代理的思考过程
• 有效浏览器自动化的技巧
• 高级功能
• 示例用例
• 性能考虑
• 测试
• 故障排除
• 贡献
• 许可证
• 致谢
• Amazon Nova Act 的反馈
• 局限性
• 开发

什么是 nova-act-mcp?

Nova Act MCP 是 Amazon 的 Nova Act 浏览器自动化 SDK 和模型上下文协议 (MCP) 之间的桥梁。它允许像 Claude 这样的人工智能助手通过自然语言指令控制 Web 浏览器来执行任务，同时提供对代理推理过程的可见性。

该项目通过 MCP 服务器接口公开了 Nova Act 强大的浏览器自动化功能，使其易于：

1. 直接从 AI 助手控制 Web 浏览器
2. 执行交互式浏览器自动化任务
3. 从网页中提取结构化数据
4. 在交互之间维护浏览器会话
5. 查看代理的逐步推理过程

前提条件

开始之前，您需要：

• Python 3.10 或更高版本
• 一个 Amazon Nova Act API 密钥（从 https://nova.amazon.com/act 获取）
• Claude Desktop 应用程序（用于与 Claude 一起使用）

安装

1. 克隆此存储库：

   git clone https://github.com/yourusername/nova-act-mcp.git
   cd nova-act-mcp
   

2. 安装依赖项：

在更改 pyproject.toml 后更新依赖项

uv sync

仅用于开发 - 如果您需要添加新的依赖项

uv add package_name

快速开始

本指南重点介绍如何使用 Claude Desktop 应用程序设置服务器，但 nova-act-mcp 旨在与任何模型上下文协议 (MCP) 兼容的客户端一起使用，例如 Visual Studio Code 或其他客户端。有关集成 MCP 服务器的说明，请参阅特定客户端的文档。

1. 获取 Nova Act API 密钥

1. 前往 https://nova.amazon.com/act
2. 生成一个新的 API 密钥
3. 保存它以供下一步使用

2. 配置您的 MCP 客户端（示例：Claude Desktop）

以下步骤展示了如何配置 Claude Desktop 应用程序。如果您使用的是不同的 MCP 客户端，请相应地调整这些说明。

1. 从 https://claude.ai/desktop 安装 Claude Desktop（如果使用 Claude）。

2. 打开您的 Claude for Desktop App 配置：

   # MacOS
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   code %USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json
   

3. 添加 nova-act-mcp 服务器配置：

   {
     "mcpServers": {
       "nova-browser": {
         "command": "uv",
         "args": [
           "--directory",
           "/full/path/to/nova-act-mcp",
           "run",
           "nova_mcp.py"
         ],
         "transport": "stdio",
         "env": {
           "NOVA_ACT_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

   替换：

   • /full/path/to/nova-act-mcp 为您克隆此存储库的绝对路径
   • your_api_key_here 为您实际的 Nova Act API 密钥

4. 保存文件并重启 Claude Desktop

3. 与您的 MCP 客户端一起使用（示例：Claude）

配置完成后，您可以将浏览器自动化工具与您的 MCP 客户端一起使用。对于 Claude Desktop，请查找锤子图标 (🔨)，它表示可用的 MCP 工具。

尝试一个简单的例子，如下所示：

你能帮我在 Google 上搜索新闻吗？使用 nova-browser 工具来：
1. 在 google.com 上启动一个会话
2. 执行指令“搜索新闻”
3. 告诉我你看到了什么以及你的推理过程

理解代理的思考过程

nova-act-mcp 的关键功能之一是能够看到代理的推理过程。当代理在浏览器中执行操作时，您将看到详细的解释：

1. 它如何解释您的指令
2. 它在页面上看到了哪些元素
3. 为什么它选择特定的操作
4. 它如何确认成功完成

这种透明性有助于您了解代理如何处理任务，并在出现问题时更容易进行调试。

有效浏览器自动化的技巧

具体且简洁

在提示浏览器操作时：

✅ 应该:

• 提供清晰、可操作的指令
• 一次专注于一项任务
• 具体说明要与哪些元素交互

❌ 不应该:

• 使用模糊或模棱两可的语言
• 在单个指令中请求复杂的、多步骤的操作
• 在没有明确标准的情况下要求进行主观评估

良好指令的示例

不要试图一次完成所有事情，而是将其分解为交互式步骤：

1. 在 amazon.com 上启动一个会话
2. 执行“搜索蓝牙耳机”
3. 执行“按 4 星以上过滤”
4. 执行“按价格从低到高排序”
5. 执行“查找第一个商品的价格”

高级功能

持久浏览器会话

nova-act-mcp 服务器在 profiles/ 目录中维护浏览器配置文件，允许您：

• 在使用之间维护登录会话
• 保留 cookie 和本地存储数据
• 在以后的对话中恢复工作流程

每个配置文件都是隔离的，因此您可以维护不同的身份或登录状态。

浏览器会话管理

以下操作可用于浏览器会话管理：

1. start - 使用指定的 URL 启动新的浏览器会话
2. execute - 在当前会话中执行自然语言指令
3. extract - 从当前网页中提取结构化数据
4. end - 结束当前浏览器会话并清理资源

示例流程：

# 启动一个会话
start: https://www.google.com

# 执行指令
execute: 搜索新闻
execute: 点击第一个结果

# 提取特定数据
extract: 从页面中提取所有新闻标题

# 结束会话
end

数据提取

extract 操作允许您使用自然语言查询从网页中抓取和结构化数据。这对于以下情况特别有用：

• 从新闻网站收集新闻标题
• 从电子商务页面提取产品信息
• 从表格和列表中收集数据
• 编译搜索结果信息

要使用 extract 功能：

1. 启动一个浏览器会话
2. 导航到包含要提取的数据的页面
3. 使用 extract 操作，并使用描述要提取内容的特定查询

示例：

# 提取新闻标题
extract: 从页面中提取所有新闻标题

# 提取产品信息
extract: 提取此页面上所有产品的价格和名称

# 从表格中提取结构化数据
extract: 将表格数据提取为带有标题的 JSON 数组

extract 功能返回可以进一步处理或分析的结构化数据。

示例用例

以下是您可以使用 nova-act-mcp 完成的更复杂的任务：

电子商务价格比较

1. 在 amazon.com 上启动一个会话
2. 执行“搜索无线耳机”
3. 提取“获取前 5 个结果的价格和评分”
4. 执行“返回搜索结果”
5. 执行“按品牌过滤：Sony, Bose”
6. 提取“比较 Sony 与 Bose 耳机的价格”
7. 在 bestbuy.com 上启动一个新会话
8. 执行“搜索在 Amazon 上找到的相同 Sony 型号”
9. 提取“获取价格和可用性”
10. 执行“查找价格匹配政策”

研究和数据收集

1. 在 scholar.google.com 上启动一个会话
2. 执行“搜索 '大型语言模型应用 2023'”
3. 执行“按去年过滤”
4. 提取“获取前 10 篇论文的标题、作者和引用次数”
5. 执行“点击引用次数最多的论文”
6. 提取“总结摘要和主要发现”
7. 执行“查找并列出参考文献部分”
8. 提取“识别参考文献中引用次数最多的作者”

旅行计划

1. 在 kayak.com 上启动一个会话
2. 执行“搜索 10 月份从旧金山到东京的航班”
3. 执行“仅过滤直飞航班”
4. 提取“查找最便宜的直飞航班选项”
5. 执行“选择最便宜的航班”
6. 在 hotels.com 上启动一个新会话
7. 执行“搜索新宿站附近东京的酒店”
8. 执行“按 4 星以上且每晚 200 美元以下过滤”
9. 提取“列出前 3 个选项及其设施和评论”
10. 执行“检查 10 月 10-17 日的可用性”

性能考虑

在进行大规模浏览器自动化时，请记住以下性能考虑因素：

资源管理

• 并发会话：每个浏览器会话都会消耗大量内存。对于大规模自动化，请考虑实施会话池并限制并发会话。
• 内存使用：Chrome 实例每个可以使用 300MB-1GB 的 RAM。运行多个会话时，请监视内存使用情况。
• CPU 利用率：浏览器自动化是 CPU 密集型的，尤其是在解析复杂页面时。安排任务以避免 CPU 饱和。

优化策略

• 无头模式：对于生产环境，请考虑在无头模式下运行浏览器，以提高资源效率。
• 请求限制：实施速率限制以避免触发网站上的反机器人措施。
• 缓存：在适当的时候缓存响应以减少冗余请求。
• 高效选择器：使用精确的选择器而不是广泛的指令来提高性能。

大规模自动化的最佳实践

• 会话重用：在适当的情况下，重用浏览器会话而不是创建新会话。
• 清理：始终在完成后正确结束会话以释放系统资源。
• 批处理：将相关任务分组到批处理中，以最大限度地减少会话创建的开销。
• 错误处理：实施强大的错误处理，并为瞬时故障自动重试。

测试

您可以使用 MCP Inspector 工具测试 nova-act-mcp 服务器：

# 如果您尚未安装 MCP Inspector，请安装它
npm install -g @modelcontextprotocol/inspector

# 使用 MCP Inspector 运行服务器
NOVA_ACT_API_KEY="your_api_key_here" npx @modelcontextprotocol/inspector uv --directory /path/to/nova-act-mcp run nova_mcp.py

然后使用以下输入格式来测试一个简单的浏览器操作：

{
  "action": "start",
  "url": "https://www.google.com"
}

然后：

{
  "action": "execute",
  "session_id": "your_session_id_from_previous_response",
  "instruction": "search for tea pots"
}

这使您可以验证服务器是否正常工作，并准确地了解代理在每个步骤中的想法。

故障排除

Nova Act API 密钥问题

如果您看到有关 Nova Act API 密钥的错误：

1. 在 https://nova.amazon.com/act 验证您的 API 密钥是否有效
2. 检查密钥是否已在您的 Claude Desktop 配置中正确设置
3. 尝试将其设置为环境变量：export NOVA_ACT_API_KEY="your_key_here"

浏览器自动化问题

如果浏览器未按预期运行：

1. 检查响应中的 agent_thinking 字段，以查看代理如何解释您的指令
2. 使您的指令更具体和可操作
3. 对于涉及表单或登录的任务，请明确说明字段名称

调试模式

要启用更详细的调试信息：

export NOVA_MCP_DEBUG=1

这将在响应中包含其他诊断信息。

贡献

我们欢迎您为改进 nova-act-mcp 做出贡献！以下是您可以提供帮助的方式：

开始开发

1. Fork 存储库
2. 创建一个功能分支：git checkout -b feature-name
3. 进行更改并添加测试（如果适用）
4. 运行测试以确保您的更改正常工作
5. 提交您的更改：git commit -m 'Add some feature'
6. 推送到分支：git push origin feature-name
7. 提交拉取请求

开发指南

• 遵循现有的代码风格和命名约定
• 编写清晰、注释的代码，并使用有意义的变量/函数名称
• 为任何新功能添加文档
• 为新功能添加测试
• 必要时更新 README

报告问题

如果您发现错误或有功能请求，请在存储库上创建一个问题。包括：

• 对问题或功能请求的清晰描述
• 重现步骤（对于错误）
• 预期行为
• 实际行为
• 环境信息（操作系统、Python 版本等）

代码审查

所有提交都需要在合并之前进行审查。我们的目标是及时审查拉取请求并提供建设性的反馈。

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• Amazon Nova Act 提供浏览器自动化 SDK
• 模型上下文协议 (MCP) 提供 AI 代理通信标准

Amazon Nova Act 的反馈

虽然我们已经实现了代理思维提取，但我们注意到，理想情况下，这些信息应该可以直接通过 Nova Act API 访问。当前的方法需要解析 HTML 跟踪文件，这不如使用专用 API 方法有效。我们欢迎未来对 Nova Act SDK 进行任何改进，以使此过程更加简单。

局限性

• 无法上传文件：浏览器自动化无法从您的本地系统上传文件
• 仅限于 Web 交互：只能与网页上可见的元素交互
• 某些网站可能会阻止自动化：具有强大反机器人措施的网站可能会带来挑战
• 会话超时：长时间运行的会话可能会被网站终止

开发

管理依赖项

本项目使用 uv 进行依赖项管理，它提供更快、更可靠的 Python 包管理。

要更新或添加依赖项：

1. 编辑 pyproject.toml 文件，在适当的部分中添加或修改依赖项：

   dependencies = [
       "new-package>=1.0.0",  # 在此处添加您的新依赖项
   ]
   

2. 使用 uv sync 更新锁定文件：

   uv sync
   

3. 将修改后的 pyproject.toml 和更新后的 uv.lock 文件都提交到存储库。

这确保了所有开发人员和用户都具有一致的依赖项版本。