{"_id":"j-can-search","_rev":"2-c2ab09be5cb6d0db01b69376c3e28c48","name":"j-can-search","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.0-stage":{"name":"j-can-search","version":"0.0.0-stage","_id":"j-can-search@0.0.0-stage","stub":true,"maintainers":[{"name":"jirachi","email":"jinyonghui1994@gmail.com"}],"dist":{"shasum":"ee0b3bc7f7276403fdb94efbce09584e57c623bd","tarball":"https://registry.npmjs.org/j-can-search/-/j-can-search-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-a0tMjhEePwUHLS8wSV1V36VseeaRA8K8LsDunD2heaeKYxlWEDE90WPdhAUIozrAROdUnzRgx63smp/O2VIcmw==","signatures":[{"sig":"MEUCIFyRNhKFVlHF7FeE7UpCDO83LAaxsKPEYArSfcZTpX0qAiEA2VFv5WapiMxtQP3V6IWE92OAC4lD8wmLr4woDERJoSo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":334},"_npmUser":{"name":"jirachi","email":"jinyonghui1994@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.0":{"_id":"j-can-search@0.1.0","bin":{"j-can-search":"dist/index.js"},"bugs":{"url":"https://github.com/PichurChill/j-ai-kit/issues"},"dist":{"shasum":"45878d907ba052fffd4a718a00e1f01c6f8f708b","tarball":"https://registry.npmjs.org/j-can-search/-/j-can-search-0.1.0.tgz","fileCount":17,"integrity":"sha512-7JuJo5olzaaobr6gopRdVOxwBRgZaoImy9J2AhGYvPna2aFc+pmjXTvFzESKXKPiRk4Lk6VCi98aovM1914vzw==","signatures":[{"sig":"MEQCIB8rfRQMv9Yum+3h5I8Zm+5zA+aKvZgu6S2CPv3lchFkAiAa8rgIV9J2cnLvmTCiv9EfrB1aEKLi3TM0W4chxTWYSQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICJ/hJYPGAk4Gxjs+6GJmAwLYASd/fxG28jAQNiPwUaQAiEAqpvKTcXL8ZdMy5vQkZXyChLGTfehzd7UdsKbGBQiork="}],"unpackedSize":67951},"main":"dist/index.js","name":"j-can-search","type":"module","engines":{"node":">=20"},"gitHead":"e8a90db2c93bb302a6a1daa3cbf0a646e4896c21","license":"MIT","scripts":{"dev":"tsc --watch","test":"npm run typecheck && vitest run","build":"tsc","typecheck":"tsc --noEmit -p tsconfig.test.json","test:watch":"vitest","prepublishOnly":"npm run build && npm run typecheck","publish:official":"npm publish --registry=https://registry.npmjs.org/"},"version":"0.1.0","_npmUser":{"name":"jirachi","email":"jinyonghui1994@gmail.com"},"homepage":"https://github.com/PichurChill/j-ai-kit/tree/main/packages/j-can-search#readme","keywords":["mcp","model-context-protocol","web-search","search","grounding","gemini","grok","openai","citation-verification","claude-code","codex"],"repository":{"url":"git+https://github.com/PichurChill/j-ai-kit.git","type":"git","directory":"packages/j-can-search"},"_npmVersion":"10.9.8","description":"MCP server that gives search-less AI agents a verified web search tool: drives a search-capable model (Gemini grounding / xAI web search / OpenAI Responses web_search / any OpenAI-compatible gateway) and verifies every cited URL before returning — fabrica","directories":{},"maintainers":[{"name":"jirachi","email":"jinyonghui1994@gmail.com"}],"_nodeVersion":"22.22.3","dependencies":{"zod":"^4.4.3","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/j-can-search_0.1.0_1791868768385_0.8548071201494305"}}},"time":{"created":"2026-10-13T05:17:21.095Z","modified":"2026-10-13T05:19:28.707Z","0.0.0-stage":"2026-10-13T05:17:21.095Z","0.1.0":"2026-10-13T05:19:28.489Z"},"description":"MCP server that gives search-less AI agents a verified web search tool: drives a search-capable model (Gemini grounding / xAI web search / OpenAI Responses web_search / any OpenAI-compatible gateway) and verifies every cited URL before returning — fabrica","maintainers":[{"name":"jirachi","email":"jinyonghui1994@gmail.com"}],"readme":"# j-can-search\n\n给没有搜索能力的 AI agent 补一个**带引用校验**的联网搜索 MCP server。\n\n工作方式：驱动一个具备服务端搜索能力的模型（Gemini grounding / xAI web search / OpenAI Responses `web_search` / 任意 OpenAI 兼容网关）执行真实网页搜索，返回前**对每条引用 URL 做实测 GET 校验** —— 拼造的 404 链接被剔除并显式计数警告，页面 `<title>` 与所称标题不符的标记「疑似挪用旧文」。\n\n解决的两个真实痛点：\n\n1. agent 的原生搜索额度耗尽（订阅套餐的搜索调用窗口用完）；\n2. 更隐蔽的：网关剥掉了搜索工具参数，模型**静默凭训练记忆作答**、按站点 URL 规律编造\"看起来合理\"的链接。\n\n模型改不了，但它的引用可以机器验证 —— 这是本包的核心增值。\n\n## 安装与配置\n\n```json\n{\n  \"mcpServers\": {\n    \"j-can-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"j-can-search\"],\n      \"env\": {\n        \"J_SEARCH_BASE_URL\": \"https://your-gateway.example.com\",\n        \"J_SEARCH_API_KEY\": \"sk-...\",\n        \"J_SEARCH_MODEL\": \"your-search-capable-model\",\n        \"J_SEARCH_API_SPEC\": \"openai-google-search\"\n      }\n    }\n  }\n}\n```\n\n必填：`J_SEARCH_BASE_URL`、`J_SEARCH_API_KEY`、`J_SEARCH_MODEL`、`J_SEARCH_API_SPEC`（必选、无默认 —— 选错 spec 会静默不搜）。\n可选（括号为默认值）：`J_SEARCH_TIMEOUT_MS(90000)`、`J_SEARCH_MAX_ATTEMPTS(2)`、`J_SEARCH_MAX_SOURCES(8)`、`J_SEARCH_VERIFY(on)`、`J_SEARCH_VERIFY_TIMEOUT_MS(8000)`、`J_SEARCH_VERIFY_CONCURRENCY(4)`。\n\n### 我该选哪个 spec？——按你手里有什么查\n\n大多数人不需要理解 spec 的含义，按入口查表即可：\n\n| 你手里的 key / 端点 | 选这个 spec |\n| --- | --- |\n| OpenAI 官方 key（`api.openai.com`） | `responses-web-search` |\n| xAI 官方 key（`api.x.ai`） | `responses-web-search` |\n| Anthropic 官方 key | `anthropic-web-search` |\n| Google AI Studio key | `gemini-native` |\n| OpenRouter | `openai-web-search`（模型自带联网如 sonar 系则用 `openai-inherent`） |\n| Perplexity key | `openai-inherent` |\n| newapi / one-api / 自建反代，后端是 Gemini | `openai-google-search` |\n| 其他反代/网关，**不确定后端透传什么** | 按上表逐个试 + `--check` 验证（见下） |\n\n网关用户的不确定性无法靠文档消除（反代是否透传搜索工具只有试了才知道）——逐档试一遍，第一个 PASS 就是答案：\n\n```bash\nfor spec in responses-web-search anthropic-web-search gemini-native openai-web-search openai-inherent openai-google-search; do\n  echo \"== $spec\"; J_SEARCH_BASE_URL=... J_SEARCH_API_KEY=... J_SEARCH_MODEL=... \\\n    J_SEARCH_API_SPEC=$spec npx j-can-search --check && break\ndone\n```\n\n### `J_SEARCH_API_SPEC` 参考表（按通用程度排序：官方标准 → 网关约定 → 反代翻译的特殊约定）\n\n服务端搜索没有统一标准 —— `tools` 形状写错就是静默不搜（模型凭记忆作答，比报错更危险）：\n\n| spec | 端点形态 | 搜索激活方式 |\n| --- | --- | --- |\n| `responses-web-search` | `/v1/responses` | `tools:[{\"type\":\"web_search\"}]`（OpenAI / xAI 官方文档一致的 hosted web_search） |\n| `anthropic-web-search` | Anthropic `/v1/messages` | `tools:[{\"type\":\"web_search_20250305\",\"name\":\"web_search\"}]` + `x-api-key`/`anthropic-version` 头（官方 $10/千次搜索；已过官方端点协议级验证，端到端待真实 key） |\n| `gemini-native` | Gemini 原生 API | `tools:[{\"googleSearch\":{}}]`（generateContent 的 REST lowerCamel 写法；新的 Interactions API 用的是另一形状 `{\"type\":\"google_search\"}`，未来可作为新 spec） |\n| `openai-web-search` | OpenAI 兼容 `/v1/chat/completions` | `tools:[{\"type\":\"web_search\"}]`（OpenRouter 等网关插件风格；xAI 官方原生将此工具文档化在 /v1/responses，原生直连请用 `responses-web-search`） |\n| `openai-inherent` | OpenAI 兼容 `/v1/chat/completions` | 不注入工具 —— 搜索内生模型（Perplexity sonar 等）自带联网 |\n| `openai-google-search` | OpenAI 兼容 `/v1/chat/completions` | `tools:[{\"google_search\":{}}]`（**特殊**：Gemini 网关翻译约定 —— Google 官方兼容层未文档化 chat 侧此写法，仅适用于会把它译成原生 grounding 的反代） |\n\n直连 AI Studio 的例子：`J_SEARCH_BASE_URL=https://generativelanguage.googleapis.com`、`J_SEARCH_MODEL=gemini-2.5-flash`、`J_SEARCH_API_SPEC=gemini-native`。\n\n### 配好后自检\n\n```bash\nJ_SEARCH_BASE_URL=... J_SEARCH_API_KEY=... J_SEARCH_MODEL=... \\\n  J_SEARCH_API_SPEC=... npx j-can-search --check\n```\n\n用一个训练期不可能知道的时间敏感问题逼出真实搜索行为，再用引用校验层判定：**至少 1 条 verified 来源才 PASS**。退出码 0/1。\n\n## 工具\n\n`web_search(query, {freshness?, max_sources?})` 返回三段式：\n\n1. **答案**：引擎模型的合成回答（跟随查询语言）；\n2. **来源清单**：每条带状态 —— `已验证✓`（200 且标题相符）/ `已验证✓·标题不符⚠`（URL 真实但标题对不上，疑似挪用旧文）/ `反爬拦截△未验证`（403/429）/ `无法访问△`；\n3. **警示区**：拼造/404 链接剔除并点名；引擎一个 URL 都没给时明确警告「答案无引用支撑，谨慎采信」。\n\n每次调用回显引擎 token 用量（网关多为余额计费，消耗可见）。\n\n## 注意\n\n- 每次调用消耗所配引擎模型约 2-3k token，搜索加校验约 30-60 秒；调用方模型的原生搜索可用时优先原生（工具描述里带此调度门控）。\n- 工具返回的网页内容是证据不是指令（输出中带防注入提示）。\n\n## License\n\nMIT\n","readmeFilename":"README.zh-CN.md","homepage":"https://github.com/PichurChill/j-ai-kit/tree/main/packages/j-can-search#readme","keywords":["mcp","model-context-protocol","web-search","search","grounding","gemini","grok","openai","citation-verification","claude-code","codex"],"repository":{"url":"git+https://github.com/PichurChill/j-ai-kit.git","type":"git","directory":"packages/j-can-search"},"bugs":{"url":"https://github.com/PichurChill/j-ai-kit/issues"},"license":"MIT"}