使用说明

项目简介

本项目 'akkaAgents' 演示了如何使用 Akka Actors 构建 AI Agent，并实现了基于 Anthropic Model Context Protocol (MCP) 的服务器和客户端。其中，Brave MCP Server 是一个基于 Java 开发的 MCP 服务器实现，它集成了 Brave 搜索 API，为支持 MCP 协议的 LLM 客户端提供 Web 搜索工具能力。

主要功能点

MCP 服务器实现: 实现了 MCP 协议，能够作为 MCP 服务器与客户端进行通信。
工具注册与执行: 注册了 'brave_web_search' 工具，允许 LLM 客户端通过调用该工具进行 Web 搜索。
基于 Brave 搜索 API: 集成了 Brave 搜索 API，提供高质量的 Web 搜索服务。
Stdio 传输协议: 使用 Stdio 作为 MCP 服务器的传输协议，简化部署和运行。
示例客户端: 包含一个 OpenAI MCP 客户端示例，展示了如何使用 MCP 服务器提供的工具。

安装步骤

安装 Java 23: 确保已安装 Java 23 或更高版本。
配置环境变量:
- 复制 'src/main/resources/env.sample' 文件为 'src/main/resources/.env'。
- 修改 '.env' 文件，填入你的 OpenAI API Key 和 Brave Search API Key。
编译项目: 使用 Gradle 命令编译项目，生成 fat jar 包。
```
./gradlew clean build
```

服务器配置

MCP 客户端需要配置以下信息以连接到 Brave MCP Server：

{
  "serverName": "brave-mcp-server",
  "command": "java",
  "args": [
    "-jar",
    "path/to/akkaAgents-1.0-SNAPSHOT-standalone.jar",  // 将 "path/to" 替换为 fat jar 包的实际路径，例如 "build/libs" 相对路径
    "--server"
  ]
}

参数注释:

'serverName': MCP 服务器的名称，客户端用于标识连接的服务器。
'command': 启动 MCP 服务器的命令，这里使用 'java' 命令。
'args': 启动命令的参数列表：
- '-jar': 指定运行 fat jar 包。
- '"path/to/akkaAgents-1.0-SNAPSHOT-standalone.jar"': 需要替换为实际的 fat jar 包路径。此路径应指向 Gradle 构建后生成的 'akkaAgents-1.0-SNAPSHOT-standalone.jar' 文件。例如，如果 fat jar 包位于 'build/libs' 目录下，则可以使用相对路径 '"build/libs/akkaAgents-1.0-SNAPSHOT-standalone.jar"'。
- '"--server"': 指定 'Main.java' 以服务器模式启动 Brave MCP Server。

MCP 客户端配置示例 (BraveClient.java 中已配置):

ServerParameters params = ServerParameters.builder("java")
        .args("-jar", serverJar, "--server")
        // ... 其他环境变量配置
        .build();

基本使用方法

启动 MCP 服务器:
- 可以通过命令行或 IntelliJ IDEA 启动 'com.theleoborges.researchagent.Main' 类，并添加 '--server' 参数。
- 使用 Gradle 命令直接运行服务器模式：
```
./gradlew runSystem -Pargs="'--server'"
```
- 或者，如果已经构建了 fat jar 包，可以直接使用 java 命令运行 (需要替换 jar 包路径)：
```
java -jar build/libs/akkaAgents-1.0-SNAPSHOT-standalone.jar --server
```
服务器启动后，将监听 Stdio 输入输出流，等待 MCP 客户端连接和请求。
配置 MCP 客户端:
- MCP 客户端需要根据 服务器配置 中的信息配置连接参数，例如在 'BraveClient.java' 中已经配置了连接到本地启动的 Brave MCP Server。
客户端调用工具:
- MCP 客户端连接到服务器后，可以列出服务器提供的工具 ('listTools' 方法) 并调用特定工具 ('callTool' 方法)，例如调用 'brave_web_search' 工具进行 Web 搜索。
- 在 'akkaAgents' 项目中，'SearchAgent' actor 使用 'BraveClient' 调用 'brave_web_search' 工具进行搜索。

运行示例客户端 (完整系统)

要运行包含 MCP 客户端和 Agent 的完整系统，可以直接运行 'com.theleoborges.researchagent.Main' 类，不添加 '--server' 参数。客户端将自动启动 Brave MCP Server 作为子进程，并进行后续的 Agent 流程 (查询优化、搜索、分析、报告生成等)。

./gradlew runSystem

可以添加 '-Pargs="'topic to research'"' 参数来指定研究主题。

./gradlew runSystem -Pargs="'your topic here'"

最终报告将生成在 'results/finalReport.md' 文件中。

关键词