Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 Documentation
diff --git a/docs/api-guide.mdx b/docs/api-guide.mdx
index 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.mdx
index 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 accompli
The 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 JSON
ctx7 docs /facebook/react "How to use hooks for state management" --json
diff --git a/docs/resources/all-clients.mdx b/docs/resources/all-clients.mdx
index 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.ts
index 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.ts
index 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.md
index 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.ts
index 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 f
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.
-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.ts
index 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.ts
index 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.ts
index 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.md
index 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 possib
The 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 JSON
ctx7 docs /facebook/react "How to use hooks for state management" --json
diff --git a/skills/find-docs/SKILL.md b/skills/find-docs/SKILL.md
index 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 ap
npx 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 queries
The 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.