AI导哈

智能文档问答系统

一个结合React前端和Python FastAPI后端的全栈Web应用，通过MCP-Agent实现智能文档检索与问答功能。

  • by bismafarrukh
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 bismafarrukh/Agent-via-MCP

使用说明

MCP大学聊天机器人

一个全栈web应用程序，结合了 React前端 带着一个 Python FastAPI后端 由MCP Agent提供支持，用于智能文档检索和应答。

项目结构

mcp/
├── backend/          # Python FastAPI server (port 8000)
│   ├── main.py       # MCP-Agent application & LLaMA 3 LLM integration
│   ├── server.py     # FastAPI app with /ask endpoint
│   ├── data/         # PDF files for document retrieval
│   ├── logs/         # Application logs
│   ├── pyproject.toml # Python dependencies
│   └── mcp_agent.secrets.yaml # API keys (create this)
│
└── frontend/         # React + Vite frontend (port 3000)
    ├── src/
    │   ├── pages/    # Home, Chat, About pages
    │   ├── components/ # Reusable React components
    │   └── services/ # API client
    ├── package.json  # Node.js dependencies
    └── vite.config.js # Vite build config

先决条件

  • python 3.12+ (下载)
  • Node.js 18+和npm/纱线(下载)
  • LLM提供商的API密钥（Groq、OpenAI或Anthropic）

后端设置

1.导航到后端目录

cd backend

2.创建虚拟环境

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1

# Windows (CMD)
python -m venv .venv
.venv\Scripts\activate

# macOS/Linux
python -m venv .venv
source .venv/bin/activate

3.升级pip并安装依赖项

python -m pip install --upgrade pip
python -m pip install -e .

如果上述方法失败，手动安装软件包：

python -m pip install "mcp-agent[llama3,openai]" groq uvicorn[standard] PyPDF2

4.设置API密钥

创建或编辑 mcp_agent.secrets.yaml 在 backend/ 文件夹：

# Using Groq (LLaMA 3)
groq:
  api_key: "your-groq-api-key-here"

# OR using OpenAI
openai:
  api_key: "your-openai-api-key-here"

# OR using Anthropic
anthropic:
  api_key: "your-anthropic-api-key-here"

或者，设置环境变量：

# Windows (PowerShell)
$env:GROQ_API_KEY="your-groq-api-key"

# Windows (CMD)
set GROQ_API_KEY=your-groq-api-key

# macOS/Linux
export GROQ_API_KEY="your-groq-api-key"

5.添加PDF文档

将您的PDF文档放在 backend/data/ 文件夹。更新 pdf_path 在 main.py 如果需要：

pdf_path = "data/uetProspectus.pdf"  # or your filename

6.运行后端服务器

python -m uvicorn server:app_api --reload --host 127.0.0.1 --port 8000

预期产量：

INFO:     Will watch for changes in these directories: ['C:\mcp\backend']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

7.验证后端

  • FastAPI文档： http://127.0.0.1:8000/docs
  • 测试终点：
    curl -X POST http://127.0.0.1:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"What programs does the university offer?"}'

前端设置

1.导航到前端目录（在新终端中）

cd frontend

2.安装节点依赖关系

npm install
# or
yarn install

3.配置API端点（如果需要）

编辑 frontend/src/services/api.js 并确保后端URL正确：

const API_BASE = "http://127.0.0.1:8000";

4.运行开发服务器

npm run dev
# or
yarn dev

预期产量：

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:3000/

5.在浏览器中打开

导航至 http://localhost:3000/ 开始使用聊天机器人！

同时运行前端和后端

终端1：启动后端

cd backend
.venv\Scripts\activate          # Windows
# OR
source .venv/bin/activate       # macOS/Linux

python -m uvicorn server:app_api --reload --host 127.0.0.1 --port 8000

终端2：启动前端

cd frontend
npm run dev

预期行为

  1. 后端正在运行http://127.0.0.1:8000
  2. 前端正在运行http://localhost:3000
  3. 前端通过以下方式与后端通信 /ask 端点
  4. 用户类型问题→ 前端发送到后端→ LLaMA 3处理PDF→ 显示响应

API终点

POST/ask

请求：

{
  "question": "What academic programs does the university offer?"
}

答复：

{
  "answer": "The university offers the following programs: ..."
}

文件描述

后端

文件 目的
main.py MCP代理设置、PDF提取、LLaMA 3集成
server.py FastAPI应用程序 /ask 端点和CORS
pyproject.toml Python依赖项（mcp代理、groq、uvicorn等）
mcp_agent.config.yaml MCP代理配置（代理、服务器）
mcp_agent.secrets.yaml API密钥（创建此密钥，不要提交！）

前端

文件 目的
src/pages/Chat.jsx 主聊天界面
src/pages/Home.jsx 登录页面
src/pages/About.jsx 关于页面
src/services/api.js 用于后端通信的API客户端
src/components/ChatWindow.jsx 聊天信息显示
src/components/MessageBubble.jsx 个性化消息样式
package.json Node.js依赖项（React、Vite、Tailwind等）
vite.config.js Vite bundler配置

故障排除

后端问题

“ModuleNotFoundError:没有名为'mcp_agent'的模块”

  • 确保虚拟环境已激活
  • 跑 python -m pip install -e . 或手动安装

“没有这样的文件或目录：data/uetProspectus.pdf”

  • 将PDF文件添加到 backend/data/ 文件夹
  • 更新 pdf_path 变量in main.py

来自前端的CORS错误

  • 验证中的后端CORS设置 server.py 匹配前端原点
  • 违约： allow_origins=["http://localhost:3000"]

找不到API密钥

  • 创建 mcp_agent.secrets.yaml 使用API密钥
  • 或设置环境变量(GROQ_API_KEY, OPENAI_API_KEY等等）

前端问题

“找不到模块'@/services/api'”

  • 检查中的路径别名 vite.config.js
  • 确保 frontend/src/services/api.js 存在

“从获取失败http://127.0.0.1:8000"

  • 验证后端是否在端口8000上运行
  • 检查防火墙/网络设置
  • 确保在中启用CORS server.py

开发流程

  1. 进行后端更改 → 通过启用自动重新加载 --reload 旗帜
  2. 进行前端更改 → 保存时Vite热重载
  3. 重启服务 如果依赖关系发生了变化

生产大楼

后端

# Create optimized production dependencies
pip freeze > requirements.txt

# Or use uv for faster installs
uv sync --frozen

前端

npm run build
# Output: dist/ folder (ready to deploy)

# Preview production build
npm run preview

部署

后端（云选项）

  • MCP代理云： uv run mcp-agent deploy hello_world
  • Vercel/铁路： 部署FastAPI应用程序
  • AWS/GCP/Azure： 带有Uvicorn的Docker容器

前端（云选项）

  • Vercel： vercel deploy
  • Netlify： 拖放 dist/ 文件夹
  • GitHub页面： 在vite.config.js中配置

关键技术

组件 技术栈
后端 Python 3.12+、FastAPI、MCP代理、Groq/OpenAI LLM
前端 React 18+，Vite，顺风CSS
PDF处理 PyPDF2
API通信 获取API，CORS

支持和资源

  • MCP代理文件： https://docs.mcp-agent.com/
  • FastAPI文档： https://fastapi.tiangolo.com/
  • React文档： https://react.dev/
  • Groq API： https://console.groq.com/
  • OpenAI API： https://platform.openai.com/

许可证

[您的许可证在这里]

最后更新时间： 2026年2月1日

相关 MCP