Cortex MCP Agent 2

🧠 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.后端设置

1. 克隆仓库 并导航到后端文件夹：

   cd backend

1. 创建虚拟环境：

   python -m venv venv
   # Windows
   venv\Scripts\activate
   # Mac/Linux
   source venv/bin/activate

1. 安装依赖关系：

   pip install fastapi uvicorn mcp langchain-groq langgraph langchain-community langchain-chroma langchain-huggingface sentence-transformers python-dotenv langfuse

1. 配置环境：

创建 .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.com

2.前端设置

1. 导航到前端文件夹：

   cd ../frontend

1. 安装节点模块：

   npm install
   npm install lucide-react react-markdown remark-gfm

1. 配置环境：

创建 .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