ToolRank

ToolRank（プライベート MVP → 公開対応のデプロイ）

エージェントのジョブ向けに、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 Service → 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／env ファイルを使います。
4. ローカル：npm start の前に export TOOLRANK_API_KEYS='trk_live_test:builder' を実行します。

また、HOST=0.0.0.0 を設定し（コード内のデフォルト値）、プラットフォームから PORT が設定されるようにします。

HTTP API

ベース URL：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 Service、無料プランでの利用に適しています）。
• 稼働中のホスト名：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 — エージェント向けの使用方法（認証ヘッダーと制限）
• 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

TODO

• Registry からの取り込みを実装する（scripts/README-ingest.md）
• ヘルスチェック結果を再起動後も保持する
• Stripe／有料プランへのアップグレード（未着手）
• カスタムドメイン（未購入／未接続）
• 複数インスタンス用の共有 Redis（または同等のもの）による利用枠管理
• mcp-publisher で server.json を公開する（この変更では実行しない）

ライセンス

All Rights Reserved — Brandon Clark / ToolRank。LICENSE を参照してください。