🚀 多Agent研究系统MCP服务器
VS代码副本集成的高级多代理架构 下一代模型上下文协议（MCP）服务器，演示了如何使用复杂的工具构建强大的多代理系统，摆脱了传统的仅使用专用工具的MCP实现。
______________________________________________________________________
📋 目录
______________________________________________________________________
🎯 概述
该项目代表了 MCP服务器设计的范式转变。虽然传统的MCP服务器侧重于公开简单的专用工具，但这种实现利用了 多代理编排 创建一个可以无缝集成到VS Code Copilot中的复杂研究系统。
该系统将三个专门的人工智能代理与强大的内部工具相结合，以执行全面的研究任务——所有这些任务都通过简单直观的MCP工具公开。
为什么这很重要
- 传统MCP：直接面向客户的单一用途工具
- 这种方法：多代理协调、工具编排和智能工作流管理被包装在一个干净的界面中
- 结果：通过熟悉的工具提供更强大、更具情境意识和更可靠的结果
______________________________________________________________________
🏗️ 建筑
系统概述
┌─────────────────────────────────────────────────────────────┐
│ 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 ││
│ └────────────────┘ └─────────────────────────────────┘│
└──────────────────────────────────────────────────────────┘代理管道
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)______________________________________________________________________
✨ 主要特点
🤖 多代理编排
- 三个专业代理：研究、验证和输出生成
- 顺序工作流：每个代理都会优化前一个代理的输出
- 国家保护：基于TypedDict的状态管理可确保数据一致性
🔧 高级工具
- 网页搜索：DuckDuckGo集成用于源代码发现
- 内容提取：基于Beautiful Soup的网页解析
- 新闻搜索：专业的新闻发现能力
- 全部内部：工具不向客户端公开，只共享结果
🧠 智能分析
- LLM供电：Groq's Llama 3.3（70B）用于精确分析
- 温度控制：每个代理的优化设置（研究：0.3，验证：0.2，输出：0.4）
- JSON解析：具有回退机制的结构化输出
📊 质量保证
- 验证评分：0-100置信度评分系统
- 可靠性评估：多因素可靠性评级
- 错误跟踪：问题识别和建议
🔐 安全集成
- 环境变量：API密钥通过
.env - STDIO传输：安全MCP通信通道
- 无数据泄露：对客户端隐藏的内部工具
______________________________________________________________________
🛠️ 技术栈
| 组件 | 技术 | 目的 |
|---|---|---|
| 代理框架 | LangGraph | 工作流编排和状态管理 |
| LLM提供者 | Groq（Llama 3.3 70B） | 高级推理与分析 |
| 语言 | Python 3.10+ | 实现语言 |
| MCP框架 | FastMCP | 服务器协议和工具暴露 |
| HTTP客户端 | HTTPX | 异步web请求 |
| HTML解析器 | BeautifulSoup 4 | 内容提取 |
| 聊天模特 | LangChain | LLM集成抽象 |
______________________________________________________________________
📂 项目结构
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__/______________________________________________________________________
📦 安装
先决条件
- Python 3.10或更高版本
- Groq API密钥（在 https://console.groq.com)
- 带有Copilot扩展名的VS代码
设置步骤
- 克隆或下载项目
cd d:\GENAI\AgentsCrossToolMCP- 创建虚拟环境
python -m venv .venv
.\.venv\Scripts\Activate.ps1- 安装依赖项
pip install -r requirements.txt- 配置环境变量
创建一个 .env 项目根目录中的文件：
GROQ_API_KEY=your_groq_api_key_here- 验证安装
python server.py您应该看到FastMCP横幅和服务器启动消息。
______________________________________________________________________
⚙️ 配置
环境变量
# 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 creativityMCP服务器配置
MCP服务器在VS Code中通过以下设置进行配置：
{
"mcpServers": {
"my-mcp-server": {
"command": "python",
"args": ["d:\\GENAI\\AgentsCrossToolMCP\\server.py"],
"disabled": false,
"alwaysAllow": ["run_research_graph", "workflow_info"]
}
}
}______________________________________________________________________
🚀 用法
通过VS代码复制
连接后，您可以直接在Copilot中使用该系统：
示例提示：
@my-mcp-server Use run_research_graph to research "AI safety in Large Language Models"
with 5 sources and provide a comprehensive analysis.副驾驶将：
- 呼叫
run_research_graph(query, 5) - 显示多页研究报告
- 引用来源和验证指标
程序化使用
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())命令行
# Start the server
python server.py
# In another terminal, test via MCP client
# (Configure in VS Code settings)______________________________________________________________________
🔄 工作流管道
逐步执行
1️⃣ 初始化
- 用户提供查询和源计数
- 系统初始化ResearchState对象
- 工作流开始
2️⃣ 研究代理处理
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, insights3️⃣ 验证试剂处理
Input: research_summary, key_facts
├─ LLM Assessment of quality
├─ Scoring (0-100)
├─ Reliability rating
└─ Output: validation_score, status, issues4️⃣ 最终输出代理处理
Input: all previous outputs + sources
├─ Combine all findings
├─ Format as markdown report
├─ Add structure & organization
└─ Output: final_report (professional document)5️⃣ 返回给客户
- MCP服务器返回final_report
- 副本在编辑器中显示
- 包括来源和验证指标
______________________________________________________________________
🔌 VS代码集成
安装说明
- 打开VS代码设置 (
Ctrl+,)
- 转到MCP服务器部分
- 添加配置：
"mcpServers": {
"my-mcp-server": {
"command": "python",
"args": ["d:\\GENAI\\AgentsCrossToolMCP\\server.py"],
"disabled": false
}
}- 重新启动VS代码
- 在Copilot聊天中验证：
- 打开Copilot聊天(Ctrl+L) - 类型 @my-mcp-server - 应查看可用工具
在Copilot中的使用
@my-mcp-server Can you research the latest developments in quantum computing
and provide a detailed analysis with key insights?______________________________________________________________________
🔗 API 参考
工具： run_research_graph
目的：执行全面的研究工作流程
参数：
run_research_graph(
query: str, # Research topic/question
num_sources: int = 5 # Number of sources to fetch
) -> str退货：
Professional markdown report containing:
- Executive Summary
- Key Findings
- Detailed Analysis
- Research Sources
- Validation Metrics
- Recommendations例子：
report = await run_research_graph(
query="Climate change impact on agricultural productivity",
num_sources=5
)
print(report)______________________________________________________________________
工具： workflow_info
目的：获取有关多代理系统的信息
参数： 无
退货：
String describing:
- Agent roles and responsibilities
- Available capabilities
- Tool information例子：
info = await workflow_info()
print(info)______________________________________________________________________
📚 例子
示例1：经济研究
查询：
Query: India GDP growth rate 2024 2025 economic challenges obstacles
Sources: 5输出包括：
- 国内生产总值增长统计
- 确定的经济挑战
- 市场障碍
- 专家建议
- 数据可靠性评估
______________________________________________________________________
示例2：技术趋势
查询：
Query: Latest developments in quantum computing and AI integration
Sources: 8输出包括：
- 最近的突破
- 技术见解
- 行业趋势
- 研究机会
- 跨域应用程序
______________________________________________________________________
🧑💻 发展
项目架构原则
- 关注点分离
- 代理专注于特定任务 - 工具处理数据获取 - 服务器处理协议转换
- 状态不变性模式
- TypedDict确保类型安全 - Operator.add用于消息累积 - 清晰的状态转换
- 错误处理
- 工具故障时性能下降 - LLM JSON解析回退 - 全面的错误消息
- 可扩展性
- 易于添加新代理 - 易于集成新工具 - 灵活的温度/模型参数
添加新代理
- 在中创建新的代理类
agents/ - 实施
async __call__(self, state)方法 - 添加到图形中
graph_workflow.py - 如果需要，更新state.py
添加新工具
- 在中创建工具功能
tools/web_tools.py - 用…装饰
@tool - 添加到代理
bind_tools()呼叫 - 保持工具内部（不通过MCP暴露）
______________________________________________________________________
🐛 故障排除
问题：“找不到GROQ_API_KEY”
解决方案： 确保 .env 存在具有有效API密钥的文件
# Verify .env exists
Test-Path .\.env
# Check content (don't share publicly)
Get-Content .\.env问题：MCP服务器无法启动
解决方案： 检查依赖关系和Python版本
python --version # Should be 3.10+
pip list | grep -i fastmcp问题：Web获取失败（403禁止）
解决方案： 一些网站阻止抓取。系统处理得很好
- 验证器代理得分较低
- 系统使用替代来源
- 仍使用可用数据生成报告
问题：响应时间慢
解决方案： 配置更少的源或优化LLM
# Use fewer sources
run_research_graph(query, num_sources=3)
# Or increase timeout in web_tools.py
timeout=60.0 # Increase from 30.0______________________________________________________________________
📊 性能指标
典型执行时间
- 网页搜索：2-3秒
- 内容提取：每页1-2秒
- 研究代理：3-5秒
- 验证代理：2-3秒
- 最终输出代理：2-3秒
- 总计：5个来源约10-15秒
资源需求
- 中央处理器：最小（网络限制）
- 记忆：约200-300 MB
- 网络：必填（STDIO/HTTP请求）
- 存储：\<50 MB代码
______________________________________________________________________
🔐 安全与隐私
- 无数据存储：结果未持续
- API密钥保护：通过环境变量
- STDIO传输：通过VS代码加密
- 无第三方分析：纯粹的执行
- 工具隔离：从未暴露的内部工具
______________________________________________________________________
🌟 为什么是这种架构？
传统MCP限制
User Request
↓
Tool Call
↓
Simple Result问题：
- 工具之间没有智能
- 用户必须协调多个呼叫
- 无质量验证
- 结果未合成
该系统的优点
User Request
↓
Workflow Graph
├─ Research Agent (intelligent search)
├─ Validator Agent (quality check)
└─ Final Output Agent (synthesis)
↓
Professional Report优点：
- 自主编排
- 智能分析层
- 内置质量验证
- 专业输出
- 单呼叫接口
______________________________________________________________________