Context7 Library Documentation

You are an expert at using the Context7 MCP server to retrieve current, accurate library documentation. Context7 provides up-to-date docs for thousands of libraries and frameworks, eliminating outdated training data issues.

Critical: These Are Direct Tool Calls

MCP tools are direct tool calls — exactly like Read, Grep, or Bash. They are NOT CLI commands.

CORRECT — call the tool directly:

Tool: mcp__context7__resolve-library-id
Parameters: { "libraryName": "next.js" }

WRONG — do NOT shell out:

Bash: claude mcp call context7 resolve-library-id ...  # This does not work

All Context7 MCP tools use the mcp__context7__ prefix.

Critical: Always Resolve Library ID First

You must call resolve-library-id before query-docs unless you already have a confirmed /org/project ID from a previous call in this session.

Critical: Output Size Awareness

Tool	Output Size	Notes
resolve-library-id	Small	Returns list of matching library IDs
query-docs	Medium-Large	Documentation content — scales with topic breadth. Use specific queries to limit size.

Workflow: Find & Query Documentation

Trigger: User asks about library APIs, framework patterns, configuration options, or "how to do X with Y library"

Steps

1. Resolve the library ID:

   resolve-library-id({ libraryName: "next.js" })
   → returns matching libraries with /org/project IDs
   

2. Query documentation with a specific question:

   query-docs({ libraryId: "/vercel/next.js", query: "how to use middleware for authentication" })
   → returns relevant documentation sections
   

3. Refine if needed (max 3 calls per tool per question):

   query-docs({ libraryId: "/vercel/next.js", query: "middleware matcher config" })
   → more specific follow-up
   

Key Patterns

• Be specific in queries: "How to set up authentication with JWT in Express.js" beats "auth"
• Max 3 calls per tool per question — if 3 queries don't answer it, use a different approach
• One library per query — don't try to query multiple libraries in a single query-docs call
• Use the full /org/project format for libraryId (e.g., /vercel/next.js, /supabase/supabase)

Decision Tree

User Needs	Action
Docs for a known library	resolve-library-id → query-docs
Not sure which library to use	resolve-library-id with general term, review matches
Already have library ID from this session	Skip resolve, go straight to query-docs
Library not found in Context7	Fall back to tavily-mcp search or WebFetch for official docs site

Common Library IDs

These are frequently used in this project — skip resolve-library-id for these:

Library	ID
Next.js	/vercel/next.js
React	/facebook/react
Supabase JS	/supabase/supabase-js
TanStack Query	/tanstack/query
Zod	/colinhacks/zod
React Hook Form	/react-hook-form/react-hook-form
Tailwind CSS	/tailwindlabs/tailwindcss
date-fns	/date-fns/date-fns
Radix UI	/radix-ui/primitives
Playwright	/microsoft/playwright
Vitest	/vitest-dev/vitest

Note: If a common ID stops working, re-resolve it — library IDs can change when repos are reorganized.

Troubleshooting

"Library not found"

1. Try alternate names: "react-query" vs "tanstack query" vs "@tanstack/react-query"
2. Try the npm package name: "next" vs "next.js"
3. Try the GitHub org/repo format directly: "vercel/next.js"
4. Fall back to tavily-mcp search for the official docs URL, then use WebFetch

Query Returns Irrelevant Results

1. Make your query more specific — include the exact API name or concept
2. Try rephrasing: "server actions" vs "use server directive" vs "form actions"
3. Add version context: "Next.js 15 app router middleware" vs just "middleware"

Query Returns Too Much Content

1. Narrow the query to a specific function or concept
2. Ask about one feature at a time rather than broad overviews
3. If output is still large, extract the relevant section and summarize for the user