使用说明

项目简介

'mcp-agent' 是一个用于构建智能体的框架，旨在简化基于 Model Context Protocol (MCP) 的应用开发。它提供 Agent 和 Orchestrator 等核心组件，帮助开发者快速搭建能够利用 MCP 服务器提供的工具和资源的智能体系统。该仓库包含可运行的 MCP 服务器示例，方便用户理解和测试 MCP 服务器的功能。

请注意，'mcp-agent' 主要是一个客户端框架，用于构建使用 MCP 服务器的智能体。它本身不是一个独立的、通用的 MCP 服务器实现，但它包含了示例 MCP 服务器代码，用于演示和测试目的。如果你需要一个通用的、生产级别的 MCP 服务器，可能需要寻找更专业的 MCP 服务器项目。

主要功能点

智能体 (Agent) 组件: 用于定义具备特定技能和描述的智能体，可以配置连接到不同的 MCP 服务器以获取工具，并能调用本地函数工具。
编排器 (Orchestrator) 组件: 用于编排多个智能体协同工作，完成复杂任务，支持规划任务步骤和分配给不同的智能体执行。
LLM 集成: 支持集成多种 LLM 模型 (如示例中使用的 Fireworks LLM)，作为智能体的推理引擎。
MCP 服务器连接: 通过 'MCPServerAggregator' 管理与多个 MCP 服务器的连接，支持 Stdio, WebSocket 等多种传输协议。
工具 (Tools) 扩展: 允许智能体使用 MCP 服务器提供的工具和本地定义的函数工具。
示例 MCP 服务器: 仓库包含 'readLocalFileSystem.ts' 和 'searchWeb.ts' 等示例 MCP 服务器代码，展示了如何基于 '@modelcontextprotocol/sdk/server' 构建 MCP 服务器。这些示例服务器提供了文件读取和模拟网页搜索等工具。

安装步骤

安装 Node.js 和 npm: 确保你的系统已安装 Node.js 和 npm (Node 包管理器)。

克隆仓库: 将 'mcp-agent' 仓库克隆到本地。

git clone https://github.com/joshuaalpuerto/mcp-agent.git
cd mcp-agent

安装依赖: 在仓库根目录下运行 'npm install' 安装项目依赖。
```
npm install
```

服务器配置 (MCP客户端视角)

要让 'mcp-agent' 框架中的 Agent 连接到 MCP 服务器，你需要在 Agent 的配置中指定 'serverConfigs'。以下是 'demo/index.ts' 中 'researcher' Agent 的 'serverConfigs' 配置示例，展示了如何配置连接到两个不同的 MCP 服务器：

[
  {
    "name": "read_file_from_local_file_system",
    "type": "stdio",
    "command": "node",
    "args": ["--loader", "ts-node/esm", "./demo/servers/readLocalFileSystem.ts"]
    // "command": "node" -  启动 MCP 服务器的命令，这里使用 Node.js 运行
    // "args": [...]  -  传递给启动命令的参数，
    //    "--loader ts-node/esm" 用于支持 TypeScript 模块加载，
    //    "./demo/servers/readLocalFileSystem.ts" 是 MCP 服务器脚本的路径
  },
  {
    "name": "search_web",
    "type": "ws",
    "url": "wss://server.smithery.ai/exa/ws?exaApiKey=YOUR_EXA_API_KEY"
    // "type": "ws" -  指定连接类型为 WebSocket
    // "url": "wss://..." -  WebSocket 服务器的 URL，
    //    请替换 "YOUR_EXA_API_KEY" 为实际的 API Key (如果需要)
  }
]

配置说明:

'name': 服务器的名称，用于在 Agent 中引用。
'type': 连接服务器使用的传输协议，可以是 'stdio' (标准输入输出), 'ws' (WebSocket), 'sse' (SSE)。
'command': (仅 'stdio' 类型需要) 启动 MCP 服务器进程的命令，例如 'node', 'python' 等。
'args': (仅 'stdio' 类型需要) 传递给启动命令的参数数组，用于指定服务器脚本路径、配置等。
'url': (仅 'ws' 和 'sse' 类型需要) MCP 服务器的 URL 地址，例如 'ws://localhost:8080' 或 'https://example.com/sse'。

运行示例 MCP 服务器 (Stdio 类型):

仓库的 'demo/servers' 目录下提供了 'readLocalFileSystem.ts' 和 'searchWeb.ts' 示例 MCP 服务器。要运行 'readLocalFileSystem.ts' 服务器 (供 'stdio' 类型的 Agent 连接)，你可以：

确保已安装 'ts-node' (如果未安装，请运行 'npm install -g ts-node')。

在项目根目录下，根据 'serverConfigs' 中的配置，使用命令手动启动服务器 (虽然 'mcp-agent' 框架在示例中会自动启动 'stdio' 服务器，但了解手动启动方式有助于调试和理解):

node --loader ts-node/esm ./demo/servers/readLocalFileSystem.ts

或者，在 'package.json' 的 'scripts' 中添加类似脚本：

"scripts": {
    "start-read-file-server": "node --loader ts-node/esm ./demo/servers/readLocalFileSystem.ts"
}

然后运行 'npm run start-read-file-server'。

基本使用方法

导入模块: 在你的代码中导入 'mcp-agent' 的相关模块。

import { Agent, Orchestrator, LLMFireworks } from 'mcp-agent';

创建 LLM 实例: 根据需要创建 LLM 实例，例如 'LLMFireworks'。

const llm = new LLMFireworks("accounts/fireworks/models/deepseek-v3", { /* ...配置... */ });

定义 Agent: 使用 'Agent.initialize()' 方法创建 Agent，配置 'name', 'description', 'serverConfigs' (连接 MCP 服务器) 和 'functions' (本地函数工具)。

const researcher = await Agent.initialize({
    name: "researcher",
    description: "Your expertise is to find information.",
    serverConfigs: [ /* ...服务器配置... */ ],
});

const writer = await Agent.initialize({
    name: "writer",
    description: "Your expertise is to write information to a file.",
    functions: [ /* ...本地函数工具... */ ],
    llm,
});

创建 Orchestrator (可选): 如果需要编排多个 Agent，创建 'Orchestrator' 实例。

const orchestrator = new Orchestrator({
    llm,
    agents: [researcher, writer],
});

执行任务: 使用 Agent 或 Orchestrator 的 'generate()' 方法执行任务。

const result = await orchestrator.generate('Search new latest development about AI and write about it to 'theory_on_ai.md' on my local machine.');
console.log(JSON.stringify(result));

关闭连接: 在程序结束时，调用 Agent 的 'close()' 方法关闭与 MCP 服务器的连接。

await researcher.close();
await writer.close();

请参考 'demo/index.ts' 示例代码，了解更详细的使用方法和示例。

关键词