stable-search MCP Server

stable-search-mcp 是一个可通过 npx 启动的 MCP 服务，用来把 stable-search 的多源搜索能力暴露给支持 MCP 的智能体。

当前实现已是 纯 Node.js + TypeScript，不再依赖外置 Python 运行时。这意味着：

• 安装后只需 Node.js 即可运行
• 可直接发布到 npm，并通过 npx stable-search-mcp 启动
• 保留 Grok、Tavily、Exa、SearxNG 的多源编排、聚合、回退与排序能力

提供的 MCP Tools

stable_search

输入：

• query：必填，搜索词
• intent：可选，general | docs | news | overview
• freshness：可选，day | week | month | year
• limit：可选，返回结果上限，默认 12，最大 20

输出：

• answer
• results
• citations
• sourcesUsed
• errors
• meta
• final
• fetch
• siteMap
• providerDetails

stable_search_status

输出各 provider 是否已启用/已配置，并返回不含密钥的诊断信息：

• Grok
• Tavily
• Exa
• SearxNG

环境变量

按现有实现保持兼容，常用变量如下：

• GROK_API_BASE_URL / GROK_API_URL
• GROK_API_KEY
• TAVILY_PROXY_URL
• TAVILY_PROXY_KEY
• EXA_POOL_URL
• EXA_POOL_KEY
• EXA_TIMEOUT
• SEARXNG_URL
• FIRECRAWL_API_URL
• FIRECRAWL_API_KEY
• STABLE_FETCH_DEFAULT
• STABLE_FETCH_TOP_N
• STABLE_FETCH_MAX_RETRIES
• STABLE_USE_JINA
• STABLE_USE_DEFUDDLE
• STABLE_READER_TIMEOUT
• STABLE_CACHE_TTL_SEC
• STABLE_CACHE_MAX_ITEMS

其中有三项尤须公子自行显式设定，不再内置任何默认反代：

• GROK_API_BASE_URL 或 GROK_API_URL
• TAVILY_PROXY_URL
• SEARXNG_URL

程序会自动读取项目根目录下的 .env，亦可直接由 MCP 客户端通过 env 注入。

请使用 .env.example 作为占位模板；切勿将真实密钥写入仓库。

本地运行

安装依赖

npm install

开发模式

npm run dev

构建

npm run build

启动 MCP 服务

npm start

若公子使用 .env，可直接在项目根目录放置该文件后再启动，无须另手导入。

或在发布后通过：

npx stable-search-mcp

冒烟自测

检查配置状态：

npm run smoke:status

执行一次搜索：

npm run smoke:search

MCP 客户端配置示例

本地源码方式

{
  "mcpServers": {
    "stable-search": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/absolute/path/to/stable-search",
      "env": {
        "GROK_API_KEY": "<secret>",
        "TAVILY_PROXY_KEY": "<secret>",
        "EXA_POOL_URL": "https://exa-pool.example.com",
        "EXA_POOL_KEY": "<secret>",
        "SEARXNG_URL": "https://searxng.example.com"
      }
    }
  }
}

npx 方式

{
  "mcpServers": {
    "stable-search": {
      "command": "npx",
      "args": ["stable-search-mcp"],
      "env": {
        "GROK_API_KEY": "<secret>",
        "TAVILY_PROXY_KEY": "<secret>"
      }
    }
  }
}

示例 Tool Calls

stable_search

{
  "query": "OpenAI GPT-5.4 release notes",
  "intent": "docs",
  "freshness": "month",
  "limit": 8
}

stable_search_status

{}

架构说明

当前版本是 纯 Node.js MCP 服务：

• src/index.ts：MCP 服务入口，定义 tools，并通过 stdio 提供服务
• src/search-core.ts：搜索编排、聚合、回退、抓取与结果整形
• src/providers.ts：Grok、Tavily、Exa、SearxNG、Firecrawl 与 reader fallback 调用
• src/utils.ts：评分、去重、缓存、意图判断与公共工具

兼容策略

• 继续保留 intent、freshness、limit 这些面向 MCP 的稳定输入
• freshness 仍做 day/week/month/year -> pd/pw/pm/py 的内部映射
• 输出结构继续保持 agent-friendly 与稳定 JSON 形态

当前限制

• npx stable-search-mcp 仍需先将本包发布到 npm
• provider 可用性仍取决于环境变量与上游服务是否可达
• 仓中的 stable_search.py 仅作迁移参照，运行时已不再依赖它
• Grok、Tavily、SearxNG 不再带任何默认代理地址，未配置时会在 stable_search_status 中直接显示未就绪

npm 发布步骤

1. 登录 npm：

npm login

2. 确认包名是否可用；若需改名，请修改 package.json 中的 name

3. 将 package.json 中这些占位值改成真实仓库地址：

• repository.url
• homepage
• bugs.url

4. 构建并检查打包内容：

npm run build
npm pack --dry-run

5. 正式发布：

npm publish

若要发布 scoped 包，如 @scope/stable-search-mcp，请同步调整 name，并保留 publishConfig.access 为 public。

后续建议

• 增加自动化测试，覆盖 stable_search 与 stable_search_status
• 发布到 npm 后验证 npx stable-search-mcp 的安装与启动体验
• 若要进一步提升可维护性，可将 provider 请求层拆得更细，并补录 fixture 测试