# 🚀 Multi-Agent Research System MCP Server

> **Advanced Multi-Agent Architecture for VS Code Copilot Integration**
>
> A next-generation Model Context Protocol (MCP) server that demonstrates how to build powerful multi-agent systems with sophisticated tooling, breaking away from traditional specialized-tool-only MCP implementations.

---

## 📋 Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Key Features](#key-features)
- [Technology Stack](#technology-stack)
- [Project Structure](#project-structure)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Workflow Pipeline](#workflow-pipeline)
- [VS Code Integration](#vs-code-integration)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Development](#development)

---

## 🎯 Overview

This project represents a **paradigm shift in MCP server design**. While traditional MCP servers focus on exposing simple, specialized tools, this implementation leverages **multi-agent orchestration** to create a sophisticated research system that can be seamlessly integrated into VS Code Copilot.

The system combines three specialized AI agents with powerful internal tools to perform comprehensive research tasks—all exposed through simple, intuitive MCP tools.

### Why This Matters

- **Traditional MCP**: Single-purpose tools exposed directly to clients
- **This Approach**: Multi-agent coordination, tool orchestration, and intelligent workflow management wrapped in a clean interface
- **Result**: More powerful, context-aware, and reliable results delivered through familiar tools

---

## 🏗️ Architecture

### System Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    VS Code Copilot                          │
└────────────────────────┬────────────────────────────────────┘
                         │
                    MCP Protocol (STDIO)
                         │
┌────────────────────────▼────────────────────────────────────┐
│              FastMCP Server (Entry Point)                   │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Exposed Tools:                                        │ │
│  │  • run_research_graph(query, num_sources)             │ │
│  │  • workflow_info()                                     │ │
│  └────────────────────────────────────────────────────────┘ │
└─────┬──────────────────────────────────────────────────────┘
      │
      │ Invokes
      │
┌─────▼────────────────────────────────────────────────────────┐
│         LangGraph Workflow (State Management)                │
│                                                              │
│  START → Research Agent → Validator Agent → Final Output → END
│          Agent            Agent           Agent
└────┬─────────┬──────────────┬────────────────────────────────┘
     │         │              │
     ▼         ▼              ▼
  ┌──────────────────────────────────────────────────────────┐
  │       Internal Tools (Not Exposed to Client)            │
  │  ┌────────────────┐  ┌─────────────────────────────────┐│
  │  │  Web Tools     │  │  LLM Agents (Groq - 70B)        ││
  │  │  • web_search  │  │  • Research Analysis            ││
  │  │  • fetch_page  │  │  • Validation & Scoring         ││
  │  │  • search_news │  │  • Report Generation            ││
  │  └────────────────┘  └─────────────────────────────────┘│
  └──────────────────────────────────────────────────────────┘
```

### Agent Pipeline

```
1. RESEARCH AGENT
   ├─ Performs web searches using DuckDuckGo
   ├─ Fetches detailed content from URLs
   ├─ Performs LLM-based analysis
   ├─ Extracts facts and insights
   └─ Outputs: summary, key_facts, insights

2. VALIDATOR AGENT
   ├─ Evaluates research quality
   ├─ Scores reliability (0-100)
   ├─ Identifies issues and gaps
   ├─ Provides improvement recommendations
   └─ Outputs: validation_score, reliability, status

3. FINAL OUTPUT AGENT
   ├─ Synthesizes all agent outputs
   ├─ Generates professional markdown report
   ├─ Organizes findings hierarchically
   ├─ Includes sources and recommendations
   └─ Outputs: final_report (professional documentation)
```

---

## ✨ Key Features

### 🤖 Multi-Agent Orchestration
- **Three Specialized Agents**: Research, Validation, and Output generation
- **Sequential Workflow**: Each agent refines the previous agent's output
- **State Preservation**: TypedDict-based state management ensures data consistency

### 🔧 Advanced Tooling
- **Web Search**: DuckDuckGo integration for source discovery
- **Content Extraction**: Beautiful Soup-based webpage parsing
- **News Search**: Specialized news discovery capability
- **All Internal**: Tools not exposed to clients—only results are shared

### 🧠 Intelligent Analysis
- **LLM-Powered**: Groq's Llama 3.3 (70B) for accurate analysis
- **Temperature Control**: Optimized settings per agent (Research: 0.3, Validation: 0.2, Output: 0.4)
- **JSON Parsing**: Structured output with fallback mechanisms

### 📊 Quality Assurance
- **Validation Scoring**: 0-100 confidence scoring system
- **Reliability Assessment**: Multi-factor reliability ratings
- **Error Tracking**: Issue identification and recommendations

### 🔐 Secure Integration
- **Environment Variables**: API keys managed via `.env`
- **STDIO Transport**: Safe MCP communication channel
- **No Data Leakage**: Internal tools hidden from client

---

## 🛠️ Technology Stack

| Component | Technology | Purpose |
|-----------|-----------|---------|
| **Agent Framework** | LangGraph | Workflow orchestration & state management |
| **LLM Provider** | Groq (Llama 3.3 70B) | Advanced reasoning & analysis |
| **Language** | Python 3.10+ | Implementation language |
| **MCP Framework** | FastMCP | Server protocol & tool exposure |
| **HTTP Client** | HTTPX | Async web requests |
| **HTML Parser** | BeautifulSoup 4 | Content extraction |
| **Chat Models** | LangChain | LLM integration abstraction |

---

## 📂 Project Structure

```
AgentsCrossToolMCP/
├── server.py                      # FastMCP server & tool definitions
├── graph_workflow.py              # LangGraph workflow pipeline
├── state.py                       # Shared state TypedDict definition
├── requirements.txt               # Python dependencies
├── pyproject.toml                 # Project metadata
│
├── agents/                        # Multi-agent components
│   ├── __init__.py
│   ├── research_agent.py          # Source discovery & analysis
│   ├── validator_agent.py         # Quality validation & scoring
│   └── final_output_agent.py      # Report generation
│
└── tools/                         # Internal tool library
    ├── __init__.py
    ├── web_tools.py               # Web search, fetch, news search
    └── __pycache__/
```

---

## 📦 Installation

### Prerequisites
- Python 3.10 or higher
- Groq API key (get one at [https://console.groq.com](https://console.groq.com))
- VS Code with Copilot extension

### Setup Steps

1. **Clone or download the project**
   ```powershell
   cd d:\GENAI\AgentsCrossToolMCP
   ```

2. **Create virtual environment**
   ```powershell
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   ```

3. **Install dependencies**
   ```powershell
   pip install -r requirements.txt
   ```

4. **Configure environment variables**
   Create a `.env` file in the project root:
   ```env
   GROQ_API_KEY=your_groq_api_key_here
   ```

5. **Verify installation**
   ```powershell
   python server.py
   ```
   You should see the FastMCP banner and server startup messages.

---

## ⚙️ Configuration

### Environment Variables

```env
# Required
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional (uses defaults if not set)
GROQ_MODEL=llama-3.3-70b-versatile    # Model for all agents
RESEARCH_TEMPERATURE=0.3               # Research agent creativity
VALIDATOR_TEMPERATURE=0.2              # Validator strictness
OUTPUT_TEMPERATURE=0.4                 # Output composition creativity
```

### MCP Server Configuration

The MCP server is configured in VS Code through the settings:

```json
{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["d:\\GENAI\\AgentsCrossToolMCP\\server.py"],
      "disabled": false,
      "alwaysAllow": ["run_research_graph", "workflow_info"]
    }
  }
}
```

---

## 🚀 Usage

### Via VS Code Copilot

Once connected, you can use the system directly in Copilot:

**Example Prompt:**
```
@my-mcp-server Use run_research_graph to research "AI safety in Large Language Models" 
with 5 sources and provide a comprehensive analysis.
```

**Copilot will:**
1. Call `run_research_graph(query, 5)`
2. Display the multi-page research report
3. Cite sources and validation metrics

### Programmatic Usage

```python
from server import run_research_graph
import asyncio

async def main():
    result = await run_research_graph(
        query="Is Indian GDP growing? Current growth rate and challenges",
        num_sources=5
    )
    print(result)

asyncio.run(main())
```

### Command Line

```powershell
# Start the server
python server.py

# In another terminal, test via MCP client
# (Configure in VS Code settings)
```

---

## 🔄 Workflow Pipeline

### Step-by-Step Execution

#### 1️⃣ **Initialization**
- User provides query and source count
- System initializes ResearchState object
- Workflow begins

#### 2️⃣ **Research Agent Processing**
```
Input: query, num_sources
├─ web_search(query) → 5 search results
├─ fetch_webpage(url) for top 2 results → raw content
├─ LLM Analysis with tools
└─ Output: summary, key_facts, insights
```

#### 3️⃣ **Validation Agent Processing**
```
Input: research_summary, key_facts
├─ LLM Assessment of quality
├─ Scoring (0-100)
├─ Reliability rating
└─ Output: validation_score, status, issues
```

#### 4️⃣ **Final Output Agent Processing**
```
Input: all previous outputs + sources
├─ Combine all findings
├─ Format as markdown report
├─ Add structure & organization
└─ Output: final_report (professional document)
```

#### 5️⃣ **Return to Client**
- MCP server returns final_report
- Copilot displays in editor
- Sources and validation metrics included

---

## 🔌 VS Code Integration

### Setup Instructions

1. **Open VS Code Settings** (`Ctrl+,`)

2. **Go to MCP Servers section**

3. **Add configuration:**
   ```json
   "mcpServers": {
     "my-mcp-server": {
       "command": "python",
       "args": ["d:\\GENAI\\AgentsCrossToolMCP\\server.py"],
       "disabled": false
     }
   }
   ```

4. **Restart VS Code**

5. **Verify in Copilot Chat:**
   - Open Copilot Chat (`Ctrl+L`)
   - Type `@my-mcp-server`
   - Should see available tools

### Usage in Copilot

```
@my-mcp-server Can you research the latest developments in quantum computing
and provide a detailed analysis with key insights?
```

---

## 🔗 API Reference

### Tool: `run_research_graph`

**Purpose**: Execute comprehensive research workflow

**Parameters:**
```python
run_research_graph(
    query: str,              # Research topic/question
    num_sources: int = 5     # Number of sources to fetch
) -> str
```

**Returns:**
```
Professional markdown report containing:
- Executive Summary
- Key Findings
- Detailed Analysis
- Research Sources
- Validation Metrics
- Recommendations
```

**Example:**
```python
report = await run_research_graph(
    query="Climate change impact on agricultural productivity",
    num_sources=5
)
print(report)
```

---

### Tool: `workflow_info`

**Purpose**: Get information about the multi-agent system

**Parameters:** None

**Returns:**
```
String describing:
- Agent roles and responsibilities
- Available capabilities
- Tool information
```

**Example:**
```python
info = await workflow_info()
print(info)
```

---

## 📚 Examples

### Example 1: Economic Research

**Query:**
```
Query: India GDP growth rate 2024 2025 economic challenges obstacles
Sources: 5
```

**Output includes:**
- GDP growth statistics
- Economic challenges identified
- Market obstacles
- Expert recommendations
- Data reliability assessment

---

### Example 2: Technology Trends

**Query:**
```
Query: Latest developments in quantum computing and AI integration
Sources: 8
```

**Output includes:**
- Recent breakthroughs
- Technical insights
- Industry trends
- Research opportunities
- Cross-domain applications

---

## 🧑‍💻 Development

### Project Architecture Principles

1. **Separation of Concerns**
   - Agents focus on specific tasks
   - Tools handle data fetching
   - Server handles protocol translation

2. **State Immutability Pattern**
   - TypedDict ensures type safety
   - Operator.add for message accumulation
   - Clear state transitions

3. **Error Handling**
   - Graceful degradation for tool failures
   - LLM JSON parsing fallbacks
   - Comprehensive error messages

4. **Extensibility**
   - Easy to add new agents
   - Simple to integrate new tools
   - Flexible temperature/model parameters

### Adding New Agents

1. Create new agent class in `agents/`
2. Implement `async __call__(self, state)` method
3. Add to graph in `graph_workflow.py`
4. Update state.py if needed

### Adding New Tools

1. Create tool function in `tools/web_tools.py`
2. Decorate with `@tool`
3. Add to agent's `bind_tools()` call
4. Keep tools internal (not exposed via MCP)

---

## 🐛 Troubleshooting

### Issue: "GROQ_API_KEY not found"
**Solution:** Ensure `.env` file exists with valid API key
```powershell
# Verify .env exists
Test-Path .\.env

# Check content (don't share publicly)
Get-Content .\.env
```

### Issue: MCP server won't start
**Solution:** Check dependencies and Python version
```powershell
python --version  # Should be 3.10+
pip list | grep -i fastmcp
```

### Issue: Web fetch fails (403 Forbidden)
**Solution:** Some websites block scraping. System handles this gracefully
- Validator agent scores lower
- System uses alternative sources
- Report still generated with available data

### Issue: Slow response times
**Solution:** Configure fewer sources or optimize LLM
```python
# Use fewer sources
run_research_graph(query, num_sources=3)

# Or increase timeout in web_tools.py
timeout=60.0  # Increase from 30.0
```

---

## 📊 Performance Metrics

### Typical Execution Times
- **Web Search**: 2-3 seconds
- **Content Fetch**: 1-2 seconds per page
- **Research Agent**: 3-5 seconds
- **Validation Agent**: 2-3 seconds
- **Final Output Agent**: 2-3 seconds
- **Total**: ~10-15 seconds for 5 sources

### Resource Requirements
- **CPU**: Minimal (network-bound)
- **Memory**: ~200-300 MB
- **Network**: Required (STDIO/HTTP requests)
- **Storage**: <50 MB code

---

## 🔐 Security & Privacy

- **No Data Storage**: Results not persisted
- **API Key Protection**: Via environment variables
- **STDIO Transport**: Encrypted by VS Code
- **No Third-Party Analytics**: Pure execution
- **Tool Isolation**: Internal tools never exposed

---

## 🌟 Why This Architecture?

### Traditional MCP Limitations
```
User Request
    ↓
Tool Call
    ↓
Simple Result
```

**Problems:**
- No intelligence between tools
- User must coordinate multiple calls
- No quality validation
- Results not synthesized

### This System's Advantages
```
User Request
    ↓
Workflow Graph
    ├─ Research Agent (intelligent search)
    ├─ Validator Agent (quality check)
    └─ Final Output Agent (synthesis)
    ↓
Professional Report
```

**Benefits:**
- Autonomous orchestration
- Intelligent analysis layers
- Built-in quality validation
- Professional output
- Single-call interface

---

### VSCode Copilot Conversation

<img width="1375" height="745" alt="Screenshot 2025-11-12 170848" src="https://github.com/user-attachments/assets/5d36c8f1-ed2d-451d-a229-385a1a8041e0" />
<img width="1196" height="755" alt="Screenshot 2025-11-12 170936" src="https://github.com/user-attachments/assets/870df046-4dfd-4886-935b-8f6c9a699015" />
<img width="1217" height="649" alt="Screenshot 2025-11-12 170948 - Copy" src="https://github.com/user-attachments/assets/c63b37ff-ba0f-47b7-b747-6768a258eb4b" />
<img width="1238" height="638" alt="Screenshot 2025-11-12 171001" src="https://github.com/user-attachments/assets/eca92598-56cc-4c31-b253-ff130c0e4eba" />