Major Project

🚀 重大项目：软件开发中上下文感知AI代理的统一MCP框架

本项目受模型上下文协议（Model Context Protocol，MCP） 核心原则的启发，实现了一个全栈AI代理系统。它提供了一个统一的架构框架，在这个框架中，AI编排器可以解释自然语言指令，识别合适的执行工具（文件系统、浏览器、GitHub），安全地调用该工具，并将结构化结果返回给前端聊天界面。该项目通过现代的客户端 - 服务器架构展示了上下文感知AI代理的实际应用。

🚀 快速开始

本项目实现了一个基于MCP核心原则的全栈AI代理系统，通过客户端 - 服务器架构，让AI编排器能处理自然语言指令并调用工具，最后将结果返回给前端。以下为你介绍如何启动项目：

前置条件

• Python 3.8 或更高版本
• Node.js 和 npm
• Google Gemini API 密钥
• GitHub 个人访问令牌（可选，使用 GitHub 工具时需要）

后端设置

1. 进入后端目录并配置 Python 环境：

cd backend
python -m venv .venv

2. 激活环境：

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

3. 安装依赖：

pip install -r requirements.txt

4. 安装 Playwright 浏览器二进制文件：

playwright install chromium

5. 环境配置： 在 backend/ 目录下创建一个 .env 文件：

GEMINI_API_KEY=your_google_gemini_api_key_here
GITHUB_PAT=your_github_personal_access_token_here

前端设置

进入前端目录并安装所需包：

cd frontend
npm install

启动应用程序

前端和后端需要分别启动。

启动后端

uvicorn mcp_host_server:app --reload

后端将运行在：

http://127.0.0.1:8000

启动前端

npm run dev

前端界面将在以下地址可用：

http://localhost:5173

✨ 主要特性

1. 智能工具选择

后端编排器使用 Google Gemini 解释自然语言请求，判断是否需要调用工具，并决定最适合该任务的工具。例如：

• “总结这个 GitHub 仓库。” → 调用 GitHub 工具
• “搜索最新的云安全新闻。” → 调用浏览器工具
• “创建一个名为 report.txt 的文件并写入内容。” → 调用文件系统工具

2. 安全的文件系统操作

文件系统工具提供以下功能：

• 读取文件
• 写入文件
• 列出目录

所有操作都严格限制在 mcp_sandbox/ 目录内，以防止未经授权的系统访问，这符合 MCP 对有限能力工具执行的强调。

3. 网页浏览和搜索

浏览器工具使用 Playwright 执行以下操作：

• 执行类似 Google 的搜索查询
• 访问实时网站
• 从页面提取可见文本内容
• 向编排器返回结构化响应

这使得实时研究、信息收集或总结网站内容等任务成为可能。

4. GitHub 仓库集成

使用 PyGithub，GitHub 工具可以：

• 列出用户仓库
• 获取文件内容
• 检查仓库元数据

这支持开发人员的工作流程，如查看文档、检查代码或检索项目详细信息。

5. 工具调用跟踪可视化

前端显示以下信息：

• 调用的工具
• 后端返回的原始 JSON 有效负载
• AI 生成的解释

这种透明度有助于用户了解代理的内部操作方式，也反映了符合 MCP 系统的工具调用跟踪行为。

📦 安装指南

前端

• 框架：使用 React 19 和 Vite 实现快速开发和构建性能
• 样式：使用 Inter 字体家族的自定义 CSS
• 图标：Lucide React
• 网络通信：通过 fetch 进行 REST API 通信

后端

• 框架：FastAPI
• 服务器运行器：Uvicorn
• AI 集成：使用 google-generativeai SDK 集成 Google Gemini
• 浏览器自动化：Playwright（异步）
• GitHub 集成：PyGithub
• 安全：文件系统沙箱，限制对预定义目录的访问

📚 详细文档

项目概述

架构

系统遵循客户端 - 服务器模型，包括：

1. React 前端：负责用户交互、请求提交、状态显示以及工具调用跟踪的可视化。
2. FastAPI 后端：作为 AI 编排器，负责路由请求、确定工具使用、执行操作并生成自然语言响应。

AI 引擎

后端通过 google-generativeai SDK 使用 Google Gemini 进行提示解释、意图分析、工具路由和总结。

目标

构建一个可扩展的代理框架，能够处理以开发人员为中心的任务，如文件操作、网络研究和仓库检查，同时保持安全性、透明度和模块化。

项目结构

major-project/
├── backend/
│   ├── mcp_host_server.py       # 主要的 FastAPI 应用程序；AI 编排器逻辑
│   ├── mcp_core.py              # 工具和工具执行的基本接口
│   ├── filesystem_server.py     # 沙箱内的受限文件操作
│   ├── browser_server.py        # 使用 Playwright 进行实时网络搜索和页面提取
│   ├── github_server.py         # GitHub 仓库访问和文件检查
│   ├── mcp_sandbox/             # 所有文件操作的安全目录
│   └── requirements.txt         # Python 依赖项
│
├── frontend/
│   ├── src/
│   │   ├── App.jsx              # 主要的聊天和 UI 逻辑
│   │   └── App.css              # 样式定义
│   └── package.json             # Node.js 依赖项
└── README.md

🚧 故障排除指南

后端无响应

如果前端显示“Backend Status: Offline”，请确保：

• FastAPI 服务器正在运行
• 终端中没有运行时错误
• 环境变量配置正确

Playwright 浏览器错误

如果浏览器工具失败：

• 验证是否执行了 playwright install chromium
• 确保你的系统支持 Playwright 所需的依赖项
• 在 Windows 上，确认 mcp_host_server.py 中的事件循环策略修复已激活

Windows 环境问题

项目包含特定于 Windows 的事件循环配置，以确保 Playwright 的异步操作在该平台上正常运行。