使用说明

┌─────────────────────────────────────────────────────────────┐
│  🔍 Yandex Search MCP - Unofficial Community Project        │
│  ⚡ Powered by Playwright + TypeScript + MCP Framework       │
│  🚀 Enhanced with Content Extraction & LLM Context          │
└─────────────────────────────────────────────────────────────┘

⚠️ 重要免责声明

这是一个 非官方社区项目 并且不隶属于、认可或关联于：

Yandex有限责任公司 （搜索引擎提供商）

Anthropic （克劳德和MCP的创造者）

谷歌（剧作家维护者）

此工具使用浏览器自动化来访问Yandex搜索。用户负责：

遵守Yandex的服务条款

遵守费率限制和机器人政策

使用自己的身份验证Cookie

不将此工具用于恶意目的

📋 目录

✨ 特性
🚀 快速开始
📦 安装
🍪 Cookie设置
⚙️ 配置
🎯 用法
🔧 工具
🏗️ 建筑
🛠️ 故障排除
🤝 贡献
📄 许可证

✨ 特性

核心能力

功能	描述	状态
🔍 Yandex搜索	使用完整参数控制搜索Yandex	✅
🕵️ 隐身模式	带有反检测插件的剧作家	✅
🍪 Cookie认证	绕过验证码的持久身份验证	✅
🌍 多区域	支持yandex.com、.ru、.tr等。	✅
🔒 安全搜索	内容筛选选项	✅

增强功能（v2.0）

功能	描述	状态
📄 内容提取	自动获取和提取页面内容	✅
🧠 相关性评分	基于人工智能的内容排名和优先级排序	✅
📊 LLM上下文格式	针对LLM优化的结构化输出	✅
💾 智能缓存	具有域特定TTL的LRU缓存	✅
🎯 来源多样性	防止结果中的域群集	✅
📈 许可证管理	具有句子保留功能的智能截断	✅

🚀 快速开始

# 1. Clone the repository
git clone https://github.com/bpawnzZ/yandex-search-mcp.git
cd yandex-search-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Configure cookies (see Cookie Setup section)
# 5. Add to MCP client configuration
# 6. Start searching! 🎉

📦 安装

先决条件

Node.js 18+
npm或纱线
Yandex帐户（用于Cookie）
Cookie编辑器浏览器扩展程序（或类似程序）

选项1：克隆和构建

git clone https://github.com/bpawnzZ/yandex-search-mcp.git
cd yandex-search-mcp
npm install
npm run build

选项2：与npx一起使用（发布后）

npx yandex-search-mcp

🍪 Cookie设置

为什么饼干？

Yandex对自动请求实施验证码挑战。使用经过身份验证的Cookie允许该工具绕过这些挑战并无缝执行搜索。

获取您的Cookie

安装Cookie编辑器扩展：
- 铬： Cookie编辑器扩展
- 火狐浏览器： Cookie编辑器插件
登录Yandex：
- 首选 yandex.com
- 登录您的Yandex帐户（或创建一个）
- 执行搜索以确保设置了Cookie
导出Cookie：
- 单击浏览器中的Cookie编辑器图标
- 点击“导出”按钮（或JSON格式）
- 复制JSON数组
保存Cookie：
- 将JSON粘贴到 cookies/yandex-cookies.json
- 确保文件是有效的JSON

Cookie文件结构示例

[
  {
    "domain": ".yandex.com",
    "expirationDate": 1800000000.000000,
    "hostOnly": false,
    "httpOnly": true,
    "name": "Session_id",
    "path": "/",
    "sameSite": "no_restriction",
    "secure": true,
    "session": false,
    "storeId": null,
    "value": "YOUR_SESSION_ID_HERE"
  }
]

重要提示： 确保您的Cookie安全，不要将其提交到公共存储库！

⚙️ 配置

MCP客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-search": {
      "command": "node",
      "args": ["/path/to/yandex-search-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Cline（VS代码扩展）

添加 ~/.kilocode/mcp.json:

{
  "mcpServers": {
    "yandex-search": {
      "command": "node",
      "args": ["/home/insomnia/git/yandex-search-mcp/dist/index.js"]
    }
  }
}

环境变量

# Optional configuration
MAX_PAGES_PER_QUERY=5        # Default: 3
MAX_TOKENS_PER_PAGE=4000     # Default: 3000
CACHE_TTL_HOURS=24          # Default: 24

🎯 用法

基本搜索

// Simple search - returns titles, URLs, snippets
{
  "tool": "yandex_search",
  "params": {
    "query": "artificial intelligence",
    "numResults": 10,
    "region": "com",
    "language": "en"
  }
}

通过内容提取增强搜索

// Enhanced search - fetches and analyzes page content
{
  "tool": "yandex_search_enhanced",
  "params": {
    "query": "artificial intelligence benefits",
    "numResults": 5,
    "region": "com",
    "fetch_content": true,
    "max_pages": 3,
    "max_tokens_per_page": 3000,
    "analysis_level": "detailed",
    "context_format": "synthesized"
  }
}

输出格式

增强的工具支持多种输出格式：

格式	描述	用例
`raw`	完整提取内容	当您需要完整文本时
`summarized`	简述要点	快速概述
`synthesized`	跨源分析（默认）	研究和分析
`qa_ready`	问答格式	直接回答

示例响应（综合）

{
  "summary": "Based on 3 sources (12,456 words analyzed), here is what we found about \"artificial intelligence benefits\":",
  "key_findings": [
    {
      "source": "example.com",
      "finding": "AI increases productivity by 40% in manufacturing",
      "confidence": "high"
    }
  ],
  "synthesized_knowledge": "Synthesis of findings...",
  "source_references": [
    {
      "url": "https://example.com/ai-benefits",
      "title": "AI Benefits in 2026",
      "key_points": ["Increased productivity", "Cost reduction"],
      "relevance_note": "Relevance score: 85.3/100"
    }
  ],
  "metadata": {
    "query": "artificial intelligence benefits",
    "total_results": 500,
    "pages_fetched": 3,
    "successful_extractions": 3,
    "total_time_ms": 28500
  }
}

🔧 工具

yandex_search（基本）

简单的搜索工具，返回标题、网址和片段。

参数：

query （字符串，必填）：搜索查询
numResults （数字，可选）：结果数量（默认值：10，最大值：50）
region （字符串，可选）：地区代码（默认：“com”）
language （字符串，可选）：语言代码（默认值：“en”）
safeSearch （布尔值，可选）：启用安全搜索（默认值：true）

yandex_search_enhanced（高级）

具有内容提取和分析功能的全功能搜索。

参数：

所有基本参数加上：
fetch_content （布尔值，可选）：获取页面内容（默认值：true）
max_pages （数字，可选）：要获取的最大页面数（默认值：3，最大值：10）
max_tokens_per_page （数字，可选）：每页令牌限制（默认值：3000）
analysis_level （枚举，可选）：“基本”|“详细”|“全面”
context_format （枚举，可选）：“原始”|“汇总”|“合成”|“qa_ready”

🏗️ 建筑

┌──────────────────────────────────────────────────────────────┐
│                    Yandex Search MCP                          │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐     ┌──────────────────────────────────┐   │
│  │ Basic Search │     │        Enhanced Pipeline         │   │
│  │              │     │                                  │   │
│  │ • Search     │     │  ┌─────────────┐  ┌──────────┐   │   │
│  │ • Snippets   │     │  │   Browser   │→ │  Search  │   │   │
│  │ • URLs       │     │  │   Manager   │  │          │   │   │
│  └──────────────┘     │  └─────────────┘  └────┬─────┘   │   │
│                       │                        │         │   │
│                       │  ┌─────────────┐  ┌────▼─────┐   │   │
│                       │  │  Content    │  │ Extract  │   │   │
│                       │  │  Extractor  │←─┤ Content  │   │   │
│                       │  └─────────────┘  └────┬─────┘   │   │
│                       │                        │         │   │
│                       │  ┌─────────────┐  ┌────▼─────┐   │   │
│                       │  │  Relevance  │  │   Cache  │   │   │
│                       │  │   Scorer    │←─┤   (LRU)  │   │   │
│                       │  └─────────────┘  └──────────┘   │   │
│                       │                        │         │   │
│                       │  ┌──────────────────┐  │         │   │
│                       │  │  LLM Context     │←─┘         │   │
│                       │  │  Formatter       │            │   │
│                       │  └──────────────────┘            │   │
│                       │                        │         │   │
│                       │  ┌──────────────────┐  │         │   │
│                       │  │  Structured      │←─┘         │   │
│                       │  │  JSON Output     │            │   │
│                       │  └──────────────────┘            │   │
│                       └──────────────────────────────────┘   │
│                                                               │
└──────────────────────────────────────────────────────────────┘

关键组件

浏览器管理器：Singleton秘密管理Playwright浏览器
内容提取器：从页面中提取有意义的内容
相关性评分器：按查询相关性对内容进行评分和排名
LLMContextFormatter：格式化输出以实现最佳LLM消耗
内容缓存：具有域特定TTL的LRU缓存

🛠️ 故障排除

检测到验证码

症状： 结果包含 error: 'CAPTCHA detected'

解决方案（按有效性排序）：

使用Yandex搜索API （推荐-100%可靠）：
```
export YANDEX_SEARCH_API_KEY="your_api_key"
export YANDEX_SEARCH_USER_ID="your_user_id"
```
看 Yandex搜索API设置在......下面
更新Cookie：从浏览器重新导出新的Cookie
使用住宅代理：数据中心IP经常被标记
启用FlareSolverr：添加 FLARESOLVERR_URL 环境变量

Yandex搜索API设置

避免CAPTCHA的最可靠方法是使用官方Yandex搜索API：

获取API凭据:
- 访问 Yandex云搜索API
- 创建服务帐户
- 使用生成API密钥 yandex.search-api.execute 范围
- 记下您的用户名

配置MCP:

{
  "mcpServers": {
    "yandex-search": {
      "command": "node",
      "args": ["/path/to/yandex-search-mcp/dist/index.js"],
      "env": {
        "YANDEX_SEARCH_API_KEY": "your_api_key_here",
        "YANDEX_SEARCH_USER_ID": "your_user_id_here"
      }
    }
  }
}

好处:
- 无验证码挑战
- 每天30000个免费请求
- 更快的响应时间
- 更可靠的结果

Cookie加载错误

症状： sameSite: expected one of (Strict|Lax|None)

解决方案： 这是由BrowserManager中的cookie规范化自动处理的。

内容未提取

症状： 页面内容为空或最少

可能的原因：

繁重的JavaScript（增加等待时间）
需要登录/付费墙
防刮擦措施

内存使用率高

解决方案：

减少 max_pages 参数
降低 max_tokens_per_page
缓存将自动删除旧条目

🤝 贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发指南

遵循TypeScript的最佳实践
为复杂逻辑添加注释
更新新功能的文档
提交前进行彻底测试

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

MCP框架 -驱动此工具的框架
剧作家 -浏览器自动化
Yandex -搜索引擎（非官方使用）

📞 支持

问题： GitHub问题
讨论： GitHub讨论

制作⚡ 为了社区，为了社区。

这是一个非官方工具。请负责任地使用并尊重Yandex的服务条款。