duckdata

duckdata

duckdata 是一个本地小型桥接程序，用于连接托管的 HasData DuckDuckGo MCP 服务，并以 JSON 格式返回 DuckDuckGo 搜索 结果。提交查询后，它会返回按排名排列的自然搜索结果——标题、URL、摘要、显示的 URL、位置、日期、站点链接和视频元数据—— 广告则单独放在另一个数组中；如果上游提供了 Search Assist AI 答案，也会一并返回。

该桥接程序本身不保存任何搜索结果。它会在本地提供上游服务的工具列表，该列表 与从实时端点捕获的内容完全一致；并将每次工具调用转发给上游，原样返回结果。捕获到的 工具集只有一个只读搜索获取工具。其中没有写入、消息传递或付款工具。

工具

• hasdata_duckduckgo_serp_getSearchResults — 获取 DuckDuckGo SERP。捕获到的架构不包含 required 数组：q 是搜索词（除非提供了 nextPageToken，否则必填；该令牌包含 要继续查询的搜索词）。使用 kl 指定地区（采用 <country>-<language> 代码，例如 us-en 或 de-de，支持 37 个地区），也可以改用 cc 与 setLang 组合——kl 优先级更高。使用 safeSearch 过滤成人内容（off、moderate 或 strict），使用 deviceType 选择设备类型 （desktop、mobile 或 tablet），并使用上一次响应返回的 不透明 nextPageToken 翻页。

配置

• HASDATA_DUCKDUCKGO_MCP_URL（可选）——覆盖 上游端点。默认值为 https://mcp.hasdata.com/mcp?apis=duckduckgo。（此覆盖钩子是本次重建中自行标注的 还原内容。）
• HASDATA_API_KEY（可选）——设置后，每个 上游请求都会携带 x-api-key: <key> 请求头，其中使用调用者自己的 HasData API 密钥。未设置时，不会发送密钥请求头。（请求头 名称和环境变量名称由原始版本的注册记录确定；从该环境 变量转发密钥是本次重建中标注的还原内容——原始 工具集是在无密钥状态下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26， clientInfo name duckdata），然后发送 notifications/initialized 通知，接着发送携带调用者参数的 tools/call 请求，参数保持不变。上游通过 initialize 响应返回 Mcp-Session-Id 请求头时，该值会随 此会话的每个后续请求一同发送，并在进程运行期间重用。 响应可能是普通 JSON，也可能是服务器发送事件；两种格式都会读取。

上游的成功结果会原样传递，包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或 无法完成的请求——会作为 isError 结果返回，其 文本以 duckdata error: 开头（此错误呈现方式是本次重建中自行标注的 还原内容）。

CLI

该工具也可作为子命令使用，接受一个 JSON 参数字符串：

npx @reneturcios/duckdata hasdata_duckduckgo_serp_getSearchResults '{"q":"open source search","kl":"us-en","safeSearch":"moderate","deviceType":"desktop"}'
npx @reneturcios/duckdata --version

退出码：成功时为 0，结果包含 isError 时为 1， 用法错误时为 2。

MCP 服务

npx -y @reneturcios/duckdata mcp

MCP 客户端配置：

{
  "mcpServers": {
    "duckdata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/duckdata", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/duckdata
docker run --rm ghcr.io/cloudcorprecords/duckdata --version

容器的默认命令是 mcp，因此第一种形式会启动 stdio MCP 服务；其他参数则会照常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全通过桩接的 JSON-RPC 上游运行——不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。