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）

______________________________________________________________________

architecture diagram Sequence diagram

后端设置

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: ..."
}

______________________________________________________________________

文件描述

后端

前端

______________________________________________________________________

故障排除

后端问题

“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中配置

______________________________________________________________________

关键技术

______________________________________________________________________

支持和资源

• 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日