Research MCP

research-mcp

面向编码／研究 Agent 的付费带引文研究远程 MCP（使用 API 密钥认证，而非 OAuth）。

**付费理由：**仅提供与查询相关、摘录自许可来源的内容包；无法提供带引文的内容时会拒绝请求——该次调用费用为 $0。采用预付内容包；仅对可计费的成功请求计费。

仓库可能是私有的；请将此 README 视为面向 Agent 的契约。Fly 上的线上主机保持不变。

营销网站（Cloudflare Pages）

权威来源：research-mcp-hq/www（public/）。线上网站：**https://researchmcp.dev**。

此仓库中的 www/ 目录树仅为存根／镜像说明——请勿将 Cloudflare Pages 指向此处。MCP API 源站仍在 Fly；品牌安装 URL 为 https://mcp.researchmcp.dev/mcp。

MCP URL（生产环境）

https://mcp.researchmcp.dev/mcp

健康状态：https://mcp.researchmcp.dev/health
服务卡片：https://mcp.researchmcp.dev/.well-known/mcp/server-card.json
额度计量：GET https://mcp.researchmcp.dev/billing/credits（需认证）

{
  "mcpServers": {
    "research-mcp": {
      "url": "https://mcp.researchmcp.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

认证

每个 /mcp 和 /billing/credits 请求都必须包含：

• Authorization: Bearer <key> 或
• X-API-Key: <key>

密钥：预付费客户密钥（来自 Checkout 成功页面）或应急 API_KEYS（运维使用；不扣减账本额度）。

隐私（需求信号）

我们会记录类别组合（工具、主题类别、主机、可计费或失败 = $0）——不会记录你的问题。需在服务器上通过 DEMAND_LOG=1 自愿启用；默认关闭。

定价（已锁定）

内容包	额度
$10 入门包	1000¢
$25 标准包	2500¢
$50 专业包	5000¢

计量档位（可计费的成功请求）	价格
轻量（source_lookup、research_brief depth=quick）	$0.25
标准（research_brief depth=standard）	$0.60
深度（仅预览）	$1.50 公布计价；预览路径始终为 $0

**失败 = $0：**示例／演示、报价门槛未通过、密度检查未通过、COGS 中止、取消、深度不匹配的黄金样例、预览／停用路径（meta.billable=false、charge_usd=0）。

查看余额和表格：GET /billing/credits → balance_cents、packs、meters_usd、fail_usd: 0。应急密钥返回 { break_glass: true, balance_cents: null }（不会伪造余额）。

何时调用各工具

在线（默认付费服务）

工具	何时调用	不要这样做
research_brief	需要 AI 基础设施／MCP／安全领域带引文、与查询相关的摘录包时调用。depth=quick（$0.25）或 depth=standard（$0.60）。	请勿使用 depth=deep（已停用／仅用于示例，预览标志启用时除外）。
source_lookup	需要获取／验证一个 URL 或主张时调用。轻量档 $0.25。	请勿将其用于开放网络搜索或多来源综合。

两者都会返回共享封装：tldr、body、confidence、sources、gaps、as_of，以及 schema_version（2026-09-14）。可选字段包括 fail_gate: { reason, retryable }、claims／摘录、retrieved_at。如果 source_url 上的引文未通过验证，则本次运行会被拒绝且不收费。

预览／停用（ENABLE_PREVIEW_TOOLS=1）

工具／路径	行为
compare_options	仅在启用标志时注册。始终为 $0／billable=false。没有在线路径——优先使用 research_brief。
depth=deep	仅在启用标志时允许。始终为 $0。软预留额度不会要求购买完整深度 SKU。

未启用标志时：不会注册 compare_options；depth=deep 会被拒绝（preview_required）。目录卡片仍会注明不要调用 compare/deep。

没有存根计费，也没有 25 种工具的大杂烩——默认仅提供两种在线工具。

已发布契约

• 架构：docs/contract/schema.json
• 示例：docs/contract/examples/happy-research-brief.json、fail-gate.json
• 响应中的 HTTP 标头：X-Research-MCP-Schema-Version: 2026-09-14
• 工具说明：docs/TOOLS.md

快速入门（本地）

cd /workspace/research-mcp
npm install && npm run build
API_KEYS=dev-key-1 npm start
# optional live brief path:
LIVE_RESEARCH=1 API_KEYS=dev-key-1 npm start

curl -s http://127.0.0.1:3000/health
curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer dev-key-1' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

环境变量（高信号）

变量	说明
API_KEYS	紧急备用密钥（以逗号分隔）
LIVE_RESEARCH=1	为 quick/standard 启用实时搜索→提取→综合→引用门控
ENABLE_PREVIEW_TOOLS=1	注册 compare + 允许 deep（始终为 $0）
DATABASE_URL	用于客户密钥 / 额度的 SQLite 账本
Stripe STRIPE_* / 套餐价格 ID	预付 Checkout（正式上线前使用测试模式）

测试

npm run eval:all      # goldens + off-golden + pipeline
npm run test:billing  # ledger / webhook / credits meter

目录结构

• src/server.ts — 工具注册（完成或隐藏）
• src/billing/credits.ts — GET /billing/credits（T10 可见用量表）
• src/contract.ts — schema_version + fail_gate
• docs/contract/ — 已发布的 JSON Schema + 示例
• ARCHITECTURE.md — 传输 / 身份验证 / 用量计量

发现

平台	URL / ID
GitHub	https://github.com/research-mcp-hq/research-mcp
Fly MCP	https://mcp.researchmcp.dev/mcp
Smithery（仅用于发现）	https://smithery.ai/servers/research-mcp-hq/research-mcp

列表展示的主页：https://researchmcp.dev，而非 Smithery。

运维

请参阅 RUNBOOK.md。许可证：MIT。