MCP Agent

MCP Agent

一个基于 Web 的对话式 Agent，通过 Vercel AI SDK 使用各种大模型（Google Gemini、Anthropic Claude、OpenAI GPT、xAI Grok），能够通过 Model Context Protocol（MCP）服务与外部服务交互。

概述

本项目提供了一个聊天界面，用户可以选择大模型提供商和模型，然后与所选大模型对话。Agent 利用 Vercel AI SDK 处理多步骤工具执行，让大模型能够与已配置的 MCP 服务（例如 WhatsApp、GitHub、GSuite、Web Search）交互，以满足用户请求。

架构

本项目由以下组件构成：

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

设置

先决条件：

• Node.js（建议使用 LTS 版本）
• npm 或 yarn
• uv（Python 包管理器）
• Docker（用于 GitHub MCP 服务）
• 大模型 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. 配置环境变量：
   • 在 mcp-agent-app/ 中创建 .env.local。
   • 添加 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 启动它们）。
  • 注意： 当前实现会通过 StdioMCPTransport 按需启动 MCP 服务。通常无需手动启动，除非要调试特定服务。如果某个服务需要 WhatsApp Go bridge 等先决条件，请确保它们正在运行。
• 启动 Next.js 应用：

  cd mcp-agent-app
  npm run dev
  # or yarn dev
  

• 打开 http://localhost:3000。

用法

• 从侧边栏下拉菜单中选择所需的大模型提供商和模型。
• 使用聊天界面进行交互。
• Agent 将使用所选的大模型，并在适当时尝试使用已配置的 MCP 工具（Anthropic 除外，目前已禁用工具）。
• 使用“Save Chat”按钮保存对话。可从历史记录列表中加载之前的聊天。

示例提示词：

• Who are you?
• Search the web for the latest AI news.（使用 ddg-search）
• 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/
• 执行： 通过 uv run 运行 Python 脚本。需要单独运行 Go bridge。
• 配置： WHATSAPP_MCP_SCRIPT_DIR

GitHub MCP 服务

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

GSuite MCP 服务

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

DuckDuckGo 搜索 MCP 服务

• 来源： duckduckgo-mcp-server/
• 执行： 通过 uv run 运行 Python 模块。
• 配置： 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 密钥和令牌。

许可证

本项目依据 MIT 开源许可证的条款授权。完整条款请参阅 MIT。