Context7 Platform -- Up-to-date docs for AI agents
CTX7-3091: Add language argument to query-docs and ctx7 docs (#3357)
Enes Gules2c0f36202a06
diff --git a/.changeset/cli-docs-language.md b/.changeset/cli-docs-language.mdnew file mode 100644index 00000000..6fa41d6b--- /dev/null+++ b/.changeset/cli-docs-language.md@@ -0,0 +1,5 @@+---+"ctx7": minor+---++Add a `--language` option to `ctx7 docs`. When you pass the programming language you write in, Context7 ranks code examples in that language first.diff --git a/.changeset/rerank-language-hint.md b/.changeset/rerank-language-hint.mdnew file mode 100644index 00000000..4cd326be--- /dev/null+++ b/.changeset/rerank-language-hint.md@@ -0,0 +1,5 @@+---+"@upstash/context7-mcp": minor+---++Add an optional `language` argument to `query-docs`. When the agent knows the programming language the user writes in, Context7 ranks code examples in that language first.diff --git a/README.md b/README.mdindex aa34be9b..e7cec6a0 100644--- a/README.md+++ b/README.md@@ -111,6 +111,7 @@ Always use Context7 when I need library/API documentation, code generation, setu- `query-docs`: Retrieves documentation for a library using a Context7-compatible library ID.- `libraryId` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`)- `query` (required): The question or task to get relevant documentation for+ - `language` (optional): The programming language you write in, used to rank code examples in that language first## More Documentationdiff --git a/docs/api-guide.mdx b/docs/api-guide.mdxindex 2bf27a28..4c436246 100644--- a/docs/api-guide.mdx+++ b/docs/api-guide.mdx@@ -153,7 +153,7 @@ The [Context7 MCP server](/resources/all-clients) exposes the same lookups as ag| MCP tool | Endpoint | Parameters ||----------|----------|------------|| `resolve-library-id` | [Search Library](/api-reference/search/search-for-libraries) — `GET /api/v2/libs/search` | `libraryName`, `query` |-| `query-docs` | [Get Context](/api-reference/context/get-documentation-context) — `GET /api/v2/context` | `libraryId`, `query` |+| `query-docs` | [Get Context](/api-reference/context/get-documentation-context) — `GET /api/v2/context` | `libraryId`, `query`, `language` |Call the REST API directly to control requests from your own code, or use the MCP tools when you want an agent to fetch documentation automatically during inference. Both use the same [API key](#authentication).diff --git a/docs/clients/cli.mdx b/docs/clients/cli.mdxindex 460f11ee..f4a2b8c4 100644--- a/docs/clients/cli.mdx+++ b/docs/clients/cli.mdx@@ -93,6 +93,9 @@ Queries work best when they're specific. Describe what you're trying to accompliThe output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context). Both are formatted for readability in the terminal.```bash+# Rank code examples in the language you write in first+ctx7 docs /websites/twilio "How to send an SMS" --language Ruby+# Output as structured JSONctx7 docs /facebook/react "How to use hooks for state management" --jsondiff --git a/docs/resources/all-clients.mdx b/docs/resources/all-clients.mdxindex 74e7f2c4..c02f5994 100644--- a/docs/resources/all-clients.mdx+++ b/docs/resources/all-clients.mdx@@ -58,6 +58,7 @@ Fetch documentation context for a library and a specific question.|-----------|------|-------------|| `libraryId` | string, required | Exact Context7-compatible library ID, e.g., `/vercel/next.js` or `/vercel/next.js/v15.1.8` || `query` | string, required | What to look up, scoped to a single concept |+| `language` | string, optional | Programming language you write in, e.g., `Python` or `Go`. Code examples in that language rank first |The tool returns the relevant documentation and code examples as text.diff --git a/packages/cli/src/commands/docs.ts b/packages/cli/src/commands/docs.tsindex a41df158..2565b34c 100644--- a/packages/cli/src/commands/docs.ts+++ b/packages/cli/src/commands/docs.ts@@ -111,7 +111,7 @@ async function resolveCommand(async function queryCommand(libraryId: string,query: string,- options: { json?: boolean }+ options: { json?: boolean; language?: string }): Promise<void> {trackEvent("command", { name: "docs" });@@ -137,7 +137,12 @@ async function queryCommand(let result;try {- result = await getLibraryContext(libraryId, query, { type: outputType }, accessToken);+ result = await getLibraryContext(+ libraryId,+ query,+ { type: outputType, language: options.language },+ accessToken+ );} catch (err) {spinner?.fail(`Error: ${err instanceof Error ? err.message : String(err)}`);if (!spinner) log.error(err instanceof Error ? err.message : String(err));@@ -227,8 +232,14 @@ export function registerDocsCommands(program: Command): void {"Single-topic question to get docs for (run a separate query per distinct concept, unless asking how they interact)").option("--json", "Output as JSON")+ .option(+ "--language <name>",+ "Programming language you write in (e.g., Python, Go); ranks code examples in that language first"+ ).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; language?: string }) => {+ await queryCommand(libraryId, query, options);+ }+ );}diff --git a/packages/cli/src/utils/api.ts b/packages/cli/src/utils/api.tsindex 7b07b384..b5327bdd 100644--- a/packages/cli/src/utils/api.ts+++ b/packages/cli/src/utils/api.ts@@ -313,6 +313,7 @@ export async function resolveLibrary(export interface GetContextOptions {type?: "json" | "txt";+ language?: string;}export async function getLibraryContext(@@ -325,6 +326,9 @@ export async function getLibraryContext(if (options?.type) {params.set("type", options.type);}+ if (options?.language) {+ params.set("language", options.language);+ }const headers = getAuthHeaders(accessToken);const response = await fetch(`${baseUrl}/api/v2/context?${params}`, {headers,diff --git a/packages/mcp/README.md b/packages/mcp/README.mdindex 63f69241..1be482de 100644--- a/packages/mcp/README.md+++ b/packages/mcp/README.md@@ -1385,6 +1385,7 @@ Context7 MCP provides the following tools that LLMs can use:- `query-docs`: Queries up-to-date documentation and code examples for a Context7-compatible library ID.- `libraryId` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`)- `query` (required): The concept to look up, scoped to a single topic+ - `language` (optional): The programming language you write in, used to rank code examples in that language first`get-library-docs` was renamed to `query-docs`. Update client tool allowlists to use `query-docs`.diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex eaeb513e..0393f6f5 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -314,7 +314,9 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot fYou 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.-Do not call this tool more than 3 times per question.`,+Do not call this tool more than 3 times per question.++If you know the programming language the user is working in, pass it as \`language\` so the results match their setup.`,inputSchema: z.preprocess(aliasArgs({ ...GLOBAL_ALIASES, ...QUERY_DOCS_ALIASES }),z.object({@@ -328,6 +330,13 @@ Do not call this tool more than 3 times per question.`,.describe("What to look up in the library's documentation, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. 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."),+ // No length limit here: the API trims long values instead of rejecting the call.+ language: z+ .string()+ .optional()+ .describe(+ "Programming language the user is writing code in, such as 'Python', 'TypeScript', 'Go', or 'C#'. Ranks code examples in that language first. Leave it out when the language is unknown or does not apply."+ ),})),annotations: {@@ -337,9 +346,12 @@ Do not call this tool more than 3 times per question.`,idempotentHint: true,},},- async ({ query, libraryId }: { query: string; libraryId: string }, toolCtx) => {+ async (+ { query, libraryId, language }: { query: string; libraryId: string; language?: string },+ toolCtx+ ) => {const ctx = getClientContext(toolCtx);- const response = await fetchLibraryContext({ query, libraryId }, ctx);+ const response = await fetchLibraryContext({ query, libraryId, language }, ctx);maybeElicitAuthSignIn(server, ctx);recordToolCallTelemetry(ctx, response.outcome);return {diff --git a/packages/mcp/src/lib/api.ts b/packages/mcp/src/lib/api.tsindex 478685a3..12a3b87e 100644--- a/packages/mcp/src/lib/api.ts+++ b/packages/mcp/src/lib/api.ts@@ -178,7 +178,7 @@ export async function searchLibraries(/*** Fetches intelligent, reranked context for a natural language query- * @param request The context request parameters (query, libraryId)+ * @param request The context request parameters (query, libraryId, language)* @param context Client context including IP, API key, and client info* @returns Context response with data*/@@ -190,6 +190,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.language) url.searchParams.set("language", request.language);const headers = generateHeaders(context);const abortSignal = AbortSignal.timeout(API_TIMEOUT_MS);diff --git a/packages/mcp/src/lib/types.ts b/packages/mcp/src/lib/types.tsindex 3d85c591..1386f8ee 100644--- a/packages/mcp/src/lib/types.ts+++ b/packages/mcp/src/lib/types.ts@@ -28,6 +28,7 @@ export type DocumentState = "initial" | "finalized" | "error" | "delete";export type ContextRequest = {query: string;libraryId: string;+ language?: string;};export type ContextResponse = {diff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.tsindex edf1003b..f415cd4a 100644--- a/packages/mcp/test/integration.test.ts+++ b/packages/mcp/test/integration.test.ts@@ -502,6 +502,7 @@ describe.each([]);const queryDocs = tools.find((t) => t.name === "query-docs")!;expect(Object.keys(queryDocs.inputSchema.properties ?? {}).sort()).toEqual([+ "language","libraryId","query",]);@@ -561,6 +562,24 @@ describe.each([expect(text).toContain("/vercel/next.js");});+ test("forwards the language hint to the context endpoint", async () => {+ await client.callTool({+ name: "query-docs",+ arguments: { libraryId: "/websites/twilio", query: "send an SMS", language: "Python" },+ });+ expect(requests.find((r) => r.path === "/v2/context")!.query.get("language")).toBe("Python");+ });++ test("accepts a long language hint instead of rejecting the call", async () => {+ const language = "TypeScript with React 19 and Next.js 16 app router";+ const result = await client.callTool({+ name: "query-docs",+ arguments: { libraryId: "/vercel/next.js", query: "app router", language },+ });+ expect(result.isError).toBeFalsy();+ expect(requests.find((r) => r.path === "/v2/context")!.query.get("language")).toBe(language);+ });+test("rewrites hallucinated argument aliases before validation", async () => {const result = await client.callTool({name: "query-docs",diff --git a/skills/context7-cli/references/docs.md b/skills/context7-cli/references/docs.mdindex c2bbde47..4f36b837 100644--- a/skills/context7-cli/references/docs.md+++ b/skills/context7-cli/references/docs.md@@ -93,6 +93,9 @@ Describe what to look up in the library's documentation in the query when possibThe output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).```bash+# Rank code examples in the language you write in first+ctx7 docs /websites/twilio "How to send an SMS" --language Ruby+# Output as structured JSONctx7 docs /facebook/react "How to use hooks for state management" --jsondiff --git a/skills/find-docs/SKILL.md b/skills/find-docs/SKILL.mdindex 314f5789..d751069c 100644--- a/skills/find-docs/SKILL.md+++ b/skills/find-docs/SKILL.md@@ -113,6 +113,12 @@ npx ctx7@latest docs /vercel/next.js "How to add authentication middleware to apnpx ctx7@latest docs /prisma/prisma "How to define one-to-many relations with cascade delete"```+If you know the programming language the user writes in, add `--language` so code examples in that language rank first:++```bash+npx ctx7@latest docs /websites/twilio "How to send an SMS" --language Ruby+```+### Writing good queriesThe query directly affects the quality of results. Be specific and include relevant details, but keep each query to one topic — if the question spans multiple distinct concepts, run a separate `docs` command per concept instead of combining them, unless the question is about how the concepts interact. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.