Tavily 联网搜索 wjh-ux/dsh-mcp-tavily

dsh-mcp-tavily

给 DeepSeek Harness（dsh）用的 Tavily 联网搜索 —— 一个插件包，分两半：让内置的 web_search 改由 Tavily 的 API 供货，并桥接 Tavily 托管的远程 MCP 服务器，用于 crawl / map / research。API Key 在插件面板的小卡片里填。不用本地服务器，不用 npx，不用构建。

Why / 为什么

DSH 内置的 web_search 由 DeepSeek 自己的端点供货：每次搜索都是一整轮辅助模型调用，按你 DeepSeek 账户的 token 计费。本插件包把这条缝改指向 Tavily，并在上面加上 Tavily 的 MCP 工具，于是日常检索花的是 Tavily 的免费月度额度（1,000/月），重活 —— crawl / map / research —— 也才用得上。

Tools added / 新增工具

| Tool | What it does / 作用 |
| web_search | 内置工具，对模型来说没变 —— 现在由 Tavily 作答。 |
| mcp__tavily__tavily_search | 联网搜索 —— 支持 include_domains、exclude_domains、time_range、search_depth: advanced |
| mcp__tavily__tavily_extract | 提取指定 URL 的可读内容（markdown / text） |
| mcp__tavily__tavily_map | 列出站点的 URL 结构 |
| mcp__tavily__tavily_crawl | 爬取整个站点并提取内容 |
| mcp__tavily__tavily_research | 多来源研究报告 |

服务器暴露资源时，还能读 MCP 资源（list_mcp_resources / read_mcp_resource）。

Install / 安装

from GitHub (recommended)
dsh plugin --profile web add github:wjh-ux/dsh-mcp-tavily

or from a local checkout
dsh plugin --profile web add link:/absolute/path/to/dsh-mcp-tavily

重启一次 dsh —— 插件包和它们的补丁在启动时解析。

Visual configuration / 可视化配置

Key 直接在 UI 里输入，不需要环境变量。

Plugins -> dsh-mcp-tavily —— 卡片就在插件包页面上，夹在描述和它的行之间。同一张表单也能从那一行的 Configure 控件进入。

| Control | Meaning |
| API Key | Tavily 的 key（tvly-...），以密钥形式写入凭据层（TAVILY_API_KEY）—— 绝不写进设置文件，也绝不写进本仓库。 |
| Show / Hide | 保存前先看一眼草稿。 |
| Save / Clear key | 存下或清除凭据。 |

状态行读的是凭据存储，所以它说的正是当前生效的是哪个来源：

| Status | Meaning |
| Tavily API key configured | 已存在凭据层 —— 卡片管着它，可以替换或清除。 |
| Supplied by the launch environment's TAVILY_API_KEY (read-only here) | key 来自启动 dsh 那个进程的环境。凭据库拒绝遮蔽它，所以保存按钮是禁用的：想让卡片接管这个 key，先删掉那个环境变量。 |
| No key on the credentials plane ... | 两个来源都没有 key；搜索走 Tavily 免费的限流无 key 模式。 |

生效时机：内置 web_search 每次请求都重新解析 key，所以卡片里保存后立即生效；MCP 工具在挂载时固定请求头，新 key 需要下次重启才对它们生效。

Key 解析顺序

1. 插件配置里显式写的 apiKey，前提是某个设置界面能提供；
2. 凭据库，按 apiKeyEnv 引用查找（默认 TAVILY_API_KEY）；
3. 进程环境，同一个引用；
4. 都没有，就走 Tavily 免费的限流无 key 模式。

两半用的是同一个函数，所以卡片也能给 MCP 工具配 key。

不用卡片配置

Windows — then fully restart dsh setx TAVILY_API_KEY "tvly-..." macOS / Linux
export TAVILY_API_KEY=tvly-...

在 <https://app.tavily.com> 领免费 key（每月 1,000 credits，不用信用卡）。什么都不配，两半也能靠 Tavily 的无 key 模式跑起来——只支持 search 和 extract（没有 crawl / map / research），限流也更低。

计费

- 免费：每月 1,000 credits；basic 搜索 = 1 credit，advanced 搜索 = 2 credits；
- 超出免费额度：每 credit $0.008（Tavily 定价，可能变动）；
- 用量面板：<https://app.tavily.com>。

兼容性

- 已在 Windows 上对照 dsh 0.2.0-rc.2 验证（@deepseek-ai/dsh-mcp-client 0.2.0-rc.2）。
- 宿主那一半依赖 MCP 客户端的 serverName / transport / url / headers 配置字段，以及 ctx.web 的搜索服务商接缝。
- 卡片需要 dsh 的客户端支持 plugins.bundle.config 槽位，并且包级有 dsh.client manifest。旧版本上宿主两半照样能跑，只是没有卡片。
- @deepseek-ai/schemastery 是可选的：没有它，服务商照样运行，只是不暴露由 schema 生成的设置表单。

安全

- 本仓库里没有密钥，补丁里也没有。 key 放在凭据库（$DSH_HOME/.credentials.yaml，或你的 dsh 挂载的存储）里，或者放在你的环境里。
- key 绝不写进 URL，否则会泄漏到日志和代理里。
- 出站流量只有一条 HTTPS 连接，指向 https://mcp.tavily.com/mcp/，外加 api.tavily.com 搜索端点；发过去的只有你的查询和本插件的 user agent（适用 Tavily 自己的条款）。
安装时不运行任何脚本，安装阶段不编译任何东西。

Implementation notes / 实现要点

这个包里有四件事，是因为 dsh 自身的模块与服务接线要求才存在的。也正因如此，这个 bundle 才是有用的参考，而不只是五个 YAML 文件。

1. 客户端那一半必须自注册。 client.js 开头就是
window.__ModuleLoader__.load({ id: "dsh-mcp-tavily", factory: (require) => { ... } })。dsh 的浏览器
侧是一张懒加载 CJS 模块表；一个只导出 factory 的文件（或者顶层写 return module.exports）在那里就是语法错误，报错会以 web boot: 1 entry did not activate 的形式出现 —— 而 Web UI 还在正常加载，很容易看错。
2. exports.inject 接收的是服务名，不是包名。 client.js 声明的是 ["slots", "locale", "remote", "remote.credentials"]。必须先加载的包列在 package.json 的 dsh.client.inject 下；把包名写进模块的 inject，会让 cordis 去找根本不存在的服务。
3. 用 link: 安装的插件，没法用普通 import() 加载 harness 包。 Node 从这个包自己的目录开始解析，而 link 安装在那里没有 @deepseek-ai/dsh-mcp-client。Cordis loader 可以，因为它按 harness 自己的模块根目录解析 —— 补丁插入的那一行正是这样按名字找到包的。所以 index.js 用的是
ctx.loader.internal.import(name, ctx.loader.baseUrl, {})。
4. credentials 服务商在插件之后才挂载。 因此在 apply 期间解析密钥会找不到服务，静默降级成无密钥，卡片里保存的密钥看起来就像「被忽略了」。index.js
用 ctx.inject(["credentials"], (child) => ...) 等待，并带一个有界回退，这样即使某个组合没有挂载任何凭据服务商，它的工具依然可用。

卡片对凭据应答做防御式解析，也是同一个原因：远程调用返回 { ok, value }，而 describe 返回一张按引用作键的映射 —— value.TAVILY_API_KEY —— 其中每一项是
{ configured, source?, writable }，永远不含密钥本身。

Manual install without the CLI / 手工安装

通过配置档的 cordis.patch.yml 添加这个 bundle；插件会自己插入一行，并挂载自己的 MCP 客户端，所以不要再为 tavily 加一行 @deepseek-ai/dsh-mcp-client —— 重复的 serverName 会被拒绝：

profile cordis.patch.yml
- id: web
config:
searchProvider: tavily
fetchProvider: http
- insert:
- id: web-search-tavily
name: dsh-mcp-tavily

web 覆盖会替换掉那一项的整个 config，所以 fetchProvider 必须重新写一遍；不写的话，第二个 fetch 服务商会让网页抓取以 WEB_PROVIDER_AMBIGUOUS 失败。

Related work / 相关工作

- @pymodel/dsh-tavily
（PyModel/dsh-research-plugins）—— 同样的底子，但机制更多：一张设置卡片、凭据平面上的密钥、DeepSeek 内置搜索与 Tavily 之间的开关、连接测试，开箱即用且无需密钥。
- dsh-plugin-web-search-tavily —— 只做一件事：把内置的 web_search 后端换成 Tavily。如果你只需要这个，那它很合适。

这个包介于两者之间：既是搜索服务商，也是 MCP 工具族，从一张卡片配置密钥，无需构建步骤，也不捆绑运行时依赖。三者注册的 serverName 相同，或者占用同一个接缝，所以只能选一个 —— 不要把两个 Tavily 服务商并排安装。

License / 许可

MIT —— 见 LICENSE。

Tavily 是第三方服务；本项目与 Tavily 或 DeepSeek 均无关联。