MCP Agent

一个基于网络的对话式代理，由 Google Gemini 提供支持，可以通过模型上下文协议 (MCP) 与各种外部服务进行交互。

概述

本项目提供了一个聊天界面，用户可以在其中与 Google Gemini 进行对话。 关键特性是代理能够理解需要与外部工具（MCP 服务器）交互的请求并执行这些操作。 目前，它与官方 GitHub MCP 服务器集成，以执行诸如获取 issue 详细信息之类的操作。

架构

该项目由两个主要部分组成：

1. mcp-agent-app/: 一个 Next.js 应用程序，提供：
   • 前端： 一个基于 React 的聊天界面 (http://localhost:3000)。
   • 后端： 一个 API 路由 (/api/chat)，它：
     • 管理与前端的对话流程。
     • 与 Google Gemini API 通信。
     • 根据 Gemini 的响应编排对 MCP 服务器的调用。
2. MCP 服务器集成（示例：GitHub）：
   • 当请求与 GitHub 相关的操作时，Next.js 后端会在 Docker 容器中动态生成官方 GitHub MCP 服务器 (ghcr.io/github/github-mcp-server)。
   • 通信通过标准输入/输出 (stdio) 进行，使用模型上下文协议定义的 JSON-RPC 格式。
   • GitHub MCP 服务器的源代码包含在 github-mcp-server/ 目录中以供参考，但通过顶层 .gitignore 被 Git 忽略。

设置

先决条件：

• Node.js (推荐 LTS 版本)
• npm 或 yarn
• Docker
• Google Gemini API 密钥： 可从 Google AI Studio 获取。
• GitHub 个人访问令牌 (PAT)： 在此处创建一个，并具有适当的范围（例如，repo、read:user），以便代理执行您想要的操作。

安装和配置：

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
     GOOGLE_API_KEY=YOUR_GEMINI_API_KEY
     GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT
     

   • 将 YOUR_GEMINI_API_KEY 和 YOUR_GITHUB_PAT 替换为您的实际凭据。

运行应用程序：

1. 确保 Docker Desktop（或 Docker 守护程序）正在运行。
2. 导航到 Next.js 应用程序目录：

   cd mcp-agent-app
   

3. 启动开发服务器：

   npm run dev
   # or yarn dev
   

4. 打开您的浏览器并转到 http://localhost:3000。

用法

• 像与 Gemini 一样与聊天界面进行交互。
• 要触发 GitHub 操作（目前已实现 get_issue），请制定一个提示，其中包含后端查找的特定操作模式。 示例： Please get issue number 1 from the repository octocat/Spoon-Knife using the GitHub MCP server action: [[ACTION:GITHUB_GET_ISSUE owner=octocat repo=Spoon-Knife issue_number=1]]
• 代理应回复直接的 Gemini 回复或执行的 GitHub 操作的结果（或错误）。

添加新的 MCP 服务器

当前的架构使用 Docker 和 stdio/MCP 用于 GitHub 服务器。 要添加对新 MCP 服务器的支持：

1. 识别服务器详细信息： 确定新服务器的运行方式（例如，Docker 镜像、可执行文件）以及它的通信方式（例如，stdio/MCP、HTTP API）。
2. 后端修改 (mcp-agent-app/src/app/api/chat/route.ts):
   • 操作检测： 添加逻辑以检测 Gemini 响应中的新操作模式（例如，[[ACTION:NEW_SERVICE_ACTION param1=...]]）。 使用正则表达式提取参数。
   • 执行逻辑：
     • 如果它像 GitHub 服务器一样使用 Docker/stdio：调整现有的 spawn 逻辑以使用新服务器的 Docker 镜像，并根据其 MCP 定义构造适当的 JSON-RPC 请求。
     • 如果它公开了一个 HTTP API：使用 fetch 调用服务器的端点，并提供必要的参数和身份验证。
     • 如果它是不同类型的可执行文件：根据需要使用 spawn 或其他 child_process 方法。
   • 响应处理： 解析来自新服务器的响应，并为前端聊天适当地格式化它。
   • 错误处理： 为新的集成路径实现强大的错误处理。
3. 环境变量： 将任何新的必需 API 密钥或配置添加到 mcp-agent-app/.env.local。
4. 文档： 更新此 README 以包含新服务器及其用法。

当前 MCP 服务器

• GitHub MCP 服务器：
  • 来源： github-mcp-server/（克隆，供参考）
  • 执行： 通过 Docker 镜像 ghcr.io/github/github-mcp-server
  • 通信： Stdio / MCP (JSON-RPC)
  • 配置： 需要 .env.local 中的 GITHUB_PERSONAL_ACCESS_TOKEN。