Context7 MCP
HARD GATE — Max 3 Context7 tool calls per user question (
resolve-library-id+query-docscount toward the cap). On quota/rate-limit errors, emit an explicit CONTEXT7_UNAVAILABLE block — do NOT silently answer from training data.HARD GATE — Before HTTP fetch, check
bash scripts/lib/doc-fetch-cache.sh get "<libraryId>:<query>". Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry.
When to Use
- Setup/configuration questions ("How do I configure Next.js middleware?")
- Code involving libraries ("Write a Prisma query for…")
- API references ("What are the Supabase auth methods?")
- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
Bounded Retry (max 3x)
| Attempt | Action |
|---|---|
| 1 | resolve-library-id → pick best match |
| 2 | query-docs with selected libraryId |
| 3 | Retry query-docs once with refined query (narrower scope) |
After 3 failures, stop and print:
CONTEXT7_UNAVAILABLE Reason: <quota|rate-limit|no-match|timeout> Action: Ask user to retry later, paste official docs URL, or run `bts docs <lib>`. Do NOT substitute training-data answers without labeling them UNVERIFIED.
Fetch Cache (ETag-revalidated)
- Cache key:
"<libraryId>:<normalized-query>"(lowercase, trimmed). - Read:
bash scripts/lib/doc-fetch-cache.sh get "<key>"— exit 0 → use cached body. - Miss / stale: call
query-docs; store viadoc-fetch-cache.sh put. - TTL: 300s default (
DOC_CACHE_TTL). Stale entries refresh on next fetch; honorETagwhen MCP returns it.
bts docs <lib> shares the same cache helper when invoked from this skill.
Process
resolve-library-idwithlibraryName+ full userquery.- Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version.
query-docswithlibraryId+ specific question (one concept per call).- Answer using fetched docs; cite library/version when relevant.
Verify
→ verify: test -f scripts/lib/doc-fetch-cache.sh
