🧠 Cortex MCP Orchestrator

Cortex is an advanced AI Agent Orchestrator built on the Model Context Protocol (MCP). It uses a split-architecture design where a central "Brain" (Orchestrator) communicates with a local "Tool Server" via standard input/output (stdio), allowing for secure, modular, and extensible tool usage.

It features a premium, ChatGPT-style UI with real-time streaming, collapsible "Chain of Thought" reasoning logs, and Markdown rendering.

---

✨ Key Features

• ⚡ Model Context Protocol (MCP): Decouples the LLM from the tools using a standardized server-client architecture.
• 🤖 LangGraph Orchestration: Uses a ReAct (Reason + Act) agent loop to plan, execute, and refine answers.
• 🧠 Advanced RAG: Built-in "Memory" using ChromaDB and HuggingFace Embeddings (all-MiniLM-L6-v2) to ingest and recall information from URLs.
• 🚀 Real-Time Streaming: Full token-by-token streaming from the backend to the React UI.
• 🛡️ Robust Windows Support: Custom launcher.py architecture to handle stdio pipes and event loops correctly on Windows.
• 🎨 Modern UI: Dark-themed React interface with "Chain of Thought" accordions, typing indicators, and auto-scrolling.

---

🏗️ Architecture

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]

Loading

---

🛠️ Tech Stack

• Backend: Python, FastAPI, LangChain, LangGraph, mcp (Python SDK), ChromaDB.
• LLM Provider: Groq (Llama-3-70b).
• Frontend: React (Vite), CSS Modules (No Tailwind dependency), Lucide Icons, React Markdown.
• Observability: Langfuse (Optional, for tracing).

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• Node.js & npm
• A Groq API Key (Get one here)
• A SerpApi Key (For Google Search)

1. Backend Setup

1. Clone the repository and navigate to the backend folder:

   cd backend

2. Create a Virtual Environment:

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

3. Install Dependencies:

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

4. Configure Environment: Create a .env file in the backend folder:

   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. Frontend Setup

1. Navigate to the frontend folder:

   cd ../frontend

2. Install Node Modules:

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

3. Configure Environment: Create a .env file in the frontend root:

   VITE_API_URL=http://localhost:8002/api/chat

---

🏃‍♂️ Usage

Step 1: Start the Backend (Orchestrator)

The Orchestrator will automatically manage the Tool Server process.

# In the backend/ folder (with venv activated)
python orchestrator.py

You should see: Uvicorn running on http://0.0.0.0:8002

Step 2: Start the Frontend

# In the frontend/ folder
npm run dev

Open your browser to http://localhost:5173

---

📂 Project Structure

/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

---

🐛 Troubleshooting

1. CRITICAL ERROR: Orchestrator Error: unhandled errors in a TaskGroup

• Cause: The MCP Server crashed on startup, usually due to a missing library or API key.
• Fix: Check the backend/server_debug.log file generated by the launcher.py. It will show the exact error (e.g., ModuleNotFoundError).

2. "Double Text" Glitch (e.g., "The weather isThe weather is...")

• Cause: React Strict Mode runs effects twice in development.
• Fix: Ensure main.jsx does not have <StrictMode> wrapping the <App />.

3. Connection Closed Error

• Cause: print() statements in server.py corrupting the JSON stream.
• Fix: Use the launcher.py script (already integrated), which redirects all unexpected output to stderr/log files.

---

🧩 Example Prompts to Try

• RAG: "Ingest https://example.com/article. After learning it, tell me the main summary."
• Complex Logic: "Find the birth city of the current CEO of Microsoft, check the weather there, and tell me a fun fact about that city."
• Reasoning: "I have a Python recursion error. Explain why it happens and write code to fix it."

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

📸 Interface Preview

The Cortex Agent handling a complex multi-step request.

🧠 Chain of Thought & Reasoning

Real-time Tool Logs

Markdown Rendering