MCP AI Agent

这是一个基于 TypeScript 的 AI Agent 项目，用于探索 Agent 如何通过 MCP（Model Context Protocol）连接外部工具、调用 MCP Server，并在多轮任务中完成规划、检索、记忆和工具执行。

项目重点关注 Agent 的工具调用能力、MCP Server 接入方式、多 Agent 协作流程，以及面向 OpenAI-compatible 模型服务的灵活配置方式，适合用于学习、演示和二次开发。

项目目标

这个项目主要解决三个问题：

1. 让 AI Agent 可以统一接入不同 MCP Server。
2. 让模型在对话过程中自动选择和调用工具。
3. 让开发者可以用较少代码组合出单 Agent、多 Agent 和自定义工具工作流。

它适合作为一个轻量级 Agent 实验项目，用来验证 MCP 工具调用、任务拆解、多 Agent 协作和模型切换能力。

核心能力

• 支持通过 STDIO 或 SSE 连接 MCP Server。
• 支持自动发现 MCP Server 暴露的工具。
• 支持接入 AI SDK v5 的模型接口。
• 支持 OpenAI、Anthropic 以及 OpenAI-compatible 模型服务。
• 支持配置默认模型，减少多 Agent 场景下的重复代码。
• 支持多 Agent 组合，让一个主 Agent 调度多个专用 Agent。
• 支持直接在 Agent 配置中声明自定义工具。
• 支持系统提示词，便于定义 Agent 的角色和行为边界。
• 支持 verbose 调试模式，方便观察工具调用流程。

技术栈

• TypeScript
• Node.js
• AI SDK v5
• MCP（Model Context Protocol）
• Zod
• tsup
• Jest

安装依赖

npm install

如果需要使用 OpenAI 模型：

npm install @ai-sdk/openai

如果需要使用 Anthropic 模型：

npm install @ai-sdk/anthropic

环境变量

根据你使用的模型服务配置 API Key。

OPENAI_API_KEY=your_api_key_here

如果使用 OpenAI-compatible 服务，可以在模型初始化时配置 baseURL。例如接入兼容 OpenAI Chat Completions 协议的模型服务时，可根据服务商文档设置：

import { createOpenAI } from "@ai-sdk/openai";

const customProvider = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

MiMo 或其他国产模型服务如果提供 OpenAI-compatible API，也可以使用类似方式接入。

最小示例

下面示例创建了一个带 Sequential Thinking MCP 工具的 Agent。模型可以在回答问题时调用 MCP 工具进行逐步推理。

import { AIAgent, Servers } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";

const agent = new AIAgent({
  name: "任务规划 Agent",
  description: "用于拆解复杂任务并给出执行步骤",
  model: openai("gpt-4o-mini"),
  systemPrompt: "你是一个严谨的任务规划助手，请先拆解问题，再给出清晰答案。",
  toolsConfigs: [Servers.sequentialThinking],
});

const response = await agent.generateResponse({
  prompt: "帮我规划一个使用 AI Agent 完成信息处理任务的步骤。",
});

console.log(response.text);
await agent.close();

自定义工具示例

除了 MCP Server，也可以直接给 Agent 添加自定义工具。下面示例添加了一个简单的乘法工具。

import { AIAgent } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const agent = new AIAgent({
  name: "计算 Agent",
  description: "可以调用工具完成数学计算",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [
    {
      type: "tool",
      name: "multiply",
      description: "计算两个数字的乘积",
      parameters: z.object({
        number1: z.number(),
        number2: z.number(),
      }),
      execute: async ({ number1, number2 }) => {
        return number1 * number2;
      },
    },
  ],
});

const response = await agent.generateResponse({
  prompt: "请计算 125 * 37。",
});

console.log(response.text);
await agent.close();

多 Agent 工作流

项目支持把多个专用 Agent 组合成一个主 Agent。例如：

• 规划 Agent：负责拆解任务。
• 搜索 Agent：负责联网或资料检索。
• 记忆 Agent：负责保存和读取上下文。
• 主控 Agent：根据任务类型把工作分发给合适的专用 Agent。

这种结构适合构建更复杂的自动化流程，例如项目计划生成、信息处理、代码分析、知识库问答等。

import { AIAgent, Servers } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";

const plannerAgent = new AIAgent({
  name: "规划 Agent",
  description: "负责拆解任务和生成执行计划",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [Servers.sequentialThinking],
});

const memoryAgent = new AIAgent({
  name: "记忆 Agent",
  description: "负责保存和读取重要信息",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [Servers.memory],
});

const masterAgent = new AIAgent({
  name: "主控 Agent",
  description: "根据任务选择合适的子 Agent 执行",
  model: openai("gpt-4o"),
  toolsConfigs: [
    {
      type: "agent",
      agent: plannerAgent,
    },
    {
      type: "agent",
      agent: memoryAgent,
    },
  ],
});

const response = await masterAgent.generateResponse({
  prompt: "请拆解一个信息处理和模型兼容配置的开发任务，并保存关键结论。",
});

console.log(response.text);
await masterAgent.close();

支持的 MCP Server

项目内置了一些常用 MCP Server 配置，可以直接通过 Servers 使用：

• Servers.sequentialThinking：逐步推理和任务拆解。
• Servers.memory：上下文记忆。
• Servers.braveSearch：网络搜索。
• Servers.fetch：URL 内容获取。
• Servers.sqlite：SQLite 数据查询。
• Servers.firecrawl：网页抓取和信息提取。
• Servers.awsKbRetrieval：AWS Knowledge Base 检索。
• Servers.everart：图像生成相关能力。

运行开发示例

仓库中包含 minimal-example.ts，可以作为本地验证入口。

npm run dev

如果更新了源码，可以执行构建：

npm run build

运行测试：

npm test

扩展方向

项目可以继续扩展以下能力：

• 增加中文任务规划 Agent 示例。
• 增加 OpenAI-compatible / MiMo-compatible 模型配置模板。
• 增加文件摘要工具，让 Agent 读取本地文档并生成摘要。
• 增加一个完整的 MCP 工具调用日志示例。
• 增加 Web API 服务层，让外部应用可以通过 HTTP 调用 Agent。
• 增加更清晰的 Agent 执行流程图和运行截图。

许可证

MIT License