Context7 Platform -- Up-to-date docs for AI agents
feat: remove research mode (#2554)
Enes Akar1aa3430bf67b
diff --git a/.changeset/remove-research-mode.md b/.changeset/remove-research-mode.mdnew file mode 100644index 00000000..c55d3cc0--- /dev/null+++ b/.changeset/remove-research-mode.md@@ -0,0 +1,6 @@+---+"ctx7": patch+"@upstash/context7-mcp": patch+---++Remove research mode entirely from the MCP server and CLI. The `query-docs` MCP tool no longer accepts or forwards a `researchMode` parameter, and the CLI no longer exposes a `--research` flag on `ctx7 docs`.diff --git a/docs/openapi.json b/docs/openapi.jsonindex 9a22ab49..7b32a1fd 100644--- a/docs/openapi.json+++ b/docs/openapi.json@@ -226,9 +226,6 @@},{"$ref": "#/components/parameters/FastParam"- },- {- "$ref": "#/components/parameters/ResearchModeParam"}],"responses": {@@ -303,9 +300,6 @@},"500": {"$ref": "#/components/responses/InternalServerError"- },- "502": {- "$ref": "#/components/responses/ResearchNoSourcesError"}},"security": [@@ -1500,21 +1494,6 @@},"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"- },"DaysParam": {"name": "days","in": "query",@@ -2704,20 +2683,6 @@}}}- },- "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 c555df18..aeed4a22 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; research?: boolean }+ options: { json?: boolean }): Promise<void> {trackEvent("command", { name: "docs" });@@ -128,22 +128,14 @@ async function queryCommand(return;}- const spinner = isTTY- ? ora(- options.research ? `Researching "${libraryId}"...` : `Fetching docs for "${libraryId}"...`- ).start()- : null;const accessToken = getAccessToken();++ const spinner = isTTY ? ora(`Fetching docs for "${libraryId}"...`).start() : null;const outputType = options.json ? "json" : "txt";let result;try {- result = await getLibraryContext(- libraryId,- query,- { type: outputType, researchMode: options.research },- accessToken- );+ result = await getLibraryContext(libraryId, query, { type: outputType }, accessToken);} catch (err) {spinner?.fail(`Error: ${err instanceof Error ? err.message : String(err)}`);if (!spinner) log.error(err instanceof Error ? err.message : String(err));@@ -230,14 +222,8 @@ 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; research?: boolean }) => {- await queryCommand(libraryId, query, options);- }- );+ .action(async (libraryId: string, query: string, options: { json?: boolean }) => {+ await queryCommand(libraryId, query, options);+ });}diff --git a/packages/cli/src/setup/templates.ts b/packages/cli/src/setup/templates.tsindex 8e399ff0..26b96140 100644--- a/packages/cli/src/setup/templates.ts+++ b/packages/cli/src/setup/templates.ts@@ -12,8 +12,7 @@ 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. 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+4. 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.@@ -25,8 +24,7 @@ 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. 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 documentation+4. 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 accf4d17..7abe6cf0 100644--- a/packages/cli/src/utils/api.ts+++ b/packages/cli/src/utils/api.ts@@ -309,7 +309,6 @@ export async function resolveLibrary(export interface GetContextOptions {type?: "json" | "txt";- researchMode?: boolean;}export async function getLibraryContext(@@ -322,11 +321,9 @@ export async function getLibraryContext(if (options?.type) {params.set("type", options.type);}- if (options?.researchMode) {- params.set("researchMode", "true");- }+ const headers = getAuthHeaders(accessToken);const response = await fetch(`${baseUrl}/api/v2/context?${params}`, {- headers: getAuthHeaders(accessToken),+ headers,});if (!response.ok) {diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.jsonindex d9da7951..38381198 100644--- a/packages/cli/tsconfig.json+++ b/packages/cli/tsconfig.json@@ -14,8 +14,7 @@"declaration": true,"declarationMap": true,"sourceMap": true,- "resolveJsonModule": true,- "types": ["node"]+ "resolveJsonModule": true},"include": ["src/**/*"],"exclude": ["node_modules", "dist"]diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex cc0d9f78..6894a045 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -244,7 +244,7 @@ ${resultsText}`;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.-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.`,+Do not call this tool more than 3 times per question.`,inputSchema: {libraryId: z.string()@@ -256,12 +256,6 @@ Workflow: call first without researchMode. If that doesn't answer the question,.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,@@ -270,49 +264,17 @@ Workflow: call first without researchMode. If that doesn't answer the question,idempotentHint: true,},},- async ({ query, libraryId, researchMode }, { sendNotification, _meta }) => {- // Emit periodic progress notifications while the upstream call is in flight.- // MCP clients that opt into resetTimeoutOnProgress (e.g. opencode) reset their- // request timer on each notification, which keeps long-running tools (notably- // researchMode) alive past the SDK's default 60s wall-clock timeout. Clients- // that don't pass a progressToken simply never see these, so behavior is unchanged.- const progressToken = _meta?.progressToken;- let progressInterval: ReturnType<typeof setInterval> | undefined;- if (researchMode && progressToken !== undefined) {- let progress = 0;- progressInterval = setInterval(() => {- progress += 1;- sendNotification({- method: "notifications/progress",- params: {- progressToken,- progress,- message: "Researching documentation...",- },- }).catch(() => {- // Notifications are best-effort; swallow transport errors so the tool- // call itself isn't aborted by a notification write failure.- });- }, 20_000);- }-- try {- const response = await fetchLibraryContext(- { query, libraryId, researchMode },- getClientContext()- );+ async ({ query, libraryId }) => {+ const response = await fetchLibraryContext({ query, libraryId }, getClientContext());- return {- content: [- {- type: "text",- text: response.data,- },- ],- };- } finally {- if (progressInterval) clearInterval(progressInterval);- }+ return {+ content: [+ {+ type: "text",+ text: response.data,+ },+ ],+ };});@@ -434,8 +396,8 @@ async function main() {// Use SSE responses for tool calls (enableJsonResponse: false). The SDK then// flushes response headers immediately after parsing the request rather than// buffering until the tool returns. This is required for long-running tools- // (e.g. researchMode) because some MCP HTTP clients cap the underlying fetch- // at 60s waiting for headers, even though the per-tool timeout is much higher.+ // because some MCP HTTP clients cap the underlying fetch at 60s waiting for+ // headers, even though the per-tool timeout is much higher.const transport = new StreamableHTTPServerTransport({sessionIdGenerator: undefined,enableJsonResponse: false,diff --git a/packages/mcp/src/lib/api.ts b/packages/mcp/src/lib/api.tsindex e4a84e46..2ba6e2a6 100644--- a/packages/mcp/src/lib/api.ts+++ b/packages/mcp/src/lib/api.ts@@ -142,7 +142,6 @@ 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 ec9021cc..e25ae758 100644--- a/packages/mcp/src/lib/types.ts+++ b/packages/mcp/src/lib/types.ts@@ -26,7 +26,6 @@ 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 c4ac1e06..234659d9 100644--- a/plugins/claude/context7/skills/context7-mcp/SKILL.md+++ b/plugins/claude/context7/skills/context7-mcp/SKILL.md@@ -38,10 +38,6 @@ 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 c4ac1e06..234659d9 100644--- a/plugins/cursor/context7/skills/context7-mcp/SKILL.md+++ b/plugins/cursor/context7/skills/context7-mcp/SKILL.md@@ -38,10 +38,6 @@ 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/rules/context7-cli.md b/rules/context7-cli.mdindex c5ecec4b..f723bde1 100644--- a/rules/context7-cli.md+++ b/rules/context7-cli.md@@ -7,8 +7,7 @@ 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. 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 documentation+4. 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 630e1834..fe994d41 100644--- a/rules/context7-mcp.md+++ b/rules/context7-mcp.md@@ -7,5 +7,4 @@ 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. 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+4. Answer using the fetched docsdiff --git a/skills/context7-cli/SKILL.md b/skills/context7-cli/SKILL.mdindex b0d9548c..531aa8af 100644--- a/skills/context7-cli/SKILL.md+++ b/skills/context7-cli/SKILL.md@@ -31,7 +31,6 @@ 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 b7045f04..ef5cae9b 100644--- a/skills/context7-cli/references/docs.md+++ b/skills/context7-cli/references/docs.md@@ -76,14 +76,6 @@ 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 c4ac1e06..234659d9 100644--- a/skills/context7-mcp/SKILL.md+++ b/skills/context7-mcp/SKILL.md@@ -38,10 +38,6 @@ 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 e5c20dc5..99e5c6e1 100644--- a/skills/find-docs/SKILL.md+++ b/skills/find-docs/SKILL.md@@ -125,14 +125,6 @@ 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: