AI Model Web Source Manager

一个可被大模型调用的联网检索组件，支持 JS 渲染页面抓取、正文抽取、索引与检索，并提供 REST API 与 MCP 工具接口，附带现代化桌面管理界面。

功能特性

• 双重抓取策略: HTTP 静态抓取 + Playwright JS 渲染
• 智能正文抽取: trafilatura 优先，失败回退到 HTML 解析
• 倒排索引搜索: TF-IDF 相关性排序
• 站点路由: 根据查询词智能选择目标站点
• 热加载配置: 修改 sites.json 无需重启服务
• 多协议支持: REST API + MCP (Model Context Protocol)
• 桌面管理界面: Electron + React 现代化 UI
• Claude Desktop 集成: 可作为 MCP 工具被 Claude 调用

项目架构

SearchEngine/
├── Design/                    # 前端应用 (Electron + React)
│   ├── src/
│   │   ├── app/
│   │   │   ├── App.tsx       # 主应用组件
│   │   │   ├── components/   # UI 组件
│   │   │   ├── hooks/        # React Hooks
│   │   │   └── services/     # API 服务
│   │   └── styles/           # 样式文件
│   ├── electron/
│   │   ├── main.js           # Electron 主进程
│   │   └── preload.cjs       # 预加载脚本
│   └── package.json
├── data/                      # 数据目录
│   ├── index/                # 倒排索引
│   └── cache/                # 文档缓存
├── main.py                   # 后端入口
├── api_server.py             # REST API 服务器
├── mcp_server.py             # MCP 服务器
├── search_engine.py          # 搜索引擎核心
├── focused_crawler.py        # 站内定向抓取器
├── content_extractor.py      # 正文抽取
├── indexer.py                # 倒排索引构建
├── searcher.py               # 搜索模块
├── ranker.py                 # TF-IDF 排序
├── sites.json                # 站点配置
└── README.md

快速开始

环境要求

• Python 3.10+
• Node.js 18+
• pnpm (推荐) 或 npm

1. 安装 Python 依赖

# 创建虚拟环境 (推荐)
conda create -n SearchEngine python=3.10
conda activate SearchEngine

# 安装依赖
pip install playwright trafilatura lxml beautifulsoup4

# 安装 Playwright 浏览器
playwright install chromium

2. 安装前端依赖

cd Design
pnpm install

3. 启动服务

方式一：启动后端 API 服务器

python main.py

服务将在 http://localhost:8000 启动。

方式二：启动桌面应用

cd Design
pnpm dev        # 前端开发服务器
pnpm electron   # Electron 开发模式

方式三：配置 MCP 服务 (Claude Desktop)

在 Claude Desktop 配置文件中添加：

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "search-engine": {
      "command": "python",
      "args": ["E:/SearchEngine/mcp_server.py"],
      "env": {}
    }
  }
}

桌面应用使用指南

主界面功能

桌面应用提供直观的站点管理界面：

按钮	颜色	功能
Live Search	绿色	启动定向检索模式（联网抓取+检索）
Local Search	蓝色	切换到本地索引搜索模式
Start MCP	红色	启动后端服务
Stop MCP	绿色	停止后端服务
Add New	灰色	添加新站点
检索日志	-	查看历史搜索记录

添加站点

1. 点击 Add New 按钮
2. 填写站点信息：
   • 域名: 如 github.com
   • 种子 URL: 抓取起始页面 URL
   • 别名: 站点的其他名称（用于搜索匹配）
3. 点击保存

站点状态

• Active (绿色): 站点已启用，会被包含在搜索范围内
• Disabled (灰色): 站点已禁用，不会被搜索

API 接口文档

REST API

服务地址: http://localhost:8000

方法	路径	功能	参数
GET	/search	本地索引搜索	q, limit, op
GET	/websearch	定向抓取+检索	q, sites, pages, depth, limit
POST	/index	索引单个 URL	url
POST	/crawl	基于站点线索抓取	q, pages, depth
GET	/status	服务状态	-
GET	/sites	获取站点列表	-
POST	/sites	添加站点	domain, seeds, aliases
PUT	/sites	更新站点	domain, seeds, aliases, status
DELETE	/sites	删除站点	domain

示例请求

WebSearch (定向抓取+检索):

curl "http://localhost:8000/websearch?q=钉钉消息类型&sites=dingtalk.apifox.cn&pages=20&depth=2"

本地搜索:

curl "http://localhost:8000/search?q=API文档&limit=10"

添加站点:

curl -X POST "http://localhost:8000/sites" \
  -H "Content-Type: application/json" \
  -d '{"domain":"developer.mozilla.org","seeds":["https://developer.mozilla.org/"],"aliases":["mdn","mozilla"]}'

响应格式

{
  "query": "关键词",
  "total": 10,
  "results": [
    {
      "url": "https://example.com/page",
      "title": "页面标题",
      "snippet": "内容摘要...",
      "score": 0.85
    }
  ]
}

MCP 工具

当配置为 MCP 服务后，Claude 可调用以下工具：

web_search

WebSearch：可选指定站点，定向抓取并检索返回。

参数:

• query (string, required): 搜索关键词
• tokens (array, optional): 模型已分词 tokens
• limit (number, optional): 返回结果数量，默认 10
• sites (array, optional): 限制站点域名列表
• pages (number, optional): 每个站点最多抓取页面数，默认 20
• depth (number, optional): 站内抓取最大深度，默认 2

index_url

索引指定 URL 的网页内容。

参数:

• url (string, required): 要索引的网页 URL

站点配置

站点配置存储在 sites.json 文件中，支持热加载：

{
  "sites": [
    {
      "domain": "dingtalk.apifox.cn",
      "seeds": ["https://dingtalk.apifox.cn/"],
      "aliases": ["apifox", "钉钉", "dingtalk"],
      "status": "Active",
      "lastSynced": "2026-01-24 02:31 PM"
    }
  ]
}

字段说明:

• domain: 站点域名（唯一标识）
• seeds: 种子 URL 列表，抓取起始点
• aliases: 站点别名，用于查询路由匹配
• status: 状态 (Active / Disabled)
• lastSynced: 最后同步时间

大模型对接

方式一：REST API 调用

import urllib.request
import json

def search(query, limit=10):
    url = f"http://localhost:8000/search?q={urllib.parse.quote(query)}&limit={limit}"
    with urllib.request.urlopen(url) as response:
        return json.loads(response.read())

results = search("Python编程")

方式二：直接导入 Python 模块

from search_engine import SearchEngine

engine = SearchEngine()
results = engine.web_search(
    "查询关键词",
    sites=["dingtalk.apifox.cn"],
    pages=20,
    depth=2,
    limit=10
)

方式三：MCP 工具调用

配置 Claude Desktop 后，AI 可直接调用 web_search 和 index_url 工具。

构建与打包

开发模式

cd Design
pnpm dev          # 前端开发服务器
pnpm electron     # Electron 开发模式

生产构建

cd Design
pnpm build        # 构建前端
pnpm dist         # 打包 Electron 应用

打包后的安装程序将输出到 Design/release/ 目录。

技术栈

后端

• Python 3.10+
• Playwright - 浏览器自动化，处理 JS 渲染
• trafilatura - 网页正文抽取
• lxml / BeautifulSoup4 - HTML 解析

前端

• React 18 - UI 框架
• TypeScript - 类型系统
• Vite - 构建工具
• Electron 31 - 桌面应用框架
• Tailwind CSS - CSS 工具类
• Radix UI - 无样式组件库
• Lucide Icons - 图标库

工作原理

抓取流程

查询词 → 站点路由 → 选择目标站点 → 定向抓取
                                    ↓
                         HTTP 抓取 / Playwright 渲染
                                    ↓
                              正文抽取
                                    ↓
                              构建索引

检索流程

查询词 → 分词 → 查询倒排索引 → TF-IDF 排序 → 返回结果

常见问题

Q: 如何处理 JS 渲染的页面？

项目使用 Playwright + Chromium 进行浏览器渲染抓取，可以处理 SPA 等需要 JavaScript 执行的页面。

Q: 抓取速度慢？

1. 减少 pages 参数（每站点抓取页数）
2. 减少 depth 参数（抓取深度）
3. 优先使用 HTTP 静态抓取（速度更快）

Q: MCP 服务无法连接？

1. 确保 Python 环境正确配置
2. 检查 claude_desktop_config.json 中的路径是否正确
3. 重启 Claude Desktop

贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

许可证

MIT License

---

Made with Claude Code