为 AI 编程工具装上
联网搜索 + AI 问答与深度研究

功能

9 个 MCP 工具

遵循 Model Context Protocol 标准，兼容所有支持 MCP 的 AI 编程工具。基础 4 个开箱即用；AI 问答增强 3 个与深度研究 1 个需在后台配置 LLM Provider 后自动启用；get_result 常驻，用于查询异步任务。

搜索 / 抓取

AI 问答增强 需配置 LLM Provider

异步任务 get_result 常驻 · web_research 需 LLM Provider

核心特性

• Streamable HTTP 传输 — 裸域名直接接入，远程访问，无需本地进程
• API Key 鉴权 — Bearer Token，每个 Key 独立计量、可启停
• SearXNG 元搜索 — 聚合 200+ 搜索源，支持按分类 / 引擎 / 时间 / 语言过滤，内置语言检测 + 来源权威性重排序
• 优先域名 — preferred_sites 参数可指定优先参考的官网 / GitHub 仓库 / 文档站，命中域名及其子域自动提权
• 智能抓取降级 — HTTP 抓取遇 403/429/WAF 挑战页/SPA 空正文时，自动降级到 stealth 无头浏览器渲染
• 多 LLM Provider — 后台可配置 OpenAI / Anthropic / Gemini 等，AI 增强工具自动启用，支持按工具切换模型
• 异步任务 — 慢工具传 defer: true 脱手执行，立即返回 taskId；web_research 深度研究流水线多轮自主调研；get_result 查进度取结果，每 Key / 全局并发后台可调（保存即生效）
• SSRF 防护 — IP 段拦截 + DNS rebinding 防护 + 重定向逐跳校验
• HTML → Markdown — 正文提取 + 噪音去除，对大模型友好
• 管理后台 — Key 管理 + LLM Provider 管理 + 任务并发设置 + 用量与 AI 成本统计 Dashboard（token / 成本按 Key 聚合）

使用方法

接入 AI 编程工具

linkseek 遵循标准 MCP Streamable HTTP 协议，配置一次即可永久生效。

一键接入：把这段话复制给你的 AI

现在的 AI 编程工具（ZCode / Claude Code / Cursor 等）都能自己完成配置。把下面这段话原样复制给它即可：它会先向你要实例地址和 API Key（不知道怎么获取也没关系，它会告诉你三条途径），然后自动完成 MCP 配置和技能安装：

请帮我接入 linkseek——自托管的联网搜索/网页抓取 MCP 服务，并安装它的配套使用技能。

第一步：确认服务信息。检查我在对话中是否已给出「实例地址 + API Key」；如果没有，停下来向我询问，并顺带告诉我获取方式（三选一）：
1. 自己部署：linkseek 开源免费，服务器或本地电脑均可（官网 https://linkseek.honlnk.com/ 有 5 分钟部署指南）
2. 借用他人部署：找已部署 linkseek 的人，请他在管理后台为你创建一对 API Key
3. 体验通道：到 github.com/honlnk/linkseek 的 Issues 联系作者申请体验用 Key（体验 Key 对应的实例地址即官网 https://linkseek.honlnk.com/）
拿到实例地址和 API Key 之前不要进行后续步骤。

第二步：添加远程 MCP 服务器。名称 linkseek，Streamable HTTP 传输，URL 为实例地址，鉴权头 Authorization: Bearer 你的Key。按你所在环境的标准方式写入：
- ZCode：~/.zcode/cli/config.json 的 mcp.servers，形如 {"type":"http","url":"...","headers":{"Authorization":"Bearer ..."}}，timeoutMs 建议 200000（web_research 深度研究全程 1-3 分钟）
- Claude Code：claude mcp add --transport http linkseek 实例地址 --header "Authorization: Bearer Key"
- Claude Desktop / Cursor / Continue 等：mcpServers 配置节，url 与 headers 同上

第三步：安装配套技能——只装 linkseek-usage 这一个，不要把技能仓库里的其他技能装进技能目录。
git clone --depth 1 https://github.com/honlnk/honlnk-skills /tmp/honlnk-skills
把 /tmp/honlnk-skills/skills/linkseek-usage 复制到你的技能目录（ZCode：~/.agents/skills/；Claude Code：~/.claude/skills/；其他 Agent：对应的技能发现目录），完成后删除 /tmp/honlnk-skills。
该技能承载「怎么用好这套工具」：工具选型、查询写法、空结果应对、异步任务用法。

全部完成后重载配置或重启会话，确认工具列表出现 linkseek 的 web_search / web_fetch 等工具即为接入成功，并向我报告结果。

1. 获取 API Key

部署后在管理后台（https://admin.你的域名/）登录，在「Key 管理」新建一个 Key。明文 Key 只显示一次，请立即保存。

2. 配置 AI 工具

在 Claude Desktop / Claude Code / Cursor / Continue 等 AI 工具的配置文件中加入：

{
  "mcpServers": {
    "linkseek": {
      "url": "https://linkseek.honlnk.com",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

3. 验证连通性

配置完成后，在 AI 工具里直接提问需要联网的问题，例如「搜索最新的 Node.js LTS 版本」。也可以用 curl 手动测试：

curl https://linkseek.honlnk.com \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0"}
    },
    "id": 1
  }'

成功的话会返回包含 "result" 的 JSON-RPC 响应。

工具参数速查

参数说明

启用 AI 问答增强（可选）

基础搜索 / 抓取工具开箱即用（get_result 同样常驻，服务于异步任务）。如果你还想让 AI 工具直接获得「搜索即问即答」与深度研究能力，只需在后台配置一个 LLM Provider：

1. 登录管理后台，进入「LLM Providers」页面。
2. 新建 Provider，选择协议（OpenAI / Anthropic / Gemini / OpenAI Responses），填入 API Key、模型名，勾选「启用」。可设其中一个为「默认」。
3. 保存后，应用会自动注册 web_search_answer、web_fetch_answer、web_research、list_models 四个工具，AI 工具即可调用。

异步任务：defer 脱手 + web_research 深度研究

耗时调用不必同步干等，两种用法：

• defer 脱手：给 web_search_and_fetch / web_search_answer / web_fetch_answer / web_fetch_render 传 defer: true，调用毫秒级返回 taskId，AI 可以先去做别的事。
• web_research 深度研究：提交一个中等复杂度的问题（如「对比两个框架的取舍」），服务端自主完成「改写 → 多轮搜索 → 筛选 → 蒸馏 → 综合」全流程，standard 档约 1-3 分钟，适合让 AI 脱手调研。

之后用 get_result 查询（建议间隔 15-30 秒，不要连续刷）：排队 / 执行中会返回当前阶段进度（如「抓取中 2/5」「浏览器渲染中」），完成后返回与同步版格式一致的结果。

公开 REST API

不走 MCP 的直接调用（/v1）

为浏览器端应用（如 NovAI）准备的薄 REST 适配层，复用同一套搜索与抓取核心。只暴露搜索和抓取，AI 问答工具不在此开放。

两种鉴权方式

• API Key：Authorization: Bearer <key>，不限日配额，用量记后台 UsageLog；CORS 对所有 Origin 放行——浏览器应用（如 NovAI「linkseek 直连」档）从任意站点地址均可直连，填服务地址 + Key 即用。
• 匿名绿灯：无 Key，要求浏览器 Origin 命中服务端白名单（PUBLIC_API_ALLOWED_ORIGINS，仅服务方为授权站点开启），按配额放行。配额键优先取 X-NovAI-Client-Id 请求头（NovAI 前端自动携带），缺失时按 IP。

版本要求：直连需实例版本含 /v1 公开端点（2026-09-24 07bba8f 及之后）。

限流与配额规则

按服务器本地日期重置。超限返回 429 QUOTA_EXCEEDED / 429 RATE_LIMITED，错误体为 { "error": { "code", "message" } }。

错误码速查

curl 示例

# API Key 方式
curl https://linkseek.honlnk.com/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Node.js LTS 版本", "maxResults": 5}'

# 匿名绿灯（浏览器场景；curl 模拟需自带白名单内的 Origin）
curl https://linkseek.honlnk.com/v1/fetch \
  -H "Content-Type: application/json" \
  -H "Origin: https://novai.example.com" \
  -H "X-NovAI-Client-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"url": "https://example.com", "render": "auto"}'

自部署

5 分钟自部署 linkseek

基于 Docker Compose，一台带 Docker 的 Linux 服务器即可。完整的部署脚本和配置已在 GitHub 仓库。

前置要求

• 一台 Linux 服务器（推荐 2C2G 起，Browserless 比较吃内存）
• 已安装 Docker 和 Docker Compose
• 一个解析到服务器的域名（例如 linkseek.example.com）
• 服务器 80/443 端口可用（用于申请证书）

部署步骤

1. 克隆仓库

   git clone https://github.com/honlnk/linkseek.git
   cd linkseek

2. 配置 DNS

   在你的域名服务商添加两条 A 记录，指向你的服务器 IP：

   记录类型	主机记录	记录值
   A	linkseek	你的服务器 IP
   A	admin.linkseek	你的服务器 IP

   验证：dig +short linkseek.example.com 应返回服务器 IP。

3. 申请 SSL 证书

   使用 certbot 为两个域名申请一张证书：

   sudo certbot certonly --standalone \
     -d linkseek.example.com \
     -d admin.linkseek.example.com

   证书续期由 certbot 自带的 systemd timer 自动处理。若要无感续期，需配置 --deploy-hook 在续期后重载 Nginx。

4. 配置环境变量

   从模板复制并填入你的密钥：

   cp .env.production.example .env.production

   编辑 .env.production，替换所有 __XXX__ 占位符：

   # 生成强随机值
   openssl rand -hex 32    # MYSQL_ROOT_PASSWORD
   openssl rand -hex 16    # MYSQL_PASSWORD（DATABASE_URL 里要一致）
   openssl rand -hex 32    # SESSION_SECRET
   
   # 自定义值
   ADMIN_PASSWORD=你的强密码

   关键：DATABASE_URL 里的密码必须与 MYSQL_PASSWORD 完全一致。

5. 放置 Nginx 网关配置

   仓库提供了双层网关的示例配置（deploy/nginx/），按需修改域名和证书路径后部署。

   如果你已有反向代理（如 Caddy、Nginx Proxy Manager），直接把 linkseek.example.com 和 admin.linkseek.example.com 都反代到 linkseek-app:7300 即可——应用层会自动按 Host 分流。

6. 启动服务

   docker compose -f docker-compose.prod.yml up -d
   
   # 查看启动状态
   docker compose -f docker-compose.prod.yml ps
   
   # 查看 app 日志（应看到迁移成功 + 管理员账号就绪）
   docker logs linkseek-app

   数据库迁移和管理员初始化在容器启动时自动执行（幂等），无需手动跑 seed。

7. 验证

   # 文档页应返回 HTML
   curl https://linkseek.example.com/
   
   # 健康检查
   curl https://linkseek.example.com/health
   # {"status":"ok"}
   
   # MCP 握手（先在后台建 Key）
   curl https://linkseek.example.com \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

   浏览器打开 https://admin.linkseek.example.com/，用 ADMIN_PASSWORD 登录后台，新建 Key 后即可接入 AI 工具。

日常维护

# 更新到最新版本
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

# 查看日志
docker compose -f docker-compose.prod.yml logs -f app

# 数据库备份
docker exec linkseek-mysql mysqldump -u linkseek -pPASSWORD linkseek > backup.sql

# 停止（保留数据）
docker compose -f docker-compose.prod.yml down