jev-search-mcp

Jev Search for Claude Code and Codex: a function-hook plugin that answers the built-in WebSearch with Jev, plus the same search as an MCP server, a CLI and a skill. Zero runtime dependencies

把 Jev Search 接進 Claude Code 和 Codex。裝成 Claude Code plugin 時，內建的 WebSearch 會直接由 Jev 回答，Jev 答不出來才退回內建；裝成 npm 套件時，是一個 MCP server 加 CLI，Claude Code、Codex 或任何能跑 shell 的 agent 都能用

Jev Search 的流程是：Jev 模型先讀懂你的一句話，決定要查哪些來源、哪段時間、用什麼關鍵字，再透過 Search1API 同時打 Google、DuckDuckGo、Yandex，必要時加上 Hacker News、Reddit、GitHub、X、arXiv、YouTube、Wikipedia、IMDb、WeChat，最後每一筆結果都由 Jev 打相關度分數。回來的是排好序的連結和摘要，不是生成的答案

這個 repo 同時是 npm 套件（src/）和 Claude Code plugin（hooks/、.claude-plugin/、.mcp.json、skills/），plugin 直接用套件裡的純函式，兩邊行為一致

安裝方式一：Claude Code plugin

這是給 Claude Code 使用者的建議路徑，裝完不用改任何指令或習慣，WebSearch 照常呼叫，答案換成 Jev 的

Function hooks 是 Claude Code 的 early access 功能，需要 2.1.271 以上，並且在 Claude Code 讀得到的地方開旗標，例如 ~/.claude/settings.json：

{ "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }

然後加入 muki-ai-plugins 這個 marketplace 並安裝，shell 或 session 裡的斜線指令都可以：

claude plugin marketplace add mukiwu/muki-ai-plugins
claude plugin install jev-search@muki-ai-plugins

安裝時會問三個設定：Jev Search 實例網址、要不要攔截 WebSearch、每次回幾筆，全部維持預設就是打官方的 jev.s1.dev。裝完重啟 Claude Code 或執行 /reload-plugins。不需要在 CLAUDE.md 寫任何東西，引導都由 plugin 自帶

之後你會得到：

• 模型知道 WebSearch 現在是 Jev。plugin 會在對話開頭的 context 加一小段說明，跟 CLAUDE.md 同一層：一般網路問題先用 WebSearch，幾秒回來、一次跨多站；但問的是精確數字、排名、留言數這類站台資料，而站台又有正規 API 時，模型直接打 API 仍然是更好的選擇，plugin 不會擋
• WebSearch 由 Jev 回答。模型讀到的格式跟內建一樣，多一行 Answered by Jev Search 和帶相關度百分比的排序清單。搜完通知列會跳一行 Jev Search: N results via 哪些來源 in 幾秒。Jev 回錯誤、被限流、網路不通、或網域過濾後一筆都不剩，就自動退回內建 WebSearch，對話裡會留一行暗色提示
• WebSearch 的描述多一段提醒，讓模型把查詢寫成一句話，需要時用文字點名站台或時間範圍
• 一個 jev_search MCP 工具，要明確指定 sources 或 window 時用
• 一個 jev-search skill，教模型什麼時候該用、怎麼下請求

設定之後在 /config 裡改，改完 plugin 會重新載入。hook 的細節、退回條件、網域對應表在 hooks/README.md

不想安裝、只想從 checkout 試：

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .

marketplace 那邊只是一筆指向這個 repo 的紀錄，plugin 本體就是這裡的 .claude-plugin/plugin.json、hooks/、.mcp.json 和 skills/，安裝時會 clone 整個 repo

安裝方式二：npm

給 Codex、其他 MCP host、或不想開 function hooks 的人。套件零依賴，npx 直接跑，需要 Node 22

當 MCP server

# Claude Code
claude mcp add --scope user jev-search -- npx -y jev-search-mcp

# Codex
codex mcp add jev-search -- npx -y jev-search-mcp

Codex 也可以直接寫 ~/.codex/config.toml，桌面版不一定帶著你的 shell PATH，command 建議寫絕對路徑：

[mcp_servers.jev-search]
command = "npx"
args = ["-y", "jev-search-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.jev-search.env]
JEV_SEARCH_BASE_URL = "https://jev.s1.dev"

這條路不會攔截內建搜尋，要讓模型優先用 jev_search，在全域指令加一段，Claude Code 放 ~/.claude/CLAUDE.md，Codex 放 ~/.codex/AGENTS.md：

## 網頁搜尋先走 jev_search

- 要查網路資料時，先用 jev_search，不要先用內建的 web search
- 需求用一句話寫，Jev 會自己挑來源和時間範圍，要鎖來源填 sources，要鎖時間填 window
- jev_search 回錯誤或被限流時，才退回內建 web search
- 拿到連結後要讀全文，照平常的方式抓網頁，Jev 只做搜尋不抓頁面

想徹底關掉內建搜尋：Claude Code 在 permissions.deny 加 WebSearch，Codex 在 config.toml 頂層加 web_search = "disabled"。但這樣 Jev 被限流時就沒有備援

當 CLI

npx -y jev-search-mcp search "what do Reddit users think of the Framework laptop this month"
npx -y jev-search-mcp search "new papers on speculative decoding" --window 30d --sources arxiv --max 8
npx -y jev-search-mcp search "bun 1.3 release notes" --json

只裝 skill

npx skills add mukiwu/jev-search-mcp

skills CLI 會把 skills/jev-search/SKILL.md 裝進 Claude Code、Codex、Cursor 等工具的 skill 目錄。這條路不接 MCP，模型看到 skill 之後會改用上面的 CLI 從 shell 查

運作方式

1. 請求送到 POST /api/ask，帶同源的 Origin 標頭，超過 300 字在字邊界截斷
2. 上游以 NDJSON 串流回 intent、每個引擎的 lane、最後 done，這裡收齊後照上游的規則以 URL 去重合併，同一個 URL 被多個引擎命中會合併成一列
3. 排序跟網頁版一致：Jev 的相關度百分比優先，同分看幾個引擎命中，再看原始名次，還沒被打分的排最後
4. 攔截 WebSearch 時，allowed_domains 對得上 Jev 來源就直接限制來源，對不上就寫進請求文字並在結果端過濾，blocked_domains 只在結果端過濾

它不做什麼

• 不做本機檔案搜尋，Grep、Glob 那類工具跟它無關
• 不抓網頁全文，拿到連結後還是用 WebFetch 或原本的方式讀頁面
• 不儲存查詢紀錄，所有請求直接送到你設定的 Jev Search 實例

設定

Plugin 的三個欄位：

欄位	預設	說明
baseUrl	https://jev.s1.dev	Jev Search 實例，hook 和 MCP server 共用
intercept	true	關掉就什麼都不攔、不引導，只留 jev_search 工具
maxResults	10	攔截 WebSearch 時回幾筆

MCP server 與 CLI 的環境變數：

變數	預設	說明
JEV_SEARCH_BASE_URL	https://jev.s1.dev	Jev Search 實例的網址，只取 origin
JEV_SEARCH_TIMEOUT_MS	35000	單次搜尋的逾時，伺服器端本身是 30 秒
JEV_SEARCH_MAX_RESULTS	10	沒填 max_results 時的預設筆數

jev_search 工具與 CLI 的參數：

參數	CLI	說明
query	位置參數	一句話描述要找什麼
window	--window	any、24h、7d、30d，不填讓 Jev 判斷
sources	--sources a,b	來源清單，不填讓 Jev 判斷
max_results	--max	回傳幾筆，最多 40

自架 Jev Search

官方實例 jev.s1.dev 是別人的帳單，也有每個 IP 每分鐘約 10 次的限制，量大或想穩定就自己架。照上游 README 部署到 Cloudflare Workers，需要 Search1API 的 key 和至少一個 Jev provider 的憑證，架好後把 plugin 的 baseUrl 或環境變數 JEV_SEARCH_BASE_URL 指過去即可

本機開發時上游跑在 http://localhost:3030，同樣可以直接指過去

開發

npm install                # 只裝 dev 依賴，執行時零依賴
npm test                   # node:test，含真實 stdio 協定測試與 hook 測試，不需要網路
npm run typecheck:hooks    # 用 types/claude-code.d.ts 檢查 hook
npm run validate           # claude plugin validate
npm run smoke -- "Rust async runtimes on Hacker News this month"

• src/client.js 打 POST /api/ask，串流或整段文字都能收，純函式部分給 hook 共用
• src/rank.js 從上游移植 URL 去重和排序規則
• src/format.js 把結果排成給模型讀的文字
• src/websearch-bridge.js WebSearch 輸入與 Jev 請求、Jev 結果與 WebSearch 輸出之間的轉換
• src/tool.js 工具定義、參數驗證、設定讀取，server 和 CLI 共用
• src/mcp.js 手寫的 JSON-RPC over stdio，只實作 tools 相關方法
• src/server.js MCP 進入點，src/cli.js npx 進入點
• hooks/jev.js function hook，見 hooks/README.md
• types/claude-code.d.ts Claude Code 的型別快照，用 /plugin-types 重新產生
• .claude-plugin/plugin.json plugin manifest，marketplace 紀錄在 muki-ai-plugins

授權

MIT，Jev Search 本身也是 MIT，TypeSafe 與 Jev 的名稱和商標屬於各自的持有者