Dribba

dribba

适用于 Dribba 公共 API 的官方 SDK 和 CLI。

无需 API 密钥、OAuth 或账户。 所有读取端点均公开。如果你在找凭据页面，那并不存在——请参阅 dribba.com/auth.md。

• 参考文档：https://dribba.com/docs
• 契约：https://dribba.com/openapi.json（OpenAPI 3.1）
• 开发者门户：https://dribba.com/developers

CLI

无需安装：

npx dribba services --table
npx dribba cases --limit 3 | jq -r '.items[].slug'
npx dribba estimate --platforms ios,android --complexity complex
npx dribba ask "flutter migration"
npx dribba markdown /servicios
npx dribba --help

添加 --sandbox，即可访问冻结的测试数据，而不是生产环境。

MCP 服务（stdio 桥接）

Dribba 的 MCP 服务是远程服务——通过 https://dribba.com/mcp 提供 Streamable HTTP。如果 你的客户端只支持 stdio，此软件包提供了桥接程序：

{
  "mcpServers": {
    "dribba": { "command": "npx", "args": ["-y", "dribba-mcp"] }
  }
}

npx dribba-mcp            # product surface: 5 tools + llms.txt resources
npx dribba-mcp --docs     # documentation surface: 4 tools

它只转发 JSON-RPC，不做其他处理，因此工具、资源和协议版本都以服务声明为准——不会有第二套实现 逐渐偏离。如果你的客户端支持 Streamable HTTP，请跳过桥接程序，直接连接该 URL。

已通过官方 @modelcontextprotocol/sdk 在 stdio 上验证：connect、 tools/list、tools/call、resources/list、resources/read。

SDK

npm i dribba        # JavaScript / TypeScript
pip install dribba  # Python 3.9+, same methods, also dependency-free

Python 客户端位于 python/，并以 dribba 的名称发布到 PyPI。

import { Dribba } from "dribba";

const dribba = new Dribba();

const { items, total, next_cursor } = await dribba.services({ limit: 5 });
const study = await dribba.case("cityxerpa");
const budget = await dribba.estimate({ platforms: ["ios", "android"] });

// Whole collections, following the cursor for you
for await (const job of dribba.paginate("/api/v1/jobs")) {
  console.log(job.title);
}

错误

每个 4xx/5xx 响应都会抛出 DribbaError。请根据 code 分支处理——它是稳定的。title 和 detail 是文本描述，措辞可能会调整。

import { DribbaError } from "dribba";

try {
  await dribba.service("nope");
} catch (error) {
  if (error instanceof DribbaError && error.code === "resource_not_found") {
    console.log(error.resolution); // what to do next, from the server
  }
}

速率限制

每个 IP 每 60 秒最多 120 个请求。每次调用后，dribba.rateLimit 都会保存上一响应公布的限制信息， 因此你可以自行限速，而不必触发 429：

await dribba.company();
console.log(dribba.rateLimit); // { limit: 120, remaining: 118, reset: 47 }

沙盒

使用与生产环境相同数据结构的冻结测试数据。它很有用，因为断言“有 9 个服务”的测试会在我们发布第十个服务时失效——而使用沙盒则不会。

const sandbox = new Dribba({ sandbox: true });
const services = await sandbox.services(); // services.sandbox === true

幂等性

任何 POST 请求都可使用 Idempotency-Key。相同的键和相同的请求正文会重放已存储的响应；相同的键搭配不同的正文则会返回 400。

await dribba.estimate(input, { idempotencyKey: crypto.randomUUID() });

Markdown 和异步导出

获取任意页面的 Markdown，或通过一次请求导出多个页面：

const page = await dribba.markdown("/servicios");

const job = await dribba.startExport(["/", "/precios", "/servicios"]);
await dribba.waitForExport(job.id);
const everything = await dribba.exportResult(job.id);

导出任务存储在单个服务实例的内存中，并会在 15 分钟后过期；轮询时收到 404，意味着请求到达了另一个实例，而不是任务丢失。

REST API 之外

• MCP——两个通过 Streamable HTTP 提供的远程服务，无需身份验证： https://dribba.com/mcp（操作）和 https://dribba.com/docs/mcp（文档）。 请参阅 https://dribba.com/developers/mcp。
• 任意页面的 Markdown——使用 Accept: text/markdown，或在 URL 后追加 .md。
• 整个网站，以 OKF 包的形式提供。
• /ask——NLWeb：用自然语言提问，并返回原文段落。

技能和 Agent 插件清单

此代码仓库也可作为可移植的 Agent Plugin：

plugin.json          the manifest
mcp.json             the two remote MCP servers
skills/              seven SKILL.md files describing what dribba.com exposes

将技能安装到你的 Agent 中：

npx skills add dribbaengineering/dribba

skills/ 是根据网站在 https://dribba.com/.well-known/agent-skills/ 提供的内容生成的。请编辑网站，而不是副本——副本会逐渐偏离。

要求

Node 20+。零依赖。

许可证

MIT。API 背后的数据采用 CC BY 4.0 许可——请注明“Dribba”并链接到来源 URL。