Context7 Platform -- Up-to-date docs for AI agents
expose research mode through MCP and CLI (#2498)
Enes Akar17b864f23fd2
diff --git a/.changeset/cuddly-clowns-bow.md b/.changeset/cuddly-clowns-bow.mdnew file mode 100644index 00000000..b4442dcf--- /dev/null+++ b/.changeset/cuddly-clowns-bow.md@@ -0,0 +1,6 @@+---+"ctx7": minor+"@upstash/context7-mcp": minor+---++Expose research mode through the MCP `researchMode` tool and the CLI `docs --research` flag for deep, agent-driven documentation answers.diff --git a/docs/openapi.json b/docs/openapi.jsonindex aaa599d9..d65a8ad3 100644--- a/docs/openapi.json+++ b/docs/openapi.json@@ -31,6 +31,9 @@},{"$ref": "#/components/parameters/QueryParam"+ },+ {+ "$ref": "#/components/parameters/FastParam"}],"responses": {@@ -72,6 +75,9 @@"401": {"$ref": "#/components/responses/UnauthorizedError"},+ "402": {+ "$ref": "#/components/responses/SpendingLimitError"+ },"404": {"$ref": "#/components/responses/NotFoundError"},@@ -110,6 +116,12 @@},{"$ref": "#/components/parameters/TypeParam"+ },+ {+ "$ref": "#/components/parameters/FastParam"+ },+ {+ "$ref": "#/components/parameters/ResearchModeParam"}],"responses": {@@ -170,6 +182,9 @@"403": {"$ref": "#/components/responses/ForbiddenError"},+ "402": {+ "$ref": "#/components/responses/SpendingLimitError"+ },"404": {"$ref": "#/components/responses/NotFoundError"},@@ -181,6 +196,9 @@},"500": {"$ref": "#/components/responses/InternalServerError"+ },+ "502": {+ "$ref": "#/components/responses/ResearchNoSourcesError"}},"security": [@@ -1186,6 +1204,104 @@}]}+ },+ "/v2/add/notion": {+ "post": {+ "summary": "Add Notion pages",+ "description": "Submit selected Notion pages for documentation processing. Requires a connected Notion account and a team project.",+ "operationId": "addNotion",+ "tags": [+ "Add Library"+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "workspaceId",+ "workspaceName",+ "pageIds",+ "title",+ "description"+ ],+ "properties": {+ "workspaceId": {+ "type": "string",+ "description": "The Notion workspace ID"+ },+ "workspaceName": {+ "type": "string",+ "description": "The Notion workspace name"+ },+ "pageIds": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of Notion page IDs to index."+ },+ "title": {+ "type": "string",+ "description": "Title for the library"+ },+ "description": {+ "type": "string",+ "description": "Description of the library"+ },+ "projectId": {+ "type": "string",+ "description": "The team project ID to associate these Notion pages with"+ }+ }+ },+ "example": {+ "workspaceId": "workspace-uuid",+ "workspaceName": "Acme Workspace",+ "pageIds": [+ "page-1",+ "page-2"+ ],+ "title": "Product Docs",+ "description": "Internal Notion knowledge base",+ "projectId": "project-uuid"+ }+ }+ }+ },+ "responses": {+ "200": {+ "$ref": "#/components/responses/AddLibrarySuccess"+ },+ "400": {+ "$ref": "#/components/responses/BadRequestError"+ },+ "401": {+ "$ref": "#/components/responses/UnauthorizedError"+ },+ "403": {+ "$ref": "#/components/responses/ForbiddenError"+ },+ "409": {+ "$ref": "#/components/responses/DuplicateError"+ },+ "429": {+ "$ref": "#/components/responses/RateLimitError"+ },+ "500": {+ "$ref": "#/components/responses/InternalServerError"+ },+ "504": {+ "$ref": "#/components/responses/GatewayTimeoutError"+ }+ },+ "security": [+ {+ "bearerAuth": []+ }+ ]+ }}},"components": {@@ -1261,6 +1377,36 @@"default": "txt"},"example": "json"+ },+ "FastParam": {+ "name": "fast",+ "in": "query",+ "description": "When `true`, skip LLM reranking and return top vector-search results directly. Trades relevance quality for lower latency.",+ "required": false,+ "schema": {+ "type": "string",+ "enum": [+ "true",+ "false"+ ],+ "default": "false"+ },+ "example": "true"+ },+ "ResearchModeParam": {+ "name": "researchMode",+ "in": "query",+ "description": "When `true`, run a deeper agentic research pipeline that returns a single synthesized `infoSnippet` instead of ranked snippets. Requires an API key and is subject to a weekly per-user quota.",+ "required": false,+ "schema": {+ "type": "string",+ "enum": [+ "true",+ "false"+ ],+ "default": "false"+ },+ "example": "true"}},"schemas": {@@ -1403,6 +1549,14 @@"items": {"$ref": "#/components/schemas/CodeExample"}+ },+ "isDynamic": {+ "type": "boolean",+ "description": "Whether this snippet was recovered from the dynamic source-code index instead of the primary docs index"+ },+ "sourceFile": {+ "type": "string",+ "description": "Repo-relative source file path for dynamic snippets"}},"required": [@@ -2173,6 +2327,20 @@}}},+ "SpendingLimitError": {+ "description": "Payment Required - the teamspace's configured monthly spending limit has been reached. A teamspace owner or admin can raise the limit in billing settings, or the cap will reset at the start of the next billing month.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ },+ "example": {+ "error": "spending_limit_exceeded",+ "message": "Monthly spending limit of $5.00 reached for this teamspace. An owner or admin can raise the limit at https://context7.com/dashboard/billing, or the cap will reset at the start of next month."+ }+ }+ }+ },"RateLimitError": {"description": "Too Many Requests - Rate limit exceeded","headers": {@@ -2226,6 +2394,20 @@}}}+ },+ "ResearchNoSourcesError": {+ "description": "Bad Gateway - Research mode could not retrieve any source material for the query",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ },+ "example": {+ "error": "research_no_sources",+ "message": "Research mode could not retrieve any source material for this query."+ }+ }+ }}}},diff --git a/packages/cli/src/commands/docs.ts b/packages/cli/src/commands/docs.tsindex bf9e5b91..c555df18 100644--- a/packages/cli/src/commands/docs.ts+++ b/packages/cli/src/commands/docs.ts@@ -116,7 +116,7 @@ async function resolveCommand(async function queryCommand(libraryId: string,query: string,- options: { json?: boolean }+ options: { json?: boolean; research?: boolean }): Promise<void> {trackEvent("command", { name: "docs" });@@ -128,13 +128,22 @@ async function queryCommand(return;}- const spinner = isTTY ? ora(`Fetching docs for "${libraryId}"...`).start() : null;+ const spinner = isTTY+ ? ora(+ options.research ? `Researching "${libraryId}"...` : `Fetching docs for "${libraryId}"...`+ ).start()+ : null;const accessToken = getAccessToken();const outputType = options.json ? "json" : "txt";let result;try {- result = await getLibraryContext(libraryId, query, { type: outputType }, accessToken);+ result = await getLibraryContext(+ libraryId,+ query,+ { type: outputType, researchMode: options.research },+ accessToken+ );} catch (err) {spinner?.fail(`Error: ${err instanceof Error ? err.message : String(err)}`);if (!spinner) log.error(err instanceof Error ? err.message : String(err));@@ -221,8 +230,14 @@ export function registerDocsCommands(program: Command): void {.argument("<libraryId>", "Context7 library ID (e.g., /facebook/react)").argument("<query>", "Question or task to get docs for").option("--json", "Output as JSON")+ .option(+ "--research",+ "Retry the query with deep research: spins up sandboxed agents that read the actual source repos (git pull + inspect) and runs a live web search, then synthesizes a fresh answer. Use on retry if you weren't satisfied with the first answer. More costly than the default."+ ).description("Query documentation for a library")- .action(async (libraryId: string, query: string, options: { json?: boolean }) => {- await queryCommand(libraryId, query, options);- });+ .action(+ async (libraryId: string, query: string, options: { json?: boolean; research?: boolean }) => {+ await queryCommand(libraryId, query, options);+ }+ );}diff --git a/packages/cli/src/setup/templates.ts b/packages/cli/src/setup/templates.tsindex 26b96140..8e399ff0 100644--- a/packages/cli/src/setup/templates.ts+++ b/packages/cli/src/setup/templates.ts@@ -12,7 +12,8 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo1. \`resolve-library-id\` with the library name and the user's question. Use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs")2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). Use version-specific IDs when the user mentions a version3. \`query-docs\` with the selected library ID and the user's full question (not single words)-4. Answer using the fetched docs+4. If you weren't satisfied with the answer, call \`query-docs\` again for the same library with \`researchMode: true\`. This retries with sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. More costly than the default+5. Answer using the fetched docs`;const FALLBACK_CLI = `Use the \`ctx7\` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.@@ -24,7 +25,8 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo1. Resolve library: \`npx ctx7@latest library <name> "<user's question>"\`2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try the full name with punctuation (e.g., "next.js" not "nextjs")3. Fetch docs: \`npx ctx7@latest docs <libraryId> "<user's question>"\`-4. Answer using the fetched documentation+4. If you weren't satisfied with the answer, re-run the same command with \`--research\`. This retries with sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. More costly than the default+5. Answer using the fetched documentationYou MUST call \`library\` first to get a valid ID (format: \`/org/project\`) unless the user provides one directly. Use the user's full question as the query -- specific and detailed queries return better results than vague single words. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.diff --git a/packages/cli/src/utils/api.ts b/packages/cli/src/utils/api.tsindex 870a4afa..accf4d17 100644--- a/packages/cli/src/utils/api.ts+++ b/packages/cli/src/utils/api.ts@@ -309,6 +309,7 @@ export async function resolveLibrary(export interface GetContextOptions {type?: "json" | "txt";+ researchMode?: boolean;}export async function getLibraryContext(@@ -321,6 +322,9 @@ export async function getLibraryContext(if (options?.type) {params.set("type", options.type);}+ if (options?.researchMode) {+ params.set("researchMode", "true");+ }const response = await fetch(`${baseUrl}/api/v2/context?${params}`, {headers: getAuthHeaders(accessToken),});diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex 1de77a7c..af234e2d 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -246,7 +246,7 @@ server.registerTool(You must call 'Resolve Context7 Library ID' tool first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.-IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.`,+Workflow: call first without researchMode. If that doesn't answer the question, retry with researchMode: true. Do not call each tool more than 3 times per question`,inputSchema: {libraryId: z.string()@@ -258,13 +258,22 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f.describe("The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad: 'auth' or 'hooks'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."),+ researchMode: z+ .boolean()+ .optional()+ .describe(+ `Retry the query with deep research: spins up sandboxed agents that read the actual source repos and runs a live web search, then synthesizes a fresh answer. Set true on retry if you weren't satisfied with the first answer and want a more thorough one. Requires an API key — you can get one free at https://context7.com.`+ ),},annotations: {readOnlyHint: true,},},- async ({ query, libraryId }) => {- const response = await fetchLibraryContext({ query, libraryId }, getClientContext());+ async ({ query, libraryId, researchMode }) => {+ const response = await fetchLibraryContext(+ { query, libraryId, researchMode },+ getClientContext()+ );return {content: [diff --git a/packages/mcp/src/lib/api.ts b/packages/mcp/src/lib/api.tsindex 2ba6e2a6..e4a84e46 100644--- a/packages/mcp/src/lib/api.ts+++ b/packages/mcp/src/lib/api.ts@@ -142,6 +142,7 @@ export async function fetchLibraryContext(const url = new URL(`${CONTEXT7_API_BASE_URL}/v2/context`);url.searchParams.set("query", request.query);url.searchParams.set("libraryId", request.libraryId);+ if (request.researchMode) url.searchParams.set("researchMode", "true");const headers = generateHeaders(context);diff --git a/packages/mcp/src/lib/types.ts b/packages/mcp/src/lib/types.tsindex e25ae758..ec9021cc 100644--- a/packages/mcp/src/lib/types.ts+++ b/packages/mcp/src/lib/types.ts@@ -26,6 +26,7 @@ export type DocumentState = "initial" | "finalized" | "error" | "delete";export type ContextRequest = {query: string;libraryId: string;+ researchMode?: boolean;};export type ContextResponse = {diff --git a/plugins/claude/context7/skills/context7-mcp/SKILL.md b/plugins/claude/context7/skills/context7-mcp/SKILL.mdindex 234659d9..c4ac1e06 100644--- a/plugins/claude/context7/skills/context7-mcp/SKILL.md+++ b/plugins/claude/context7/skills/context7-mcp/SKILL.md@@ -38,6 +38,10 @@ Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)- `query`: The user's specific question+### Step 3.5: Retry with researchMode if you weren't satisfied++If the default `query-docs` answer didn't satisfy, call `query-docs` **again for the same library** with `researchMode: true`. This retries using sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. Do this before giving up or answering from training data. More costly than the default — use it as a targeted retry.+### Step 4: Use the DocumentationIncorporate the fetched documentation into your response:diff --git a/plugins/cursor/context7/skills/context7-mcp/SKILL.md b/plugins/cursor/context7/skills/context7-mcp/SKILL.mdindex 234659d9..c4ac1e06 100644--- a/plugins/cursor/context7/skills/context7-mcp/SKILL.md+++ b/plugins/cursor/context7/skills/context7-mcp/SKILL.md@@ -38,6 +38,10 @@ Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)- `query`: The user's specific question+### Step 3.5: Retry with researchMode if you weren't satisfied++If the default `query-docs` answer didn't satisfy, call `query-docs` **again for the same library** with `researchMode: true`. This retries using sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. Do this before giving up or answering from training data. More costly than the default — use it as a targeted retry.+### Step 4: Use the DocumentationIncorporate the fetched documentation into your response:diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex aac4bf06..1654ca59 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -90,7 +90,7 @@ importers:version: 3.6.2tsup:specifier: ^8.5.0- version: 8.5.1([email protected])([email protected])typescript:specifier: ^5.8.2version: 5.9.3@@ -99,7 +99,7 @@ importers:version: 8.47.0([email protected])([email protected])vitest:specifier: ^4.0.13- version: 4.0.14(@opentelemetry/[email protected])(@types/[email protected])packages/mcp:dependencies:@@ -133,7 +133,7 @@ importers:version: 5.9.3vitest:specifier: ^4.0.13- version: 4.0.14(@opentelemetry/[email protected])(@types/[email protected])packages/sdk:devDependencies:@@ -145,13 +145,13 @@ importers:version: 17.2.3tsup:specifier: ^8.5.1- version: 8.5.1([email protected])([email protected])typescript:specifier: ^5.8.2version: 5.9.3vitest:specifier: ^4.0.13- version: 4.0.14(@opentelemetry/[email protected])(@types/[email protected])packages/tools-ai-sdk:devDependencies:@@ -172,13 +172,13 @@ importers:version: 17.2.3tsup:specifier: ^8.5.1- version: 8.5.1([email protected])([email protected])typescript:specifier: ^5.8.2version: 5.9.3vitest:specifier: ^4.0.13- version: 4.0.14(@opentelemetry/[email protected])(@types/[email protected])zod:specifier: ^4.3.4version: 4.3.5@@ -1649,6 +1649,9 @@ packages:resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}engines: {node: '>= 0.4'}+ resolution: {integrity: sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==}+resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}engines: {node: '>= 6'}@@ -2131,6 +2134,9 @@ packages:resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==}engines: {node: '>=8'}+ resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}+resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}engines: {node: '>=18'}@@ -2347,6 +2353,11 @@ packages:typescript:optional: true+ resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}+ engines: {node: '>=18.0.0'}+ hasBin: true+resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}engines: {node: '>= 0.8.0'}@@ -3419,21 +3430,21 @@ snapshots:chai: 6.2.1tinyrainbow: 3.0.3dependencies:'@vitest/spy': 4.0.14estree-walker: 3.0.3magic-string: 0.30.21optionalDependencies:- vite: 7.2.4(@types/[email protected])+ vite: 7.2.4(@types/[email protected])([email protected])dependencies:'@vitest/spy': 4.0.14estree-walker: 3.0.3magic-string: 0.30.21optionalDependencies:- vite: 7.2.4(@types/[email protected])+ vite: 7.2.4(@types/[email protected])([email protected])'@vitest/[email protected]':dependencies:@@ -4000,6 +4011,11 @@ snapshots:dunder-proto: 1.0.1es-object-atoms: 1.1.1+ dependencies:+ resolve-pkg-maps: 1.0.0+ optional: true+dependencies:is-glob: 4.0.3@@ -4333,11 +4349,12 @@ snapshots:mlly: 1.8.0pathe: 2.0.3dependencies:lilconfig: 3.1.3optionalDependencies:postcss: 8.5.6+ tsx: 4.21.0dependencies:@@ -4394,6 +4411,9 @@ snapshots:+ optional: true+dependencies:onetime: 7.0.0@@ -4615,7 +4635,7 @@ snapshots:dependencies:bundle-require: 5.1.0([email protected])cac: 6.7.14@@ -4626,7 +4646,7 @@ snapshots:fix-dts-default-cjs-exports: 1.0.1joycon: 3.1.1picocolors: 1.1.1- postcss-load-config: 6.0.1([email protected])+ postcss-load-config: 6.0.1([email protected])([email protected])resolve-from: 5.0.0rollup: 4.53.3source-map: 0.7.6@@ -4643,6 +4663,14 @@ snapshots:- tsx- yaml+ dependencies:+ esbuild: 0.27.0+ get-tsconfig: 4.14.0+ optionalDependencies:+ fsevents: 2.3.3+ optional: true+dependencies:prelude-ls: 1.2.1@@ -4684,7 +4712,7 @@ snapshots:- [email protected](@types/[email protected]):dependencies:esbuild: 0.25.12fdir: 6.5.0([email protected])@@ -4695,8 +4723,9 @@ snapshots:optionalDependencies:'@types/node': 22.19.7fsevents: 2.3.3+ tsx: 4.21.0- [email protected](@types/[email protected]):dependencies:esbuild: 0.25.12fdir: 6.5.0([email protected])@@ -4707,11 +4736,12 @@ snapshots:optionalDependencies:'@types/node': 25.0.3fsevents: 2.3.3+ tsx: 4.21.0dependencies:'@vitest/expect': 4.0.14- '@vitest/mocker': 4.0.14([email protected](@types/[email protected]))'@vitest/pretty-format': 4.0.14'@vitest/runner': 4.0.14'@vitest/snapshot': 4.0.14@@ -4728,7 +4758,7 @@ snapshots:tinyexec: 0.3.2tinyglobby: 0.2.15tinyrainbow: 3.0.3- vite: 7.2.4(@types/[email protected])+ vite: 7.2.4(@types/[email protected])([email protected])why-is-node-running: 2.3.0optionalDependencies:'@opentelemetry/api': 1.9.0@@ -4746,10 +4776,10 @@ snapshots:- tsx- yamldependencies:'@vitest/expect': 4.0.14- '@vitest/mocker': 4.0.14([email protected](@types/[email protected]))'@vitest/pretty-format': 4.0.14'@vitest/runner': 4.0.14'@vitest/snapshot': 4.0.14@@ -4766,7 +4796,7 @@ snapshots:tinyexec: 0.3.2tinyglobby: 0.2.15tinyrainbow: 3.0.3- vite: 7.2.4(@types/[email protected])+ vite: 7.2.4(@types/[email protected])([email protected])why-is-node-running: 2.3.0optionalDependencies:'@opentelemetry/api': 1.9.0diff --git a/rules/context7-cli.md b/rules/context7-cli.mdindex f723bde1..c5ecec4b 100644--- a/rules/context7-cli.md+++ b/rules/context7-cli.md@@ -7,7 +7,8 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo1. Resolve library: `npx ctx7@latest library <name> "<user's question>"` — use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs")2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question)3. Fetch docs: `npx ctx7@latest docs <libraryId> "<user's question>"`-4. Answer using the fetched documentation+4. If you weren't satisfied with the answer, re-run the same command with `--research`. This retries with sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. More costly than the default+5. Answer using the fetched documentationYou MUST call `library` first to get a valid ID unless the user provides one directly in `/org/project` format. Use the user's full question as the query -- specific and detailed queries return better results than vague single words. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.diff --git a/rules/context7-mcp.md b/rules/context7-mcp.mdindex fe994d41..630e1834 100644--- a/rules/context7-mcp.md+++ b/rules/context7-mcp.md@@ -7,4 +7,5 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo1. Always start with `resolve-library-id` using the library name and the user's question, unless the user provides an exact library ID in `/org/project` format2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question). Use version-specific IDs when the user mentions a version3. `query-docs` with the selected library ID and the user's full question (not single words)-4. Answer using the fetched docs+4. If you weren't satisfied with the answer, call `query-docs` again for the same library with `researchMode: true`. This retries with sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. More costly than the default+5. Answer using the fetched docsdiff --git a/skills/context7-cli/SKILL.md b/skills/context7-cli/SKILL.mdindex 531aa8af..b0d9548c 100644--- a/skills/context7-cli/SKILL.md+++ b/skills/context7-cli/SKILL.md@@ -31,6 +31,7 @@ npx ctx7@latest <command># Documentationctx7 library <name> <query> # Step 1: resolve library IDctx7 docs <libraryId> <query> # Step 2: fetch docs+ctx7 docs <libraryId> <query> --research # Retry with deep research if the default answer didn't satisfy# Skillsctx7 skills install /owner/repo # Install from a repo (interactive)diff --git a/skills/context7-cli/references/docs.md b/skills/context7-cli/references/docs.mdindex ef5cae9b..b7045f04 100644--- a/skills/context7-cli/references/docs.md+++ b/skills/context7-cli/references/docs.md@@ -76,6 +76,14 @@ ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade deletIMPORTANT: Do not call `ctx7 docs` more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.+### Retry with `--research` if you weren't satisfied++If the default `ctx7 docs` answer didn't satisfy, re-run the same command **with `--research`** before giving up or answering from training data. This retries using sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. More costly than the default — use it as a targeted retry.++```bash+ctx7 docs /vercel/next.js "How does middleware matcher handle dynamic segments in v15?" --research+```+### Writing good queriesThe query directly affects the quality of results. Be specific and include relevant details. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.diff --git a/skills/context7-mcp/SKILL.md b/skills/context7-mcp/SKILL.mdindex 234659d9..c4ac1e06 100644--- a/skills/context7-mcp/SKILL.md+++ b/skills/context7-mcp/SKILL.md@@ -38,6 +38,10 @@ Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)- `query`: The user's specific question+### Step 3.5: Retry with researchMode if you weren't satisfied++If the default `query-docs` answer didn't satisfy, call `query-docs` **again for the same library** with `researchMode: true`. This retries using sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. Do this before giving up or answering from training data. More costly than the default — use it as a targeted retry.+### Step 4: Use the DocumentationIncorporate the fetched documentation into your response:diff --git a/skills/find-docs/SKILL.md b/skills/find-docs/SKILL.mdindex 99e5c6e1..e5c20dc5 100644--- a/skills/find-docs/SKILL.md+++ b/skills/find-docs/SKILL.md@@ -125,6 +125,14 @@ Use the user's full question as the query when possible, vague one-word queriesThe output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).+### Retry with `--research` if you weren't satisfied++If the default `ctx7 docs` answer didn't satisfy, re-run the same command **with `--research`** before giving up or answering from training data. This retries using sandboxed agents that git-pull the actual source repos plus a live web search, then synthesizes a fresh answer. More costly than the default — use it as a targeted retry.++```bash+ctx7 docs /vercel/next.js "How does middleware matcher handle dynamic segments in v15?" --research+```+## AuthenticationWorks without authentication. For higher rate limits: