Ai Research Agent MCP

🚀 MCP 驅動的 AI 研究工程師

這是一個基於模型上下文協議（MCP）的自主 AI 代理，它能夠將單個提示轉化為完整的研究報告，整合網絡信息、個人筆記、代碼和圖表等內容，為研究工作提供全面且高效的支持。

🚀 快速開始

前提條件

• Python 3.10 或更高版本（推薦 Python 3.11+）
• Claude Desktop 或 Cursor IDE（支持 MCP 的客戶端）
• Git（用於克隆倉庫）
• uv（可選，但推薦 - 在此安裝）或 pip
• （可選）用於增強功能的 API 密鑰

安裝步驟

1. 克隆倉庫

git clone https://github.com/prabureddy/ai-research-agent-mcp.git
cd ai-research-agent-mcp

2. 安裝依賴

選項 A：使用 uv（推薦 - 快 10 - 100 倍！）

# 進入服務器目錄
cd server

# 若未安裝 uv，進行安裝
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 創建並激活虛擬環境
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安裝所需包（比 pip 快很多！）
uv pip install -r requirements.txt

選項 B：使用 pip（傳統方式）

# 進入服務器目錄
cd server

# 創建並激活虛擬環境
python3.11 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安裝所需包
pip install -r requirements.txt

3. 配置環境

# 返回項目根目錄
cd ..

# 複製示例環境文件
cp .env.example .env

# 使用首選文本編輯器編輯 .env（可選）
nano .env  # 或 vim, code 等

環境配置（可選）：

# 可選：使用 Brave Search（比 DuckDuckGo 更好）
BRAVE_API_KEY=your_brave_api_key_here

# 可選：用於未來的 Anthropic 集成
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 可選：自定義路徑
RESEARCH_RUNS_DIR=./research_runs
KNOWLEDGE_BASE_DIR=./knowledge_base

# RAG 默認使用本地嵌入（無需 API 密鑰！）
USE_LOCAL_EMBEDDINGS=true
EMBEDDING_MODEL=all-MiniLM-L6-v2

⚠️ 重要提示

切勿將 .env 文件提交到版本控制中，它已包含在 .gitignore 中。

💡 使用建議

系統默認使用本地 sentence-transformers 嵌入，因此 RAG 功能無需 API 密鑰！

4. 創建所需目錄

# 創建用於數據存儲的目錄
mkdir -p research_runs knowledge_base data/vector_db logs

5. 配置 Claude Desktop

macOS： 編輯 ~/Library/Application Support/Claude/claude_desktop_config.json Windows： 編輯 %APPDATA%\Claude\claude_desktop_config.json Linux： 編輯 ~/.config/Claude/claude_desktop_config.json

首先找到絕對路徑：

# 在項目目錄中運行：
pwd
# 示例輸出: /Users/yourname/Projects/ai-research-agent-mcp

# 找到 Python 路徑（如果使用虛擬環境）：
which python  # 或: which python3.11
# 示例輸出: /Users/yourname/Projects/ai-research-agent-mcp/server/venv/bin/python3.11

配置模板： 添加以下配置，將路徑和環境變量替換為實際值：

{
  "mcpServers": {
    "research-engineer": {
      "command": "/absolute/path/to/python",
      "args": [
        "/absolute/path/to/ai-research-agent-mcp/server/src/server.py"
      ],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key_here_or_remove_this_line",
        "ANTHROPIC_API_KEY": "your_anthropic_api_key_here_or_remove_this_line",
        "SEARCH_PROVIDER": "duckduckgo",
        "MAX_SEARCH_RESULTS": "10",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "USE_LOCAL_EMBEDDINGS": "true",
        "VECTOR_DB_PATH": "/absolute/path/to/ai-research-agent-mcp/data/vector_db",
        "CHUNK_SIZE": "1000",
        "CHUNK_OVERLAP": "200",
        "SANDBOX_TIMEOUT": "30",
        "SANDBOX_MAX_MEMORY_MB": "512",
        "ALLOWED_PACKAGES": "numpy,pandas,matplotlib,seaborn,scipy,scikit-learn",
        "RESEARCH_RUNS_DIR": "/absolute/path/to/ai-research-agent-mcp/research_runs",
        "KNOWLEDGE_BASE_DIR": "/absolute/path/to/ai-research-agent-mcp/knowledge_base",
        "LOG_LEVEL": "INFO",
        "LOG_FILE": "/absolute/path/to/ai-research-agent-mcp/logs/research_engineer.log"
      }
    }
  }
}

⚠️ 重要提示

• 所有文件路徑使用 絕對路徑（不要使用 ~ 或相對路徑）
• 如果使用虛擬環境，使用虛擬環境內的 Python 路徑
• 移除或留空沒有的 API 密鑰（DuckDuckGo 無需密鑰即可工作）
• env 中的所有路徑必須是絕對路徑

macOS/Linux（使用虛擬環境）示例：

{
  "mcpServers": {
    "research-engineer": {
      "command": "/Users/yourname/Projects/ai-research-agent-mcp/server/venv/bin/python3.11",
      "args": [
        "/Users/yourname/Projects/ai-research-agent-mcp/server/src/server.py"
      ],
      "env": {
        "SEARCH_PROVIDER": "duckduckgo",
        "MAX_SEARCH_RESULTS": "10",
        "USE_LOCAL_EMBEDDINGS": "true",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "VECTOR_DB_PATH": "/Users/yourname/Projects/ai-research-agent-mcp/data/vector_db",
        "RESEARCH_RUNS_DIR": "/Users/yourname/Projects/ai-research-agent-mcp/research_runs",
        "KNOWLEDGE_BASE_DIR": "/Users/yourname/Projects/ai-research-agent-mcp/knowledge_base",
        "LOG_FILE": "/Users/yourname/Projects/ai-research-agent-mcp/logs/research_engineer.log"
      }
    }
  }
}

macOS/Linux（使用 uv）示例：

{
  "mcpServers": {
    "research-engineer": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/yourname/Projects/ai-research-agent-mcp/server",
        "python",
        "src/server.py"
      ],
      "env": {
        "SEARCH_PROVIDER": "duckduckgo",
        "MAX_SEARCH_RESULTS": "10",
        "USE_LOCAL_EMBEDDINGS": "true",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "VECTOR_DB_PATH": "/Users/yourname/Projects/ai-research-agent-mcp/data/vector_db",
        "RESEARCH_RUNS_DIR": "/Users/yourname/Projects/ai-research-agent-mcp/research_runs",
        "KNOWLEDGE_BASE_DIR": "/Users/yourname/Projects/ai-research-agent-mcp/knowledge_base",
        "LOG_FILE": "/Users/yourname/Projects/ai-research-agent-mcp/logs/research_engineer.log"
      }
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "research-engineer": {
      "command": "C:/Users/yourname/Projects/ai-research-agent-mcp/server/venv/Scripts/python.exe",
      "args": [
        "C:/Users/yourname/Projects/ai-research-agent-mcp/server/src/server.py"
      ],
      "env": {
        "SEARCH_PROVIDER": "duckduckgo",
        "MAX_SEARCH_RESULTS": "10",
        "USE_LOCAL_EMBEDDINGS": "true",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "VECTOR_DB_PATH": "C:/Users/yourname/Projects/ai-research-agent-mcp/data/vector_db",
        "RESEARCH_RUNS_DIR": "C:/Users/yourname/Projects/ai-research-agent-mcp/research_runs",
        "KNOWLEDGE_BASE_DIR": "C:/Users/yourname/Projects/ai-research-agent-mcp/knowledge_base",
        "LOG_FILE": "C:/Users/yourname/Projects/ai-research-agent-mcp/logs/research_engineer.log"
      }
    }
  }
}

6. 重啟 Claude Desktop

完全退出並重新啟動 Claude Desktop 以使更改生效。

驗證安裝

在 Claude Desktop 中輸入：

List available tools

你應該看到：web_search、web_research、execute_code、create_research_run 等。

第一個研究任務

嘗試以下簡單任務：

Research the current state of electric vehicles in 2026. 
Include market size, major players, and growth trends. 
Create a simple visualization showing EV adoption over time.

代理將：

1. 在網絡上搜索電動汽車數據
2. 編寫 Python 代碼創建圖表
3. 展示帶有來源的研究結果

✨ 主要特性

• ✅ 自主多步驟研究
• ✅ 網絡搜索和內容提取
• ✅ 基於個人知識庫的檢索增強生成（RAG）
• ✅ 安全的代碼執行並捕獲輸出
• ✅ 結構化報告生成
• ✅ 自我評估和質量指標
• ✅ 全面的日誌記錄和跟蹤
• ✅ 可復現的研究運行

📦 安裝指南

一鍵安裝

選項 1：使用 uv（推薦 - 快速！）

git clone https://github.com/prabureddy/ai-research-agent-mcp.git \
  && cd ai-research-agent-mcp/server \
  && uv venv \
  && source .venv/bin/activate \
  && uv pip install -r requirements.txt

選項 2：使用 pip（傳統方式）

git clone https://github.com/prabureddy/ai-research-agent-mcp.git \
  && cd ai-research-agent-mcp/server \
  && python3 -m venv venv \
  && source venv/bin/activate \
  && pip3 install -r requirements.txt

💻 使用示例

基礎用法

簡單查詢

Research the pros and cons of electric scooters vs bikes for urban commuting.

代理將：

1. 在網絡上搜索相關信息
2. 整理研究結果
3. 展示總結

綜合研究與代碼

Deep dive: Compare electric scooters vs bikes for my 5-mile daily commute. 
Build a cost calculator in Python that shows total cost of ownership over 3 years.
Include purchase price, maintenance, electricity/none, and create visualizations.

代理將：

1. 研究成本、維護和使用數據
2. 構建 Python 成本計算器
3. 創建比較圖表
4. 編寫綜合報告
5. 將所有內容保存到研究運行目錄
6. 自我評估工作

高級用法

工具使用示例

網絡研究

僅搜索：

Use web_search to find the latest news about AI regulation in 2026

綜合研究與抓取：

Use web_research to gather detailed information about multifamily real estate cap rates, 
and scrape the top 5 results for full content

抓取特定 URL：

Scrape this article and summarize the key points: https://example.com/article

知識庫（RAG）

索引筆記：

Index all files in my knowledge_base directory so I can query them later

查詢知識庫：

Query my knowledge base for information about real estate investment strategies

結合網絡和知識庫：

Research current EV market trends using both web search and my personal notes 
in the knowledge base

代碼執行

簡單計算：

Write Python code to calculate the compound annual growth rate (CAGR) 
for an investment that grew from $10,000 to $25,000 over 5 years

數據分析：

Create a Python script that:
1. Generates sample sales data for 12 months
2. Calculates moving averages
3. Creates a line chart with trend line
4. Prints summary statistics

金融建模：

Build a mortgage calculator in Python that:
- Takes loan amount, interest rate, and term
- Calculates monthly payment
- Shows amortization schedule
- Creates a chart showing principal vs interest over time

使用最佳實踐

1. 明確具體

❌ 模糊：

Research AI

✅ 具體：

Research the current state of large language models in 2026, focusing on:
- Model sizes and capabilities
- Training costs
- Commercial applications
- Regulatory challenges

2. 請求結構化

❌ 無結構：

Tell me about real estate

✅ 結構化：

Research multifamily real estate investment in 2026:
1. Current market conditions
2. Financial modeling
3. Risk analysis
4. Recommendations

3. 結合工具

✅ 有效：

Research electric vehicle adoption rates using:
1. Web search for latest statistics
2. My knowledge base for past analysis
3. Python code to project future adoption
4. Visualizations of trends

4. 請求評估

✅ 注重質量：

After completing the analysis, evaluate your work and tell me:
- What data sources were most valuable?
- What are the limitations of this analysis?
- What would make this analysis more robust?

📚 詳細文檔

系統架構

系統概述

┌─────────────────────────────────────────────────────────────┐
│                    Claude Desktop / Cursor                   │
│                     (MCP Client/Host)                        │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                    MCP Server (Python)                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Tool Registry & Router                   │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Web Research │  │   RAG Tool   │  │Code Sandbox  │     │
│  │              │  │              │  │              │     │
│  │ • Search     │  │ • Embeddings │  │ • Restricted │     │
│  │ • Scrape     │  │ • ChromaDB   │  │   Python     │     │
│  │ • Extract    │  │ • Query      │  │ • Safe Exec  │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐                        │
│  │  Workspace   │  │  Evaluator   │                        │
│  │              │  │              │                        │
│  │ • File I/O   │  │ • Metrics    │                        │
│  │ • Organize   │  │ • Critique   │                        │
│  │ • Manage     │  │ • Quality    │                        │
│  └──────────────┘  └──────────────┘                        │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
        ┌────────────────────────────────────┐
        │      External Services              │
        │                                     │
        │  • DuckDuckGo / Brave Search       │
        │  • OpenAI Embeddings API           │
        │  • Web Scraping (HTTP)             │
        └────────────────────────────────────┘
                         │
                         ▼
        ┌────────────────────────────────────┐
        │      Local Storage                  │
        │                                     │
        │  • research_runs/                  │
        │  • knowledge_base/                 │
        │  • data/vector_db/                 │
        │  • logs/                           │
        └────────────────────────────────────┘

核心組件

1. MCP 服務器 ()

職責：

• 通過 MCP 協議暴露工具
• 將工具調用路由到適當的處理程序
• 處理錯誤和日誌記錄
• 管理服務器生命週期

技術：

• Python 3.10+
• MCP SDK (mcp 包)
• 用於 I/O 操作的異步/等待

2. 網絡研究工具 ()

職責：

• 在網絡上搜索信息
• 抓取並提取乾淨的內容
• 處理速率限制和重試

組件：

• 搜索提供商： DuckDuckGo（默認，無需 API 密鑰），Brave Search（可選）
• 內容提取： Trafilatura 用於提取主要內容，BeautifulSoup 用於提取元數據

3. RAG 工具 ()

職責：

• 將文檔索引到向量數據庫中
• 對知識庫進行語義搜索
• 支持多種文件格式（Markdown、PDF、DOCX）

組件：

• 向量數據庫： ChromaDB（持久化，本地）
• 嵌入： OpenAI text-embedding-3-small
• 分塊策略：1000 字符，重疊 200 字符

4. 代碼沙箱 ()

職責：

• 安全地執行 Python 代碼
• 捕獲輸出和繪圖
• 實施資源限制

安全層：

1. RestrictedPython：AST 級別的代碼限制
2. 資源限制：內存和 CPU 約束
3. 超時：執行時間限制
4. 允許的包：安全庫的白名單（numpy、pandas、matplotlib 等）

5. 工作區工具 ()

職責：

• 組織研究輸出
• 管理文件 I/O
• 跟蹤研究運行

目錄結構：

research_runs/
└── YYYY-MM-DD_HHMMSS_task-name/
    ├── metadata.json
    ├── report.md
    ├── evaluation.json
    ├── sources.json
    ├── code/
    │   └── *.py
    ├── charts/
    │   └── *.png
    └── data/
        └── *.json

6. 評估工具 ()

職責：

• 質量評估
• 自我批判生成
• 指標跟蹤

質量指標（0 - 10 分制）：

• 清晰度、數據依據、完整性、代碼質量、可操作性、置信度

配置

環境變量

查看 .env.example 以獲取所有可用的配置選項：

# 搜索配置
BRAVE_API_KEY=...           # 可選：比 DuckDuckGo 更好的搜索
SEARCH_PROVIDER=duckduckgo  # duckduckgo 或 brave
MAX_SEARCH_RESULTS=10

# RAG 配置（默認使用本地嵌入）
USE_LOCAL_EMBEDDINGS=true
EMBEDDING_MODEL=all-MiniLM-L6-v2
VECTOR_DB_PATH=./data/vector_db
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

# 代碼沙箱配置
SANDBOX_TIMEOUT=30
SANDBOX_MAX_MEMORY_MB=512

# 目錄配置
RESEARCH_RUNS_DIR=./research_runs
KNOWLEDGE_BASE_DIR=./knowledge_base

# 日誌記錄
LOG_LEVEL=INFO

Cursor IDE 配置（替代方案）

1. 打開 Cursor 設置

按下 Cmd+,（Mac）或 Ctrl+,（Windows/Linux）

2. 搜索 "MCP"

找到 MCP 服務器配置部分。

3. 添加服務器配置

添加與 Claude Desktop 相同的配置（詳見上面的第 5 節示例）。

基本示例：

{
  "research-engineer": {
    "command": "/absolute/path/to/python",
    "args": [
      "/absolute/path/to/ai-research-agent-mcp/server/src/server.py"
    ],
    "env": {
      "SEARCH_PROVIDER": "duckduckgo",
      "USE_LOCAL_EMBEDDINGS": "true",
      "VECTOR_DB_PATH": "/absolute/path/to/data/vector_db",
      "RESEARCH_RUNS_DIR": "/absolute/path/to/research_runs",
      "KNOWLEDGE_BASE_DIR": "/absolute/path/to/knowledge_base"
    }
  }
}

使用 uv：

{
  "research-engineer": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/absolute/path/to/ai-research-agent-mcp/server",
      "python",
      "src/server.py"
    ],
    "env": {
      "SEARCH_PROVIDER": "duckduckgo",
      "USE_LOCAL_EMBEDDINGS": "true"
    }
  }
}

項目結構

完整的文件和目錄結構：

ai-research-agent-mcp/
│
├── README.md                          # 本文件 - 完整文檔
├── LICENSE                            # MIT 許可證
├── .gitignore                         # Git 忽略規則
├── .env.example                       # 示例環境變量
│
├── server/                            # MCP 服務器實現
│   ├── requirements.txt               # Python 依賴項
│   ├── pyproject.toml                 # 項目元數據和構建配置
│   │
│   └── src/                           # 源代碼
│       ├── __init__.py                # 包初始化
│       ├── server.py                  # 主 MCP 服務器入口點
│       ├── config.py                  # 配置管理
│       │
│       └── tools/                     # 工具實現
│           ├── __init__.py            # 工具包初始化
│           ├── web_research.py        # 網絡搜索和抓取
│           ├── rag_tool.py            # 用於知識庫的向量 RAG
│           ├── code_sandbox.py        # 安全的 Python 代碼執行
│           ├── workspace.py           # 文件和工作區管理
│           └── evaluator.py           # 質量評估和批判
│
├── agent/                             # 代理編排
│   └── prompts/                       # 系統提示和模板
│       └── research_agent.md          # 主要研究代理提示
│
├── config/                            # 配置文件
│   └── claude_desktop_config.json     # 示例 Claude Desktop 配置
│
├── examples/                          # 示例任務和輸出
│   └── example_research_task.md       # 帶有預期輸出的詳細示例
│
├── knowledge_base/                    # 個人知識庫（用戶內容）
│   └── example_notes.md               # RAG 示例筆記
│
├── research_runs/                     # 研究輸出目錄（運行時創建）
│   └── YYYY-MM-DD_HHMMSS_task-name/   # 單個研究運行
│       ├── metadata.json              # 運行元數據
│       ├── report.md                  # 最終報告
│       ├── evaluation.json            # 自我評估
│       ├── sources.json               # 數據源
│       ├── code/                      # 生成的代碼
│       │   └── *.py
│       ├── charts/                    # 可視化
│       │   └── *.png
│       └── data/                      # 數據文件
│           └── *.json
│
├── data/                              # 數據存儲（運行時創建）
│   └── vector_db/                     # ChromaDB 向量數據庫
│
└── logs/                              # 日誌文件（運行時創建）
    └── research_engineer.log          # 應用程序日誌

關鍵文件說明

文件	用途
	帶有工具註冊表的主 MCP 服務器
	配置加載和驗證
	網絡搜索和抓取
	向量數據庫和語義搜索
	安全的 Python 代碼執行
	文件 I/O 和研究運行管理
	質量指標和自我批判

🔧 技術細節

系統架構設計

本系統採用模塊化設計，通過 MCP 協議實現組件間的通信。MCP 服務器作為核心，負責工具的註冊、路由和管理。各個工具模塊（如網絡研究、RAG、代碼沙箱等）獨立實現特定功能，通過 MCP 服務器進行調用。這種設計使得系統具有良好的可擴展性和維護性。

安全機制

代碼沙箱採用多層安全機制確保代碼執行的安全性。RestrictedPython 對代碼進行 AST 級別的限制，防止惡意代碼的執行。同時，設置了內存和 CPU 約束、執行時間限制以及允許的包白名單，進一步保障系統的安全穩定運行。

數據處理與存儲

RAG 工具使用 ChromaDB 作為向量數據庫，將文檔進行嵌入並存儲。通過分塊策略，將文檔分割成合適大小的塊，提高檢索效率。研究輸出和日誌數據分別存儲在 research_runs 和 logs 目錄中，便於管理和追溯。

📄 許可證

本項目採用 MIT 許可證。詳情請參閱 LICENSE 文件。

---

希望你享受使用本 AI 研究工程師！🚀