ToolRank MCP server

ToolRank (private MVP → public-ready deploy)

Ranked shortlist of MCP servers / APIs for agent jobs — health, price_band, and install snippet.

Live: https://toolrank.onrender.com — OpenAPI at /openapi.json, Streamable HTTP MCP at /mcp.

Private build for Brandon Clark / ToolRank. All Rights Reserved (see LICENSE). GitHub: brandonclark1996-design/toolrank.

Honesty: Ranking is lexical (token overlap), not learned or sponsored. Catalog is 36 curated tools. health is often unknown. Stripe is not wired. Custom domain is not purchased.

Stack

• Node 20, TypeScript
• Hono HTTP API
• Zod validation
• JSON catalog (data/catalog.json, 36 curated public tools)
• MCP stdio (npm run mcp) and Streamable HTTP (POST /mcp) via @modelcontextprotocol/sdk
• API-key auth + process-local soft quotas (src/auth.ts) on /v1/* and /mcp

Quick start (local)

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

Local curl with a test key

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 .

Anonymous (no key) works until the free IP quota is hit (20 / rolling 24h).

Auth + limits

• Env: TOOLRANKAPIKEYS = comma-separated keys, optional key:plan (free \| builder). Example: trkliveabc:builder,trklivexyz:free. Bare key → free.
• /health and /openapi.json are always open (no auth / no quota).
• Invalid key → 401 { error, schemaversion, asof }
• Over quota → 429 + Retry-After (seconds hint)
• Authed POST /v1/search responses include plan (free \| builder)
• Quotas are in-memory / process-local — fine for single-instance MVP; they reset on restart and do not sync across replicas.

Setting keys on the host (Brandon)

Do not commit real keys. Set TOOLRANKAPIKEYS in the host environment:

1. Render: Dashboard → your Web Service → Environment → add TOOLRANKAPIKEYS = trklive….…:builder,… (use sync: false / secret). Redeploy.
2. Railway: Service → Variables → TOOLRANKAPIKEYS.
3. Docker / VPS: -e TOOLRANKAPIKEYS='…' or systemd/env file outside git.
4. Local: export TOOLRANKAPIKEYS='trklivetest:builder' before npm start.

Also set HOST=0.0.0.0 (default in code) and let the platform inject PORT.

HTTP API

Base: https://toolrank.onrender.com (or http://127.0.0.1:8787 locally).

Shortened. The full README is on GitHub.