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 的異步操作在該平臺上正常運行。