内容
# mcp-agent
**使用模型上下文协议在TypeScript中构建有效的代理**
**mcp-agent** 是一个TypeScript框架，其灵感来自Python [lastmile-ai/mcp-agent](https://github.com/lastmile-ai/mcp-agent) 项目。它提供了一种简单、可组合且类型安全的方式来构建利用 [模型上下文协议（MCP）](https://modelcontextprotocol.io/introduction) 在JavaScript和TypeScript环境中的AI代理。
该库旨在将`mcp-agent`的强大模式和架构引入JavaScript生态系统，使开发人员能够创建强大且可控的AI代理，这些代理可以与支持MCP的服务和工具交互。
## 安装
```bash
npm install @joshuacalpuerto/mcp-agent
```
## 核心功能
**mcp-agent** 使您能够构建具有以下核心功能的复杂AI代理：
* **代理抽象：** 使用明确的指令、工具访问（本地函数和MCP服务器）和集成的LLM功能定义智能代理。
* **模型上下文协议（MCP）集成：** 与通过MCP服务器公开的服务和工具无缝连接和交互。
* **本地函数工具：** 使用自定义的进程内JavaScript/TypeScript函数作为工具，类似于MCP服务器工具。
* **LLM灵活性：** 与各种大型语言模型（LLM）集成。该库包括Fireworks AI的示例实现，展示了对不同LLM提供商的可扩展性。
* **内存管理：** 基本的内存消息历史记录，用于启用对话式代理。
* **工作流：** 实现复杂代理工作流，如`Orchestrator`模式，将任务分解为步骤并协调多个代理。支持来自Anthropic的[构建有效代理](https://www.anthropic.com/research/building-effective-agents)和OpenAI的[Swarm](https://github.com/openai/swarm)的其他模式即将推出。
* **TypeScript和类型安全：** 使用TypeScript构建，提供强大的类型、改进的代码可维护性和增强的开发人员体验。
## 快速入门
### 独立使用
使用基本示例快速入门（作为独立使用）：
```js
import { fileURLToPath } from 'url';
import path from 'path';
import { Agent, LLMFireworks, Orchestrator } from 'mcp-agent';
import { writeLocalSystem } from './tools/writeLocalSystem';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
async function runOrchestrator() {
const llm = new LLMFireworks("accounts/fireworks/models/deepseek-v3", {
maxTokens: 2048,
temperature: 0.1
});
const researcher = await Agent.initialize({
llm,
name: "researcher",
description: `您的专业知识是查找信息。`,
serverConfigs: [
{
name: "read_file_from_local_file_system",
type: "stdio",
command: "node",
args: ['--loader', 'ts-node/esm', path.resolve(__dirname, 'servers', 'readLocalFileSystem.ts'),]
},
{
name: "search_web",
type: "ws",
url: createSmitheryUrl(
"https://server.smithery.ai/exa/ws",
{
exaApiKey: process.env.EXA_API_KEY
}
)
},
],
});
const writer = await Agent.initialize({
llm,
name: "writer",
description: `您的专业知识是将信息写入文件。`,
functions: [writeLocalSystem],
llm,
});
const orchestrator = new Orchestrator({
llm,
agents: [researcher, writer],
});
const result = await orchestrator.generate('搜索关于AI的最新发展，并将其写入到本地计算机上的`theory_on_ai.md`文件中。无需验证结果。');
console.log(JSON.stringify(result));
await researcher.close();
await writer.close();
}
runOrchestrator().catch(console.error);
```
https://github.com/user-attachments/assets/122a388b-0dc8-4984-b189-22408a308d7f
**运行此示例：**
1. **安装依赖项：**
```bash
pnpm install
```
2. **设置环境变量：** 创建一个`.env`文件（或直接设置环境变量）并添加您的API密钥（例如`EXA_API_KEY`，如果需要Fireworks AI API密钥）。
3. **运行演示：**
```bash
node --loader ts-node/esm ./demo/standalone/index.ts
```
### REST服务器集成
有关具有多代理编排的完整Express.js集成示例，请参阅 [demo/express/README.md](./demo/express/README.md)。
## 核心概念
* **代理：** 基本构建块。`Agent`是一个具有特定角色、指令和工具访问权限的自主实体。代理可以调用工具来执行操作和与外部服务交互。
* **MCP服务器聚合器（`MCPServerAggregator`）：** 管理每个代理可用的工具。每个代理都有自己的聚合器，为其提供特定的工具集。聚合器充当其指定代理的工具提供者。
* **MCP连接管理器（`MCPConnectionManager`）：** 集中存储库，管理整个应用程序中所有MCP服务器连接的生命周期和重用。这是所有可用工具的全局集合，任何代理都可以潜在地使用。
* **支持的传输：** `stdio`、`sse`、`streamable-http`和`websockets`
* **LLM集成（`LLMInterface`、`LLMFireworks`）：** 抽象与大型语言模型的交互。`LLMFireworks`是Fireworks AI模型的示例实现。
* **工具：** 代理可以用来执行操作的函数或MCP服务器功能。工具可以是：
* **MCP服务器工具：** 外部MCP服务器公开的功能（例如文件系统访问、网络搜索）。
* **本地函数工具：** 在应用程序内直接定义的JavaScript/TypeScript函数。
* **工作流：** 用于构建复杂代理行为的可组合模式（参见Anthropic博客 [此处](https://www.anthropic.com/research/building-effective-agents)）。
* **编排器** - 工作流演示了如何协调多个代理以实现更大的目标。
* **提示链** - 即将推出。
* **路由** - 即将推出。
* **并行化** - 即将推出。
* **评估优化器** - 即将推出。
* **内存（`SimpleMemory`）：** 为对话式代理提供基本的内存消息历史记录。
## 架构：为什么使用连接管理器 + 聚合器？
该框架使用两层架构来高效管理MCP服务器连接：
**连接管理器（全局）：**
- 在整个应用程序中维护每个MCP服务器连接的单个实例
- 防止在多个代理需要相同工具时重复服务器连接
- 示例：如果Agent1和Agent2都需要文件系统工具，则只会启动一个文件系统服务器
**聚合器（每个代理）：**
- 每个代理都有自己的聚合器，提供对其特定工具集的访问
- 聚合器从全局连接管理器引用工具
- 作为其指定代理的工具提供者接口
**好处：**
- **资源效率：** 避免启动相同MCP服务器的多个实例
- **连接重用：** 在可能的情况下在代理之间共享服务器连接
- **隔离：** 每个代理只能看到其配置的工具
- **可扩展性：** 添加新代理而无需复制现有的服务器连接
## 评估
该项目使用 [RunLedger](https://pypi.org/project/runledger/) 进行确定性代理评估，通过录制带 replay。评估套件位于 [`evals/runledger/`](./evals/runledger/)，并在每次PR和推送到 `main` 时通过GitHub Actions自动运行。
```bash
# 在本地运行评估
python -m pip install "runledger==0.1.0"
runledger run evals/runledger --mode replay --baseline baselines/runledger-demo.json
```
参见 [评估README](./evals/runledger/README.md)，了解有关该套件的工作原理、消息协议以及如何添加新测试用例的详细信息。
## 致谢
该项目大量借鉴并建立在优秀的 [lastmile-ai/mcp-agent](https://github.com/lastmile-ai/mcp-agent) Python框架的概念和架构之上
我们鼓励您探索他们的存储库，以更深入地了解已为此TypeScript实现提供信息的底层原理和模式。
## 贡献
欢迎贡献！
MCP 市场