LangGraph——MCP支持的学生分析代理
一个生产就绪的LangGraph风格的代理，通过最小的MCP（模型连接器代理）服务器安全地路由用户请求，以分析学生的表现数据。专为安全性、可观察性和优雅的故障处理而设计。
______________________________________________________________________
目录
______________________________________________________________________
概述
该系统帮助教育工作者分析学生表现数据，以识别有风险的学生，跟踪成绩趋势，并通过人工智能助手界面获得见解。
为什么选择MCP？ 模型连接器代理模式在人工智能推理和数据访问之间建立了严格的界限。这通过确保LLM只对意图进行分类，而所有数据操作都通过确定性、可审计、只读的通道，防止了“LLM即系统”的反模式。
______________________________________________________________________
特性
- 人工智能驱动的分析 --关于具有LLM意图解析和确定性回退的学生的自然语言查询
- 性能分析 --学生总结、趋势检测、风险评估和班级排名
- 实时仪表板 --带有KPI、图表和排行榜的React+TypeScript接口
- 综合可观察性 --Prometheus度量、分布式跟踪和LLM成本跟踪
- 安全第一设计 --只读MCP服务器、投影白名单、输入验证
- 故障弱化 --在没有LLM（启发式回退）和MongoDB（模拟数据）的情况下工作
______________________________________________________________________
快速开始
先决条件
- Python 3.10+
- Node.js 18+
- MongoDB（本地或Atlas）-- *或者使用Docker进行一次命令设置*
单线安装
curl -sSL https://raw.githubusercontent.com/dicksarp09/mcp-agent-dashboard/main/install.sh | bash这将：
- 克隆存储库
- 设置Docker容器（MongoDB、后端、前端）
- 配置环境变量
- 启动所有服务
访问仪表板： http://localhost:3000
手动设置
1.后端设置
# Create virtual environment
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Mac/Linux
# Install dependencies
pip install -r requirements.txt
# Create .env file
cat > .env << EOL
MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/
MONGO_DB=student-db
MONGO_COLLECTION=student_performance.records
GROQ_API_KEY=your_groq_api_key_here
EOL
# Start the MCP server
python start_server.py服务器在上运行 http://127.0.0.1:8000
2.前端设置
cd web
npm install
npm run dev仪表板运行 http://localhost:3000
3.访问应用程序
打开 http://localhost:3000 在您的浏览器中。
______________________________________________________________________
建筑
┌─────────────────┐
│ React Client │
│ (Dashboard) │
└────────┬────────┘
│ HTTP/REST
▼
┌─────────────────────────────────────┐
│ LangGraph Agent Layer │
│ ┌──────────────────────────────┐ │
│ │ Intent Classification Node │ │ ← Rule-based + LLM fallback
│ └──────────┬───────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ Input Validation Node │ │ ← Security checkpoint
│ └──────────┬───────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ MCP Tool Invocation Node │ │ ← Database interaction
│ └──────────┬───────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ Performance Analysis Node │ │ ← Deterministic computation
│ └──────────┬───────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ Response Formatting Node │ │
│ └──────────────────────────────┘ │
└─────────────────┬───────────────────┘
│ MCP Protocol
▼
┌─────────────────┐
│ MCP Server │
│ ┌───────────┐ │
│ │ Cache │ │ ← In-memory (1,295x speedup)
│ └─────┬─────┘ │
│ ▼ │
│ ┌───────────┐ │
│ │Projection │ │ ← Security whitelist
│ │Whitelist │ │
│ └─────┬─────┘ │
└────────┼─────────┘
│ Read-only
▼
┌─────────────────┐
│ MongoDB Atlas │
│ (Students DB) │
└─────────────────┘关键组件
- 代理 (
src/agent.py)--使用可观察性检测来编排LangGraph节点 - MCP服务器 (
src/mcp_server.py)--具有安全白名单的只读MongoDB访问 - 性能分析器 (
src/performance_analyzer.py)--确定性分析逻辑 - 可观测性 (
src/observability.py)--度量、跟踪和成本跟踪
系统设计
有关涵盖架构、安全性、弹性和可观察性的55个问题的详细系统设计评估，请参阅 SYSTEM_DESIGN.md.
______________________________________________________________________
API概述
健康与信息
GET /-API信息和状态GET /health--健康检查GET /docs--Swagger用户界面文档
学生查询
POST /query--按ID查询单个学生POST /analyze/summary--学生表现总结POST /analyze/trend--品位趋势分析POST /analyze/risk--风险评估POST /class_analysis--班级级别分析
查询示例
curl -X POST http://localhost:8000/query \
-H "Content-Type: application/json" \
-d '{"student_id": "689cef602490264c7f2dd235", "fields": ["name", "G1", "G2", "G3"]}'有关API的完整文档，请参阅 API_README.md.
______________________________________________________________________
可观测性
该系统包括覆盖80%生产需求的综合可观测性。
可用指标
- 请求度量 --按节点/查询类型列出的请求总数和失败次数
- 延迟度量 --每个节点的执行时间、MCP调用、LLM调用
- 缓存指标 --命中率/未命中率（观察到高达1295倍的加速）
- 成本跟踪 --LLM代币使用情况和每个模型的估计美元成本
分布式追踪
每个请求都通过具有相关ID的所有5个代理节点进行跟踪：
agent.intent--意图解析agent.validation--请求验证agent.mcp_call--MCP服务器调用agent.analysis--性能分析agent.response--响应综合
访问指标
from src.observability import get_metrics_summary
summary = get_metrics_summary()
print(f"Cache hits: {summary['cache_hits']}")
print(f"Total LLM cost: ${sum(summary['llm_cost_usd'].values())}")Prometheus指标端点： GET /metrics
有关详细的可观察性文档，请参阅 可维护性\_ SUMMARY.md.
______________________________________________________________________
发展
项目结构
mcp-agent-dashboard/
├── src/
│ ├── main.py # FastAPI application
│ ├── agent.py # LangGraph agent
│ ├── mcp_server.py # MCP server
│ ├── performance_analyzer.py # Analytics logic
│ └── observability.py # Metrics & tracing
├── web/ # React frontend
├── SYSTEM_DESIGN.md # Detailed system design
├── DEPLOYMENT.md # Deployment guide
└── README.md # This file运行测试
# Backend tests
pytest
# Frontend tests
cd web
npm test代码质量
# Type checking (frontend)
cd web
npx tsc --noEmit
# Linting (frontend)
npm run lint环境变量
创建一个 .env 项目根目录中的文件：
# MongoDB (Required for real data)
MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/
MONGO_DB=student-db
MONGO_COLLECTION=student_performance.records
# Groq API (Optional - for LLM intent parsing)
GROQ_API_KEY=your_groq_api_key_here
# Without MongoDB credentials, the server runs with mock data______________________________________________________________________
路线图
当前限制
- 风险阈值是硬编码的（G3\<10）
- 不支持多租户
- 没有可通过UI配置的策略
- 生产部署需要手动设置
计划的功能
- \[\]通过管理界面可配置风险阈值
- \[\]具有数据隔离功能的多租户支持
- \[\]高级分析（预测建模）
- \[\]移动响应式仪表板改进
- \[\]Kubernetes部署模板
- \[\]用于快速更改的A/B测试框架
- \[\]异常查询模式的异常检测
- \[\]符合GDPR的数据删除工作流程
______________________________________________________________________
安全与最佳实践
- ✅ 投影白名单 --MCP只允许特定字段
- ✅ 只读访问 --通过MCP无写入操作
- ✅ 输入验证 --所有输入上的Pydantic验证器
- ✅ 指标中没有原始数据 --可观察性仅使用低基数标签
- ✅ 跟踪上下文 --分布式跟踪，不暴露敏感数据
- ✅ 成本跟踪 -静态定价，无外部API调用
______________________________________________________________________
故障排除
后端无法启动
- 检查端口8000是否空闲：
netstat -ano | findstr :8000 - 在中验证MongoDB凭据
.env - 检查日志中的连接错误
前端无法连接
- 确保后端在端口8000上运行
- 检查浏览器控制台是否存在CORS错误
- 验证
vite.config.ts代理设置
LLM不工作
- 检查
GROQ_API_KEY在.env - 如果LLM失败，系统将退回启发式解析
- 检查日志中是否有“LLM解析失败”消息
Docker问题
看 部署.md 了解Docker的详细故障排除。
______________________________________________________________________
支持
对于问题和疑问：
- 检查 API_README.md 有关后端详细信息
- 检查 可维护性\_ SUMMARY.md 可观察性文档
- 检查 SYSTEM_DESIGN.md 了解架构细节
- 检查 部署.md 用于部署指南
- 在GitHub上打开一个问题
______________________________________________________________________
贡献
- 克隆该仓库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
______________________________________________________________________
内置于 FastAPI、React、LangGraph和MongoDB