🧠 Cortex MCP编排器
皮质 是基于 模型上下文协议（MCP）它采用了一种分体式架构设计，其中中央“大脑”（编排器）通过标准输入/输出（stdio）与本地“工具服务器”通信，允许安全、模块化和可扩展的工具使用。
它具有高级功能， ChatGPT风格的用户界面 实时流媒体、可折叠的“思维链”推理日志和Markdown渲染。
______________________________________________________________________
✨ 主要特点
- ⚡ 模型上下文协议（MCP）： 使用标准化的服务器-客户端架构将LLM与工具解耦。
- 🤖 LangGraph编排： 使用ReAct（Reason+Act）代理循环来计划、执行和优化答案。
- 🧠 高级RAG： 内置“内存”使用 色度数据库 和 拥抱面部嵌入 (
all-MiniLM-L6-v2)从URL中摄取和调用信息。 - 🚀 实时流媒体： 从后端到React UI的完整令牌流式传输。
- 🛡️ 强大的Windows支持： 自定义
launcher.py要处理的架构stdio在Windows上正确使用管道和事件循环。 - 🎨 现代UI： 深色主题的React界面，带有“思想链”手风琴、打字指示器和自动滚动。
______________________________________________________________________
🏗️ 建筑
graph LR
A[React Frontend] |"Stream API"| B[FastAPI Orchestrator]
B |"Stdio Pipe (MCP)"| C[Launcher Script]
C |"Subprocess (Stderr Log)"| D[MCP Tool Server]
D |"Search/RAG"| E[External APIs & ChromaDB]______________________________________________________________________
🛠️ 技术栈
- 后端： Python、FastAPI、LangChain、LangGraph，
mcp（Python SDK）、ChromaDB。 - LLM提供者： 格罗克（火焰-3-70b）。
- 前端： React（Vite）、CSS模块（无顺风依赖）、Lucide图标、React Markdown。
- 可观察性： Langfuse（可选，用于追踪）。
______________________________________________________________________
🚀 入门指南
先决条件
- Python 3.10+
- Node.js和npm
- A. Groq API密钥 （拿一个 这里)
- A. SerpApi密钥 （适用于谷歌搜索）
1.后端设置
- 克隆仓库 并导航到后端文件夹：
cd backend- 创建虚拟环境：
python -m venv venv
# Windows
venv\Scripts\activate
# Mac/Linux
source venv/bin/activate- 安装依赖关系：
pip install fastapi uvicorn mcp langchain-groq langgraph langchain-community langchain-chroma langchain-huggingface sentence-transformers python-dotenv langfuse- 配置环境：
创建 .env 文件在 backend 文件夹：
GROQ_API_KEY=gsk_your_key_here
SERPAPI_API_KEY=your_serpapi_key
# Optional: Langfuse for tracing
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com2.前端设置
- 导航到前端文件夹：
cd ../frontend- 安装节点模块：
npm install
npm install lucide-react react-markdown remark-gfm- 配置环境：
创建 .env 文件在 frontend 根：
VITE_API_URL=http://localhost:8002/api/chat______________________________________________________________________
🏃♂️ 用法
步骤1：启动后端（编排器）
编排器将自动管理工具服务器进程。
# In the backend/ folder (with venv activated)
python orchestrator.py*您应该看到： Uvicorn running on http://0.0.0.0:8002*
步骤2：启动前端
# In the frontend/ folder
npm run dev*打开浏览器 http://localhost:5173*
______________________________________________________________________
📂 项目结构
/project-root
├── /backend
│ ├── orchestrator.py # Main API & Agent Logic
│ ├── launcher.py # Windows Pipe Handler (CRITICAL)
│ ├── server.py # MCP Tool Server (Weather, RAG, Search)
│ ├── .env # API Keys
│ └── chroma_db_mcp/ # Vector Database Storage
│
├── /frontend
│ ├── src/
│ │ ├── ChatInterface.jsx # Main Chat Component
│ │ ├── ChatInterface.css # Styles & Animations
│ │ ├── App.jsx # App Entry
│ │ └── main.jsx # React Root (Strict Mode disabled)
│ ├── .env # Frontend Config
│ └── package.json
│
└── README.md______________________________________________________________________
🐛 故障排除
1. CRITICAL ERROR: Orchestrator Error: unhandled errors in a TaskGroup
- 原因： MCP服务器在启动时崩溃，通常是由于缺少库或API密钥。
- 修复： 检查
backend/server_debug.log由生成的文件launcher.py它将显示确切的误差（例如。，ModuleNotFoundError).
2.“双文本”提示（例如，“天气是……”）
- 原因： React严格模式在开发中运行两次效果。
- 修复： 确保
main.jsx做 不 有 `包装`.
3.连接关闭错误
- 原因：
print()声明server.py破坏JSON流。 - 修复： 使用
launcher.py脚本（已集成），它将所有意外输出重定向到stderr/log文件。
______________________________________________________________________
🧩 示例提示尝试
- 抹布： *“摄入 https://example.com/article学习后，告诉我主要的总结。"*
- 复杂逻辑： *“找到微软现任首席执行官的出生城市，看看那里的天气，告诉我一个关于那个城市的有趣事实。”*
- 推理： *“我有一个Python递归错误。解释为什么会发生，并编写代码来修复它。”*
______________________________________________________________________
📜 许可证
根据MIT许可证分发。看 LICENSE 了解更多信息。
📸 界面预览
The Cortex Agent handling a complex multi-step request.
🧠 思维与推理链
Real-time Tool Logs
Markdown Rendering