AI导哈

多模型对话代理

基于多种大语言模型（如Google Gemini、Anthropic Claude等）的Web对话代理，支持通过MCP协议与外部服务（如WhatsApp、GitHub等）交互，实现自动化任务处理。

  • by allanbrewer
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 allanbrewer/mcp-agent

使用说明

MCP代理

一个基于网络的会话代理，由各种LLM（Google Gemini、Anthropic Claude、OpenAI GPT、xAI Grok）通过Vercel AI SDK提供支持，能够通过模型上下文协议（MCP）服务器与外部服务进行交互。

概述

该项目提供了一个聊天界面，用户可以在其中选择LLM提供者和模型，然后与所选的LLM进行对话。该代理利用Vercel AI SDK处理多步骤工具执行，允许LLM与配置的MCP服务器（例如WhatsApp、GitHub、GSuite、Web Search）交互以满足用户请求。

建筑

该项目由以下部分组成：

  1. 前端(mcp-agent-app/): Next.js应用程序提供基于React的聊天界面，可在以下网址访问 http://localhost:3000.
    • 用途 @ai-sdk/reacts useChat 用于管理聊天状态和流式响应的钩子。
    • 使用React上下文(ChatContext)管理应用程序状态，如当前聊天ID、所选提供商/型号，并提供对 useChat 钩子的状态和功能。
    • 包括一个侧边栏，用于选择LLM提供商/模型和管理保存的聊天记录。
  2. 聊天API(mcp-agent-app/src/app/api/chat/route.ts): Next.js API路由：
    • 从前端接收聊天消息、提供商ID和型号ID。
    • 选择并实例化适当的LLM提供者（例如。， @ai-sdk/google, @ai-sdk/anthropic)根据请求。
    • 从加载MCP服务器配置 mcp-config.json.
    • 使用助手(prepareStdioArgs)解析服务器命令的路径和环境变量。
    • 使用初始化MCP客户端 experimental_createMCPClient 和 Experimental_StdioMCPTransport 从 ai 和 ai/mcp-stdio.
    • 使用以下命令直接从初始化的MCP客户端获取工具模式 mcpClient.tools().
    • 调用Vercel AI SDK streamText 函数，传递选定的语言模型、消息和合并的MCP工具。
    • 依赖 streamText （与 maxSteps > 1)以处理多步骤对话流，包括通过MCP客户端自动调用工具。
    • 由于当前SDK与stdio工具不兼容，包括禁用Anthropic工具的解决方法。
    • 使用以下命令将响应（文本块、错误）流式传输回前端 result.toDataStream().
    • 关闭中的MCP客户端连接 onFinish 回拨。
  3. 聊天持久性API(mcp-agent-app/src/app/api/chats/): Next.js API路由用于使用Prisma和SQLite数据库保存、加载、列出和删除聊天会话。存储聊天记录(CoreMessage[])、标题、提供者ID和型号ID。
  4. MCP服务器： 实现模型上下文协议（MCP）的外部进程（Python脚本、Docker容器）。聊天API后端通过 StdioMCPTransport 基于 mcp-config.json.
  5. 配置：
    • mcp-agent-app/mcp-config.json：定义可用的MCP服务器、启动命令和工具模式（尽管现在模式主要是动态发现的）。
    • mcp-agent-app/llm-config.json：定义前端UI的可用LLM提供者及其模型。
    • mcp-agent-app/.env.local：存储后端和MCP服务器所需的API密钥、令牌和路径。

设置

先决条件：

  • Node.js （推荐LTS版本）
  • npm 或 纱线
  • 紫外线 （Python包管理器）
  • 码头工人 （适用于GitHub MCP服务器）
  • LLM API密钥： 获取您要使用的提供商的密钥（Google Gemini、Anthropic Claude、OpenAI GPT、xAI Grok）。设置它们 .env.local.
  • GitHub个人访问令牌（PAT）： 创建一个 具有适当的范围（例如。， repo, read:user).设置为 GITHUB_PERSONAL_ACCESS_TOKEN 在……里面 .env.local.
  • GSuite OAuth2凭据： 按照以下步骤操作 GSuite MCP服务器 部分。

安装和配置：

  1. 克隆存储库：
    git clone <repository_url>
cd mcp-agent
  2. 安装Next.js应用程序依赖项：
    cd mcp-agent-app
npm install
# or yarn install
  3. 配置环境变量：
    • 创建 .env.local 在……里面 mcp-agent-app/.
    • 添加API密钥、令牌和配置路径。例子：
      # .env.local

# LLM API Keys (Add keys for providers you want to use)
GOOGLE_API_KEY=YOUR_GEMINI_API_KEY
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
XAI_API_KEY=YOUR_XAI_API_KEY

# GitHub Token
GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT

# Paths (Adjust if needed, especially if uv isn't in PATH)
# UV_PATH=/path/to/your/uv # Optional override
WHATSAPP_MCP_SCRIPT_DIR=../whatsapp-mcp/whatsapp-mcp-server # Relative paths often work
GSUITE_MCP_SCRIPT_DIR=../mcp-gsuite
GSUITE_GAUTH_FILE=../mcp-gsuite/.gauth.json
GSUITE_ACCOUNTS_FILE=../mcp-gsuite/.accounts.json
GSUITE_CREDENTIALS_DIR=../mcp-gsuite/gsuite-credentials # Directory for storing token.json
DDG_MCP_SCRIPT_DIR=../duckduckgo-mcp-server

# Database URL (SQLite)
DATABASE_URL="file:./dev.db"
    • 替换占位符。确保路径相对于 mcp-agent-app 目录或使用绝对路径。
  4. 设置数据库：
    npx prisma migrate dev --name init # Or your latest migration name

运行应用程序：

  • MCP服务器： 确保所需的MCP服务器正在运行或可访问（例如，为GitHub运行Docker守护进程，如果需要，手动启动其他服务器，尽管应用程序试图通过stdio启动它们）。
    • 注： 当前的实施通过以下方式按需启动MCP服务器 StdioMCPTransport。除非调试特定的服务器，否则通常不需要手动启动它们。确保WhatsApp Go桥等先决条件 是 如果服务器需要，则运行。
  • 启动Next.js应用程序：
    cd mcp-agent-app
npm run dev
# or yarn dev
  • 打开 http://localhost:3000.

用法

  • 从侧栏下拉菜单中选择所需的LLM提供者和模型。
  • 与聊天界面交互。
  • 代理将使用所选的LLM，并在适当的时候尝试使用配置的MCP工具（Anthropic除外，该工具当前已禁用）。
  • 使用“保存聊天”按钮来保持对话。从历史记录列表中加载以前的聊天记录。

示例提示：

  • Who are you?
  • Search the web for the latest AI news. （使用ddg搜索）
  • Get issue number 1 from the vercel/ai repository. （使用github）
  • Send a WhatsApp message to [Number] saying "Test from MCP Agent" （使用whatsapp）
  • What's on my main Google Calendar today? （使用gsuite）

添加新的MCP服务器

  1. 实施MCP服务器： 开发一个通过stdio/JSON-RPC通信的服务器。
  2. 更新 mcp-config.json: 添加一个服务器条目，定义其 id, description，以及 command （包括 executableEnvVar/defaultExecutable, argsTemplate, scriptDirEnvVar, envVars).配置中的工具模式现在不那么重要了，因为它们是动态发现的，但描述是有帮助的。
  3. 更新 .env.local: 为新服务器的命令添加任何必需的环境变量。
  4. 重启 这 mcp-agent-app。后端将尝试从新服务器连接和发现工具。

当前MCP服务器

（描述基本保持不变，但执行现在由 StdioMCPTransport)

WhatsApp MCP服务器

  • 来源： whatsapp-mcp/
  • 执行： Python脚本通过 uv run。需要单独运行Go桥。
  • 配置： WHATSAPP_MCP_SCRIPT_DIR

GitHub MCP服务器

  • 来源： Docker镜像(ghcr.io/github/github-mcp-server)
  • 执行： Docker容器通过 docker run。需要Docker守护进程运行。
  • 配置： GITHUB_PERSONAL_ACCESS_TOKEN

GSuite MCP服务器

  • 来源： mcp-gsuite/
  • 执行： Python脚本通过 uv run.
  • 配置： GSUITE_MCP_SCRIPT_DIR, GSUITE_GAUTH_FILE, GSUITE_ACCOUNTS_FILE, GSUITE_CREDENTIALS_DIR。需要OAuth2设置。

DuckDuckGo搜索MCP服务器

  • 来源： duckduckgo-mcp-server/
  • 执行： Python模块通过 uv run.
  • 配置： DDG_MCP_SCRIPT_DIR

文件和文件夹结构

mcp-agent/ (Project Root)
├── .gitignore
├── LICENSE
├── README.md (This file)
├── docs/ (Additional documentation)
├── mcp-agent-app/ (Next.js Application)
│   ├── .env.local (API Keys, Paths, DB URL)
│   ├── llm-config.json (LLM Provider/Model definitions for UI)
│   ├── mcp-config.json (MCP server command configurations)
│   ├── next.config.ts
│   ├── package.json
│   ├── prisma/
│   │   └── schema.prisma (Database schema)
│   │   └── migrations/
│   ├── src/
│   │   ├── app/
│   │   │   ├── api/
│   │   │   │   ├── chat/route.ts (Main chat API, uses Vercel AI SDK)
│   │   │   │   └── chats/ (API routes for saving/loading chats)
│   │   │   └── page.tsx (Main page component)
│   │   ├── components/ (React components: ChatInterface, Sidebar, etc.)
│   │   ├── context/
│   │   │   └── ChatContext.tsx (Manages app state, integrates useChat hook)
│   │   └── lib/
│   │       └── prisma.ts (Prisma client instance)
│   └── ... (Other Next.js files)
├── duckduckgo-mcp-server/
├── github-mcp-server/ (Source code, not directly run if using Docker image)
├── mcp-gsuite/
└── whatsapp-mcp/
    ├── whatsapp-bridge/ (Go component - needs separate execution)
    └── whatsapp-mcp-server/ (Python component)

调试

  • 检查Next.js服务器的终端日志(npm run dev).查找API密钥状态、提供程序/模型使用、MCP初始化步骤以及 streamText.
  • 检查浏览器控制台日志，了解上下文操作和潜在的前端错误。
  • 如果MCP服务器初始化失败，请检查 prepareStdioArgs 记录并确保中的路径和环境变量 .env.local 是正确的。
  • 验证API密钥和令牌。

许可证

该项目根据麻省理工学院开源许可证条款获得许可。请参考 麻省理工学院 完整的条款。

相关 MCP