dsh-web-search-free

한국어 | English — DSH 플러그인(dsh-plugin) · 무료 웹 검색 provider + 설정 스위치 + MCP server(Claude Code / Codex 호환)

「DeepSeek 공식 종량제 검색」을 원클릭으로 OpenCode 동일 무료 검색(익명, key 불필요)으로 전환하고, 동일한 무료 검색 백엔드를 그대로 MCP 서버로 사용하여 Claude Code, Codex 등 모든 MCP 클라이언트에서 사용할 수 있습니다.

• 🆓 무료 백엔드: Parallel(기본) / Exa(예비) — 모두 OpenCode 내장 websearch 도구와 동일한 무료 MCP 엔드포인트로, 익명 사용 가능, API key 불필요, 잔액 차감 없음.

• 🔄 DSH 설정 스위치: 공식 ↔ 무료 원클릭 전환, profile 패치 자동 유지.

• 🔌 MCP server: 제로 의존성, 이중 전송(stdio + HTTP/SSE 이중 포트), claude mcp add / codex mcp add로 설치 즉시 사용 가능.

배경: 왜 기본적으로 DeepSeek 공식 key를 사용하는가

DSH의 web_search 도구는 ctx.web 능력 seam을 사용합니다. 기본으로 장착된 provider는 @deepseek-ai/dsh-web-search-deepseek(id = deepseek-official, dsh-base 의존성에 의해 자동 포함)입니다. 검색할 때마다 DeepSeek 공식 Anthropic 호환 API (https://api.deepseek.com/anthropic/v1/messages)의 네이티브 web_search_20250305 서버 도구를 호출하며, DEEPSEEK_API_KEY를 재사용하고 token 기준으로 과금됩니다.

Related MCP server: Search MCP Server

기능

무료 백엔드(DSH 내)

ctx.web에 두 개의 무료 검색 provider를 등록하며, 모델 측 web_search 도구 호출 방식은 변경되지 않습니다:

설정 스위치(DSH 설정 → 플러그인 설정 → 구성 가능 → 무료 웹 검색)

• enabled 스위치(기본 꺼짐 = 공식 검색): 켜기 → 무료; 끄기 → 공식.

• 무료 백엔드 선택: Parallel(기본) / Exa(예비), 단일 선택.

• 변경 시 profile 사용자 계층 패치 ~/.dsh/profiles/web/cordis.patch.yml의 web 행 config.searchProvider를 자동 유지(켜기 → 선택한 provider id 기록; 끄기 → 덮어쓰기 블록 삭제).

  ~/.dsh/.env에는 쓸 수 없음: dsh-app-boot가 .env의 모든 DSH_* 변수를 거부함.

• 변경 후 DSH 재시작 시 적용(WebRuntime 시작 시 web 행 구성을 읽음).

MCP server(Claude Code / Codex / 모든 MCP 클라이언트)

독립적인 제로 의존성 MCP server(lib/mcp-server.js, DSH에 의존하지 않음)로, web_search 도구를 노출합니다(매개변수: query 필수, provider 선택 parallel/exa, numResults 선택). 이중 전송을 지원합니다: stdio(기본) 및 HTTP/SSE(포트 리슨, Streamable HTTP POST / 및 구식 GET /sse + POST /messages 호환).

전송 1: stdio(기본, 포트 불필요)

# 本地路径方式（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

전송 2: HTTP/SSE(포트 리슨, 이중 포트 모드)

# 启动 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

• 구식 SSE 클라이언트(URL이 SSE 채널을 가리킴):

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

• 검증: 브라우저에서 http://127.0.0.1:3100/을 열면 {"name":"dsh-web-search-free","version":"0.3.0","transport":"http/sse","port":3100} 반환.

기타 MCP 클라이언트

stdio 또는 HTTP/SSE 전송을 지원하는 모든 MCP 클라이언트가 연결할 수 있습니다(명령/URL은 위와 동일). 선택 환경 변수: EXA_API_KEY(Exa 익명 한도 상향).

설치(DSH 플러그인 본체)

⚠️ 왜 다른 사람은 설치해도 설정에 카드가 안 보일까? 설정 카드가 표시되려면 다음 조건을 모두 충족해야 합니다:

1. 패키지가 dsh.profile.bundles에 선언되어야 함(node_modules에 패키지를 넣는 것만으로는 부족);

2. 설치 후 DSH 재시작(host 어셈블리와 client 그래프 모두 시작 시 해석됨);

3. 설정을 열기 전에 브라우저 페이지 새로고침;

4. profile이 web이어야 함(tui/headless는 브라우저 UI 없음);

5. 로컬 경로/link:/tgz로 설치(npx @dsh-external/dsh-web-search-free는 npm registry에 먼저 게시되어야 하며, 게시 전에는 사용 불가). 설치 후 dev_plugin_status로 client ✓를 확인하거나, 설정 → 플러그인 설정 → 구성 가능에서 직접 확인.

화면 효과(설정 → 플러그인 설정 → 구성 가능 → 무료 웹 검색):

방법 1: 로컬 핫 어셈블리(dsh-super-injector, 재시작 불필요)

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

방법 2: profile 선언(재시작 시 적용)

~/.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"
  }
}

방법 3: npm 패키지(tgz)

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

검증

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

공식으로 롤백

설정에서 enabled 스위치를 끄면(덮어쓰기 블록이 즉시 삭제됨), DSH를 재시작합니다. (~/.dsh/profiles/web/cordis.patch.yml에서 # >>> web-search-free와 # <<< web-search-free 사이의 블록을 수동으로 삭제.)

권한 설명(안전·투명)

• DSH 플러그인: 무료를 활성화하면 web_search 요청은 search.parallel.ai / mcp.exa.ai로만 전송됩니다. ~/.dsh/profiles/web/cordis.patch.yml을 수정하며(경계 마커가 있는 web 행 덮어쓰기, 형식은 위 참조), 다른 구성은 건드리지 않습니다. key 없음, 데이터 수집 없음, 리슨 없음.

• MCP server: 위 무료 엔드포인트만 호출하며, 사용자의 어떤 파일/환경도 읽지 않습니다(선택적 EXA_API_KEY 제외). stdio 모드는 어떤 포트도 리슨하지 않습니다. HTTP/SSE 모드는 사용자가 지정한 --host:--port(기본 127.0.0.1:3100)에서만 MCP 엔드포인트를 제공하며, 기본적으로 로컬 루프백 주소에만 바인딩합니다.

개발

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

구조:

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