visitproject

一个无头的 agentic 网络搜索服务，通过 MCP（Model Context Protocol） 把深度 web 搜索能力暴露给 AI agent。

普通的 web search 工具只是把链接丢给 agent。visitproject 多做了一系列让搜索结果真正可用的事：

1. 聚合召回——基于 SearXNG 元搜索，一次查遍 Google / Bing / DuckDuckGo 等 70+ 引擎
2. 去重 + 重排——用 embedding 算相似度，过滤掉与问题无关的、去掉重复的，按相关性排序；embedding 不可用时自动降级到 URL 规范化 + 标题 Jaccard 去重
3. 正文提取——deep 模式用无头浏览器抓取 + Readability 提取正文，再让 LLM 抽取关键事实
4. 真实的 relevance score——quick 模式用 embedding 相似度，deep 模式用 LLM picker 打分（不是编造的递减序列）
5. 成本护栏——deep 模式有 LLM 调用次数、抓取 URL 数的硬上限，防止研究循环跑飞烧钱
6. 结果缓存——LRU + TTL，重复相似 query 省下 50%+ 成本
7. 多引擎 fallback——SearXNG 不可用时自动退到 DuckDuckGo / Tavily
8. 流式中间结果——deep 模式每轮通过 MCP progress notification 推送当前进度

最终 agent 拿到的是干净的结构化结果（标题 + URL + 正文 + 分数），而不是一堆要自己点开的链接。

架构

┌─────────────────────────────────────────────────────┐
│  MCP 客户端（MadCop / ZCode / Claude Desktop / ...） │
└───────────────────────┬─────────────────────────────┘
                        │ stdio (MCP 协议)
                        ▼
┌─────────────────────────────────────────────────────┐
│  visitproject (Node 进程)                            │
│                                                      │
│  search 工具 ──┬─ quick: 召回 → embedding 重排       │
│                └─ deep : agentic 多轮研究循环        │
│                          │                           │
│                          ▼                           │
│  scrape 工具 ── Playwright + Readability 正文提取    │
└───────────────────────┬─────────────────────────────┘
                        │ HTTP
                        ▼
┌─────────────────────────────────────────────────────┐
│  SearXNG (Docker 容器) —— 元搜索引擎                 │
└─────────────────────────────────────────────────────┘

两个工具

search 支持 source 参数：web（通用）/ academic（arxiv/scholar/pubmed）/ discussions（reddit）。

快速开始

1. 启动 SearXNG

需要 Docker（macOS 推荐 Colima）：

docker-compose up -d
# 验证：应返回 JSON 结果
curl 'http://localhost:8080/search?format=json&q=hello+world' | head -c 200

2. 安装依赖并构建

npm install
npm run build

# 安装 Playwright 浏览器（deep 模式抓正文用）
npx playwright install chromium

3. 配置

cp .env.example .env
# 编辑 .env，填入 LLM_API_KEY 等

visitproject 需要两类模型：

• Chat 模型：deep 模式的 researcher 循环、结果筛选、事实抽取
• Embedding 模型：quick 模式的去重与重排

两者都支持 OpenAI 兼容协议（OpenAI / DeepSeek / 智谱 / NVIDIA NIM / 通义等），也支持本地 Ollama。详见 .env.example。

4. 本地测试

npm start
# server 启动后会通过 stdio 等待 MCP 客户端连接

接入 MadCop

visitproject 主要场景是给 MadCop 的 agent 提供网络搜索。在 MadCop 的 MCP 配置（~/.madcop/mcp_servers.json 或设置界面）中添加：

{
  "name": "visitproject",
  "command": "node",
  "args": ["/absolute/path/to/visitproject/dist/index.js"],
  "enabled": true,
  "env": {
    "SEARXNG_URL": "http://localhost:8080",
    "LLM_PROVIDER": "openai",
    "LLM_BASE_URL": "https://api.openai.com/v1",
    "LLM_API_KEY": "sk-...",
    "LLM_MODEL": "gpt-4o-mini",
    "EMBEDDING_MODEL": "text-embedding-3-small"
  }
}

挂载后，MadCop 的所有 agent（standard 模式 / deep 模式的 researcher 等）即可调用 search 和 scrape 工具。

接入其他 MCP 客户端

任何支持 stdio MCP 的客户端都能用，配置方式类似。例如 Claude Desktop 在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "visitproject": {
      "command": "node",
      "args": ["/absolute/path/to/visitproject/dist/index.js"],
      "env": { "SEARXNG_URL": "http://localhost:8080", "...": "..." }
    }
  }
}

深度 vs 快速

默认 deep，可在 .env 用 VISIT_DEPTH=quick 改默认值，或每次调用时用 depth 参数覆盖。

项目结构

visitproject/
├── src/
│   ├── index.ts              # MCP server 入口（stdio 传输）
│   ├── server.ts             # 注册 search / scrape 工具
│   ├── config.ts             # 环境变量配置
│   ├── types.ts              # 共享类型
│   ├── core/
│   │   ├── searxng.ts        # SearXNG HTTP 客户端
│   │   ├── scraper.ts        # Playwright + Readability 正文提取
│   │   ├── pipeline.ts       # 搜索管线：召回→去重→重排 / 召回→选→抓→抽
│   │   └── researcher.ts     # agentic 多轮研究循环
│   ├── models/
│   │   ├── base/             # LLM / Embedding 抽象
│   │   ├── providers/        # OpenAI / Ollama 实现
│   │   └── factory.ts        # 按 provider 构造实例
│   ├── prompts/researcher.ts # researcher / picker / extractor 提示词
│   └── utils/                # 相似度计算 / 文本分块
├── searxng/settings.yml      # SearXNG 配置
├── docker-compose.yml        # SearXNG 容器
└── .env.example              # 配置模板

开发

npm run dev      # watch 模式编译
npm run typecheck
npm test         # 跑测试（29 个，覆盖 similarity/chunker/dedup/cache）

全部配置项

垂直自建索引（v0.4.0）

除了借 SearXNG 搜全网，visitproject 还能自建垂直索引——你指定几个网站，它爬取建本地索引，搜索时先查本地索引，命中够多就不再依赖 Google/Bing。数据你掌控，可定制，零外部依赖。

建索引

# 1. 编辑数据源配置（编辑 data/sources.json，加你想索引的网站）
# 2. 爬取 + 建索引
npm run index
# 或指定自定义配置
node dist/cli.js index --sources ./my-sources.json

数据源配置 data/sources.json：

[
  {
    "name": "nodejs-docs",
    "url": "https://nodejs.org/api/",
    "maxDepth": 1,
    "maxPages": 50
  }
]

工作原理

search(query)
  ├─ 1. 查本地 MiniSearch 索引（自建，CJK 分词，毫秒级）
  │     命中 ≥ indexMinHits → 直接返回，跳过 SearXNG
  ├─ 2. 命中不足 → searchWithFallback（SearXNG → DDG → Tavily）
  └─ 合并去重

爬虫：BFS 同域遍历，礼貌限速（每页 500ms 间隔），限并发（3），用 Playwright + Readability 提正文。CJK tokenizer 让中文 query 能单字召回。

License

MIT