dsh-web-search-free

Chinese | English — DSH plugin (dsh-plugin) · Free web search provider + settings toggle + MCP server (compatible with Claude Code / Codex)

One-click switch from "DeepSeek official pay-per-token search" to the same free search used by OpenCode (anonymous, no key required), and the same free search backend doubles as an MCP server for Claude Code, Codex, or any MCP client.

• 🆓 Free backend: Parallel (default) / Exa (fallback) — both are the same free MCP endpoints used by OpenCode's built-in websearch tool, anonymous, no API key required, no balance deducted.

• 🔄 DSH settings toggle: official ↔ free one-click switch, automatically maintains the profile patch.

• 🔌 MCP server: zero dependencies, dual transport (stdio + HTTP/SSE dual-port), ready to use with claude mcp add / codex mcp add.

Background: why DeepSeek official key by default

DSH's web_search tool uses the ctx.web capability seam. The default provider is @deepseek-ai/dsh-web-search-deepseek (id = deepseek-official, pulled in automatically by the dsh-base dependency): every search calls DeepSeek's official Anthropic-compatible API (https://api.deepseek.com/anthropic/v1/messages) with the native web_search_20250305 server-side tool, reusing DEEPSEEK_API_KEY, billed per token.

Related MCP server: Search MCP Server

Features

Free backend (within DSH)

Registers two free search providers into ctx.web; the model-side web_search tool call stays unchanged:

Settings toggle (DSH Settings → Plugin Settings → Configurable → Free Web Search)

• enabled toggle (default off = official search): on → free; off → official.

• Free backend selection: Parallel (default) / Exa (fallback), single choice.

• Changes automatically maintain the profile user-layer patch ~/.dsh/profiles/web/cordis.patch.yml's web line config.searchProvider (on → writes the selected provider id; off → removes the override block).

  Cannot write to ~/.dsh/.env: dsh-app-boot rejects any DSH_* variable in .env.

• Restart DSH after changes for them to take effect (WebRuntime reads the web line config at startup).

MCP server (Claude Code / Codex / any MCP client)

A standalone zero-dependency MCP server (lib/mcp-server.js, no DSH dependency), exposing the web_search tool (parameters: query required, provider optional parallel/exa, numResults optional). Supports dual transport: stdio (default) and HTTP/SSE (listens on a port, compatible with Streamable HTTP POST / and legacy GET /sse + POST /messages).

Transport one: stdio (default, no port needed)

# 本地路径方式（clone 后）
claude mcp add dsh-web-search -- node /绝对路径/dsh-web-search-free/lib/mcp-server.js
codex mcp add dsh-web-search -- node /绝对路径/dsh-web-search-free/lib/mcp-server.js

# 或 npm 全局安装后（npx，需先发布到 npm registry）
claude mcp add dsh-web-search -- npx -y @dsh-external/dsh-web-search-free
codex mcp add dsh-web-search -- npx -y @dsh-external/dsh-web-search-free

Transport two: HTTP/SSE (listens on a port, dual-port mode)

# 启动 MCP server（默认 http://127.0.0.1:3100；可用 --host/--port 调整）
node /绝对路径/dsh-web-search-free/lib/mcp-server.js --http --port 3100

• Claude Code (Streamable HTTP):

  claude mcp add --transport http dsh-web-search http://127.0.0.1:3100

• Codex (OpenAI Codex CLI):

  codex mcp add --transport http dsh-web-search http://127.0.0.1:3100

• Legacy SSE clients (URL points to the SSE channel):

  # 客户端配置 http://127.0.0.1:3100/sse（GET /sse 建立通道，POST /messages 发请求）

• Verification: opening http://127.0.0.1:3100/ in a browser returns {"name":"dsh-web-search-free","version":"0.3.0","transport":"http/sse","port":3100}.

Other MCP clients

Any MCP client supporting stdio or HTTP/SSE transport can connect (same command/URL as above). Optional environment variable: EXA_API_KEY (raises the Exa anonymous limit).

Installation (DSH plugin itself)

⚠️ Why don't others see the card in Settings after installing? For the settings card to show, all of the following must hold:

1. The package is declared in dsh.profile.bundles (just putting the package in node_modules is not enough);

2. Restart DSH after installation (host assembly and client graph are both resolved at startup);

3. Refresh the browser page before opening Settings;

4. The profile is web (tui/headless have no browser UI);

5. Install via local path/link:/tgz (npx @dsh-external/dsh-web-search-free requires publishing to the npm registry first; unavailable until published). After installation, you can confirm with dev_plugin_status that client ✓, or just look at Settings → Plugin Settings → Configurable.

UI effect (Settings → Plugin Settings → Configurable → Free Web Search):

Method one: local hot assembly (dsh-super-injector, no restart needed)

dev_install_package   # dir = 插件包目录（含 package.json 与 lib/）

Method two: profile declaration (takes effect after restart)

Declare in ~/.dsh/profiles/web/package.json:

{
  "dsh": { "profile": { "bundles": [
    "@deepseek-ai/dsh-base",
    "@deepseek-ai/dsh-web-app",
    // ...其他 bundle...
    "@dsh-external/dsh-web-search-free"
  ]}},
  "dependencies": {
    "@dsh-external/dsh-web-search-free": "link:/绝对路径/dsh-web-search-free"
  }
}

Method three: npm package (tgz)

npm run build && npm pack
# 把产物 tgz 加入 profile 依赖后重装（pnpm install），重启生效

Verification

npm run verify   # 补丁联动 + Parallel/Exa 真实搜索 + 选择矩阵 + MCP 冒烟

Revert to official

Turn off the enabled toggle in Settings (the override block is removed immediately), then restart DSH. (Or manually delete the block between # >>> web-search-free and # <<< web-search-free in ~/.dsh/profiles/web/cordis.patch.yml.)

Permissions (secure and transparent)

• DSH plugin: once free search is enabled, web_search requests go only to search.parallel.ai / mcp.exa.ai; it modifies ~/.dsh/profiles/web/cordis.patch.yml (a web line override with boundary markers, format as above), and touches no other config. No keys, no data collection, no listening.

• MCP server: only calls the free endpoints above, reads none of your files/environment (except the optional EXA_API_KEY). stdio mode listens on no port; HTTP/SSE mode serves the MCP endpoint only on your specified --host:--port (default 127.0.0.1:3100), bound to the loopback address by default.

Development

bash scripts/build.sh   # tsc 编译 host + core + mcp-server，复制 client 到 lib/
npm run verify          # 端到端验证

Structure:

src/core.ts           # 零依赖搜索核心：Parallel + Exa（host 与 MCP 共用）
src/index.ts          # host：双 provider 注册 + settings 开关 + profile 补丁联动
src/mcp-server.ts     # MCP server：stdio + HTTP/SSE 双传输（bin：dsh-web-search-mcp）
src/client/client.js  # client：设置面板「免费网页搜索」开关卡片（含后端选择）
scripts/build.sh      # 构建（自动探测 DSH_CHECKOUT）
scripts/verify.mjs    # 端到端验证脚本
cordis.patch.yml      # bundle 装配层（含 web 行 searchProvider 解除固定）

License

MIT © sheep-programmer