主要项目：软件开发中上下文感知AI代理的统一MCP框架
该项目实施了一个全栈AI Agent系统，其灵感来自 模型上下文协议（MCP）它提供了一个统一的架构框架，其中AI编排器可以解释自然语言指令，识别要执行的适当工具（文件系统、浏览器、GitHub），安全调用该工具，并将结构化结果返回给前端聊天界面。该项目通过现代客户端-服务器架构展示了上下文感知AI代理的实际应用。
项目概述
架构： 该系统遵循客户端-服务器模型，由以下部分组成：
- A. React前端 负责用户交互、请求提交、状态显示和工具调用跟踪的可视化。
- A. FastAPI后端 充当AI编排器，负责路由请求、确定工具使用、执行操作和生成自然语言响应。
AI引擎： 后端使用 谷歌双子座 通过 google-generativeai 用于快速解释、意图分析、工具路由和摘要的SDK。
目标： 构建一个可扩展的代理框架，能够处理以开发人员为中心的任务，如文件操作、web研究和存储库检查，同时保持安全性、透明度和模块化。
______________________________________________________________________
技术栈
前端
- 框架： React 19与Vite结合，实现快速开发和构建性能
- 造型： 使用Inter字体系列自定义CSS
- 图标： Lucide反应
- 网络： REST API通信通过
fetch
后端
- 框架： 快速API
- 服务器运行程序： 乌维科恩
- AI集成： 谷歌生成人工智能SDK
- 浏览器自动化： 剧作家（异步）
- GitHub集成： PyGithub
- 安全： 文件系统沙盒限制对预定义目录的访问
______________________________________________________________________
项目结构
major-project/
├── backend/
│ ├── mcp_host_server.py # Main FastAPI application; AI Orchestrator logic
│ ├── mcp_core.py # Base interfaces for tools and tool execution
│ ├── filesystem_server.py # Restricted file operations inside a sandbox
│ ├── browser_server.py # Live web search and page extraction using Playwright
│ ├── github_server.py # GitHub repository access and file inspection
│ ├── mcp_sandbox/ # Secure directory for all file operations
│ └── requirements.txt # Python dependencies
│
├── frontend/
│ ├── src/
│ │ ├── App.jsx # Main chat and UI logic
│ │ └── App.css # Styling definitions
│ └── package.json # Node.js dependencies
└── README.md______________________________________________________________________
设置和安装
1.先决条件
- Python 3.8或更高版本
- Node.js和npm
- Google Gemini API密钥
- GitHub个人访问令牌（可选，GitHub工具需要）
2.后端设置
导航到后端目录并配置Python环境：
cd backend
python -m venv .venv激活环境：
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate安装依赖项：
pip install -r requirements.txt安装Playwright浏览器二进制文件：
playwright install chromium环境配置
创建一个 .env 文件内部 backend/ 目录：
GEMINI_API_KEY=your_google_gemini_api_key_here
GITHUB_PAT=your_github_personal_access_token_here3.前端设置
导航到前端目录并安装所需的软件包：
cd frontend
npm install______________________________________________________________________
运行应用程序
前端和后端必须分别启动。
启动后端
uvicorn mcp_host_server:app --reload后端将在以下位置运行：
http://127.0.0.1:8000启动前端
npm run dev前端界面将在以下网址提供：
http://localhost:5173______________________________________________________________________
特性和功能
1.智能刀具选择
后端编排器使用Gemini来解释自然语言请求，确定是否需要调用工具，并决定哪个工具最适合该任务。 示例：
- “总结此GitHub存储库。”→ GitHub工具
- “搜索最新的云安全新闻。”→ 浏览器工具
- “创建一个名为report.txt的文件，并在其中写入内容。”→ 文件系统工具
2.安全的文件系统操作
文件系统工具提供：
- 正在读取文件
- 写入文件
- 列出目录
所有操作严格限于 mcp_sandbox/ 目录，以防止未经授权的系统访问。这种方法与MCP强调能力有限的工具执行是一致的。
3.网页浏览和搜索
浏览器工具使用Playwright来：
- 执行谷歌风格的搜索查询
- 访问实时网站
- 从页面中提取可见文本内容
- 向编排器返回结构化响应
这使得实时研究、信息收集或总结网站内容等任务成为可能。
4.GitHub存储库集成
使用PyGithub，GitHub工具可以：
- 列出用户存储库
- 获取文件内容
- 检查存储库元数据
这支持开发人员工作流，如查看文档、检查代码或检索项目详细信息。
5.刀具轨迹可视化
前端显示：
- 工具已调用
- 后端返回的原始JSON有效负载
- 人工智能生成的解释
这种透明度有助于用户了解代理的内部操作方式。它还反映了MCP兼容系统的工具调用跟踪行为。
______________________________________________________________________
故障排除指南
后端没有响应
如果前端显示“后端状态：脱机”，请确保：
- FastAPI服务器正在运行
- 终端中没有运行时错误
- 环境变量配置正确
剧作家浏览器错误
如果浏览器工具失败：
- 核实一下
playwright install chromium被处决 - 确保您的系统支持Playwright所需的依赖关系
- 在Windows上，确认中的事件循环策略修复
mcp_host_server.py是活跃的
Windows上的环境问题
该项目包括一个特定于Windows的事件循环配置，以确保Playwright的异步操作在平台上正确运行。