ToolRank

ToolRank（私有 MVP → 可公开部署）

面向 Agent 任务的 MCP 服务 / API 排名候选列表 — 健康状态、price_band 和安装片段。

在线地址： https://toolrank.onrender.com — OpenAPI 见 /openapi.json，Streamable HTTP MCP 见 /mcp。

为 Brandon Clark / ToolRank 构建的私有项目。保留所有权利（见 LICENSE）。GitHub：brandonclark1996-design/toolrank。

**如实说明：**排名基于词法匹配（令牌重叠），并非通过学习得出，也没有赞助。目录包含 36 个精选工具。health 通常为 unknown。**Stripe 尚未接入。**尚未购买自定义域名。

技术栈

• Node 20、TypeScript
• Hono HTTP API
• Zod 验证
• JSON 目录（data/catalog.json，包含 36 个精选公开工具）
• 通过 @modelcontextprotocol/sdk 提供 MCP stdio（npm run mcp）和 Streamable HTTP（POST /mcp）
• 在 /v1/* 和 /mcp 上通过 API 密钥进行身份验证，并实施进程本地软配额（src/auth.ts）

快速开始（本地）

cd /workspace/toolrank
cp .env.example .env
# Edit .env — set TOOLRANK_API_KEYS if you want keyed access locally
export TOOLRANK_API_KEYS='trk_live_test:builder'
npm install
npm test
npm run build
npm start              # listens on 0.0.0.0:$PORT (default 8787)
# or: npm run dev

使用测试密钥通过本地 curl 调用

export TOOLRANK_API_KEYS='trk_live_test:builder'
npm start

curl -s http://127.0.0.1:8787/health | jq .

curl -s http://127.0.0.1:8787/v1/search \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer trk_live_test' \
  -d '{"job":"scrape website to markdown for RAG","constraints":{"budget":"any"},"limit":5}' | jq .

# Or X-API-Key:
curl -s http://127.0.0.1:8787/v1/search \
  -H 'content-type: application/json' \
  -H 'X-API-Key: trk_live_test' \
  -d '{"job":"web search for research","limit":3}' | jq .

匿名访问（无密钥）可用，直至达到免费 IP 配额（滚动 24 小时内 20 次）。

身份验证与限制

调用方	方式	软限制（进程本地，滚动 24 小时）
匿名	无密钥	对 /v1/* 和 /mcp，每个 IP 20 次请求
free 密钥	Authorization: Bearer <key> 或 X-API-Key: <key>	每个密钥 100 次
builder 密钥	同上	每个密钥 2000 次

• 环境变量：TOOLRANK_API_KEYS = 以逗号分隔的密钥，可选 key:plan（free | builder）。示例：trk_live_abc:builder,trk_live_xyz:free。仅提供密钥时，默认计划为 free。
• /health 和 /openapi.json 始终开放（无需身份验证，也不计入配额）。
• 密钥无效 → 401 { error, schema_version, as_of }
• 超出配额 → 429 + Retry-After（秒数提示）
• 经过身份验证的 POST /v1/search 响应会包含 plan（free | builder）
• 配额存储在内存中／进程本地——适用于单实例 MVP；服务重启后会重置，且不会在多个副本间同步。

在主机上设置密钥（Brandon）

不要提交真实密钥。在主机环境中设置 TOOLRANK_API_KEYS：

1. **Render：**控制面板 → 你的 Web 服务 → Environment → 添加 TOOLRANK_API_KEYS = trk_live_….…:builder,…（使用 sync: false／密钥）。然后重新部署。
2. **Railway：**Service → Variables → TOOLRANK_API_KEYS。
3. **Docker / VPS：**使用 -e TOOLRANK_API_KEYS='…'，或在 Git 仓库之外通过 systemd／环境文件设置。
4. **本地：**运行 npm start 前，先执行 export TOOLRANK_API_KEYS='trk_live_test:builder'。

另请设置 HOST=0.0.0.0（代码中的默认值），并由平台注入 PORT。

HTTP API

基址：https://toolrank.onrender.com（本地为 http://127.0.0.1:8787）。

方法	路径	描述
GET	/health	存活状态 + 目录元数据（开放）
POST	/v1/search	为任务排列工具（需身份验证／计入配额）
GET	/v1/tools/:id	工具详情（需身份验证／计入配额）
GET	/v1/fresh?since=	自 ISO 时间戳以来的更新（需身份验证／计入配额）
GET	/openapi.json	OpenAPI 3.1（开放）
ALL	/mcp	Streamable HTTP MCP（需身份验证／计入配额；与 stdio 使用相同的工具）

搜索请求体

{
  "job": "string (required)",
  "constraints": {
    "budget": "free | paid | any",
    "auth": "optional hint",
    "runtime": "mcp | api | …"
  },
  "limit": 10,
  "check_health": false
}

可选的 check_health: true 会探测排名靠前的结果（超时 2 秒）。探测失败时仍标记为 unknown（不会误报为 down）。

部署（无自定义域名／无 Stripe）

Docker

docker build -t toolrank .
docker run --rm -p 8787:8787 \
  -e TOOLRANK_API_KEYS='trk_live_prod:builder' \
  toolrank

Render

• Blueprint：render.yaml（Docker Web 服务，适合免费计划）。
• 在线主机名：https://toolrank.onrender.com（无需自定义域名）。
• 在控制面板中设置 TOOLRANK_API_KEYS。

Railway

• 使用 railway.toml（Dockerfile）或 Procfile（构建后执行 web: node dist/index.js）。
• 在 Variables 中设置 TOOLRANK_API_KEYS。使用 Railway 的公共 HTTP 域名。

原生 Node 主机的构建步骤：npm ci && npm run build，然后运行 node dist/index.js。

MCP

工具：search_tools、get_tool、list_fresh（stdio 和 HTTP 共用处理程序）。

Streamable HTTP（生产环境）

https://toolrank.onrender.com/mcp

与 /v1/* 使用相同的 API 密钥 / 匿名配额。官方 MCP Registry 清单：server.json（io.github.brandonclark1996-design/toolrank）。除非收到要求，否则不要在此机器上运行 mcp-publisher。

Cursor / Claude HTTP MCP 配置片段：

{
  "mcpServers": {
    "toolrank": {
      "url": "https://toolrank.onrender.com/mcp"
    }
  }
}

stdio（本地）

npm run mcp

{
  "mcpServers": {
    "toolrank": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/workspace/toolrank"
    }
  }
}

排名

1. 对 job 进行分词（去除停用词）。
2. 对标签 / 名称 / 描述匹配项评分。
3. 在预算限制下，提高匹配 price_band 的排名。
4. 提高 health: up 的排名；降低 health: down 的排名。
5. 略微优先考虑 mcp / both 接口。

诚实的词法排名，不存在付费推广。共精选 36 个工具。健康状态通常未知。Stripe 尚未接入。

文档

• docs/AGENT.md — 供 Agent 阅读的用法说明（认证标头 + 限制）
• docs/llms.txt — 精简的机器摘要
• server.json — 官方 MCP Registry 清单（尚未发布）
• scripts/README-ingest.md — 用于未来从 registry.modelcontextprotocol.io 导入的占位文档

测试与构建

npm test    # vitest — ranking, envelope, auth middleware, /mcp
npm run build

待办事项

• 实现 Registry 导入（scripts/README-ingest.md）
• 在重启之间持久化健康探测结果
• Stripe / 付费升级（尚未开始）
• 自定义域名（尚未购买 / 接入）
• 多实例时使用共享 Redis（或类似方案）配额
• 使用 mcp-publisher 发布 server.json（本次变更未运行）

许可证

保留所有权利 — Brandon Clark / ToolRank。详见 LICENSE。