MCP Scout

MCPSearch

集成MCP的人工智能多源研究和爬行平台

  

概述

MCPSearch是一个面向代理和开发人员的自托管研究堆栈。它结合了：

• 跨多个引擎的并行网络搜索
• HTTP+浏览器+隐形爬行
• 社交和开发者资源收集
• 结构化内容提取
• MCP原生工具暴露
• 更高层次的研究工作流程 investigate, compare，以及 trending

这个项目已经超越了简单的爬虫。当前形状为：

• 29个MCP工具 mcp_server/server.py
• 统一的 mcpsearch / mcpsearch_multi 接口
• 中的共享操作路由 mcp_server/handlers.py
• 中的旗舰编排层 agents/research_agent.py

当前能力

• 网络搜索：DuckDuckGo、谷歌和必应聚合
• 爬行模式：

fast 仅通过HTTP， hybrid 通过HTTP+剧作家， stealth 通过反机器人回退

• 提取：

markdown/文本提取、表格、代码块、图像、元数据、JSON-LD/OpenGraph/Microdata extruct

• 快速解析：

selectolax 使用BeautifulSoup回退进行热搜索解析路径

• 社会来源：

Reddit、推特/X、YouTube、GitHub

• HTTP缓存：

共享异步客户端工厂，在请求量大的路径上提供可选的Hishel支持的缓存

• 研究工作流程：

research_agent, investigate, compare, trending

• 工具发现：

list_tools, describe_tools, get_crawl_stats

安装

基本安装

git clone https://github.com/JonusNattapong/MCPSearch.git
cd MCPSearch
pip install -e .
playwright install chromium

开发安装

make dev

或者：

pip install -e ".[dev]"
playwright install chromium

可选的隐形依赖关系

crawler/stealth.py 安装后可以使用迷彩。如果迷彩不可用，MCPSearch将退回到基于Playwright的隐形行为。

环境变量

• OPENAI_API_KEY

可选。启用AI摘要时，由摘要流使用。

快速开始

命令行界面

# Search
mcpsearch search -q "AI agents"

# Crawl a page
mcpsearch crawl -u "https://example.com"

# Read a page in terminal-friendly format
mcpsearch read -u "https://example.com"

# Research workflow
mcpsearch research --query "browser fingerprinting" --depth deep --summarize

# Compare topics
mcpsearch compare --compare "React" "Vue" "Svelte" --depth medium

# Trending view
mcpsearch trending --max-results 10

# Run MCP server
mcpsearch server

面向Python/MCP的示例

# Unified tool
mcpsearch(action="search", query="LLM agents", limit=5)
mcpsearch(action="crawl", url="https://example.com", mode="hybrid")
mcpsearch(action="reddit", query="python", subreddit="learnpython")
mcpsearch(action="github", query="browser automation", sort="stars")

# Multi-action orchestration
mcpsearch_multi(actions='[
  {"action":"search","query":"agent memory patterns"},
  {"action":"reddit","query":"LocalLLaMA"},
  {"action":"github","query":"llm agents","sort":"stars"}
]')

# Flagship research tools
investigate(topic="Python async scraping", depth="deep", include_social=True)
compare(topics="React,Vue,Svelte", depth="medium", max_sources=3)
trending(platforms="reddit,github", limit=10)

MCP集成

克劳德桌面

{
  "mcpServers": {
    "mcpsearch": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/MCPSearch",
      "env": {
        "OPENAI_API_KEY": ""
      }
    }
  }
}

光标

{
  "mcpServers": {
    "mcpsearch": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/MCPSearch"
    }
  }
}

自定义MCP客户端

{
  "command": "python",
  "args": ["-m", "mcp_server"],
  "transport": "stdio"
}

工具图

统一工具

• mcpsearch
• mcpsearch_multi

搜索和抓取工具

• web_search
• search_and_summarize
• smart_search
• deep_search
• crawl_url
• hybrid_crawl
• crawl_recursive
• extract_content
• get_crawl_stats

社交工具

• search_reddit
• get_subreddit
• get_reddit_post
• search_twitter
• get_user_tweets
• search_youtube
• get_youtube_channel
• get_youtube_content
• search_github
• get_github_user
• get_github_repo
• get_github_readme

研究工具

• research_agent
• investigate
• compare
• trending

发现工具

• list_tools
• describe_tools

推荐入口点

如果您要将MCPSearch集成到代理中：

• 从...开始 list_tools 和 describe_tools
• 更喜欢 mcpsearch 用于简单布线
• 使用 mcpsearch_multi 当您想要并行源收集时
• 使用 investigate 更丰富的主题导向研究
• 使用 compare 当输出应该并排时
• 使用 trending 用于源发现和早期信号收集

研究工作流程

investigate

最好是当你想在搜索、抓取和社交资源中探索一个主题时。

investigate(
    topic="anti-bot browser strategies",
    depth="deep",
    include_social=True,
    include_summary=True,
    max_sources=5,
)

compare

最好是当你想要重复的浅层或中等调查和紧凑的比较结果时。

compare(
    topics="Playwright,Selenium,Camoufox",
    depth="medium",
    max_sources=3,
)

trending

最好是在深入挖掘之前想要新的线索。

trending(
    platforms="reddit,github",
    limit=10,
)

建筑

请求流

Query / URL / Topic
        |
        v
  mcpsearch / direct tool
        |
        v
 mcp_server/handlers.py
        |
        +--> search/aggregator.py
        +--> crawler/engine.py
        +--> crawler/hybrid.py
        +--> crawler/stealth.py
        +--> social/*.py
        +--> agents/research_agent.py

爬行策略

fast    -> HTTP only
hybrid  -> HTTP first, then browser rendering when needed
stealth -> multi-browser / anti-bot fallback path

当前项目结构

MCPSearch/
├── agents/                 # Higher-level research orchestration
├── crawler/                # HTTP, hybrid, stealth, extraction logic
├── mcp_server/             # MCP server, unified tools, shared handlers
├── search/                 # Search aggregation
├── social/                 # Reddit, Twitter/X, YouTube, GitHub scrapers
├── summarizer/             # AI summarization helpers
├── tests/                  # Workflow and unit tests
├── utils/                  # Cache, dedup, rate limiting
├── cli.py                  # CLI entry point
├── Makefile                # Dev/test/release commands
└── pyproject.toml          # Package metadata and dependencies

发展

有用的命令

make install
make dev
make test
make test-cov
make lint
make lint-fix
make format
make server
python3 scripts/benchmark_search_and_crawl.py

重点测试命令

make test-hybrid
make test-rate-limiter
pytest tests/test_extractor.py -v
pytest tests/test_search_parsers.py -v
pytest tests/test_mcp_integration.py -v
pytest tests/test_mcp_tools.py -v

发布

make patch
make minor
make major

版本来源于 .

项目状态说明

• README现在反映了 mcpsearch / mcpsearch_multi，而不是老年人 scout 命名。
• Playwright是声明依赖关系的一部分。
• 迷彩支持存在于代码中，但在安装时是可选的。
• 现在的主要研究方向是编排、归因和多源分析，而不仅仅是单页爬行。

实用的下一步改进

看 docs/USEFUL_LIBS.md 查看适合当前架构的库和实现技巧的精选列表。

法律和道德使用

负责任地使用MCPSearch。

• 尊重目标网站政策和适用法律。
• 使用速率限制和缓存来减少负载。
• 在大规模抓取之前审查平台条款。
• 避免收集或重新分发受限制的个人数据。

贡献

贡献指导生活 CONTRIBUTING.md.

许可证

MIT。看 LICENSE.