CTX7-3522: Docs feedback score and required comment, with a feedback request in the server instructions

.changeset/research-preview-docs-feedback.md

@@ -2,4 +2,4 @@
 "@upstash/context7-mcp": minor
 ---
 
-Research preview: a `submit-docs-feedback` tool sends feedback on the documentation that `query-docs` returned (helpful or not, what was missing or wrong, and a short comment) from the agent or the user. It is listed only with research preview on: `--research-preview` or `CONTEXT7_RESEARCH_PREVIEW=1` for stdio, and `?research_preview=1` on the MCP URL for the hosted server.
+Research preview: a `submit-docs-feedback` tool sends feedback on the documentation that `query-docs` returned: a score from 0 to 5, what was wrong, and a short comment. It is listed only with research preview on: `--research-preview` or `CONTEXT7_RESEARCH_PREVIEW=1` for stdio, and `?research_preview=1` on the MCP URL for the hosted server. With research preview on, the server instructions also ask the agent to send this feedback after it answers. API calls carry `X-Context7-Research-Preview: 1`, so Context7 can count how many people use the research preview.

packages/mcp/src/index.ts

@@ -32,7 +32,10 @@ import {
 } from "./lib/constants.js";
 import { maybeElicitAuthSignIn } from "./lib/auth/auth-prompt.js";
 import { QUERY_DOCS_TOOL, RESOLVE_LIBRARY_ID_TOOL } from "./lib/tool-names.js";
-import { registerResearchPreviewTools } from "./lib/research-preview-tools.js";
+import {
+  DOCS_FEEDBACK_INSTRUCTIONS,
+  registerResearchPreviewTools,
+} from "./lib/research-preview-tools.js";
 import { installProcessShutdown } from "./lib/process-shutdown.js";
 import {
   forceFlushTelemetry,
@@ -325,11 +328,15 @@ function createMcpServer(mcpContext: McpRequestContext, researchPreview: boolean
     },
     instructions: `Use this server 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, porting code between libraries, platforms, or SQL dialects, 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.
 
-Do not use for: refactoring, debugging, or reviewing code that does not depend on a library or platform API, or general programming concepts.`,
+Do not use for: refactoring, debugging, or reviewing code that does not depend on a library or platform API, or general programming concepts.${researchPreview ? `\n\n${DOCS_FEEDBACK_INSTRUCTIONS}` : ""}`,
   };
   const server = mcpInstrumentation
     ? mcpInstrumentation.createServer(serverInfo, serverOptions, mcpContext)
     : new McpServer(serverInfo, serverOptions);
+  const toolClientContext = (toolCtx: ServerContext): ClientContext => ({
+    ...getClientContext(toolCtx),
+    ...(researchPreview ? { researchPreview: true } : {}),
+  });
 
   server.registerTool(
     RESOLVE_LIBRARY_ID_TOOL,
@@ -391,7 +398,7 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
       },
     },
     async ({ query, libraryName }: { query: string; libraryName: string }, toolCtx) => {
-      const ctx = getClientContext(toolCtx);
+      const ctx = toolClientContext(toolCtx);
       const searchResponse = await searchLibraries(query, libraryName, ctx);
 
       if (!searchResponse.results || searchResponse.results.length === 0) {
@@ -469,7 +476,7 @@ If you know the programming language the user is working in, pass it as \`langua
       { query, libraryId, language }: { query: string; libraryId: string; language?: string },
       toolCtx
     ) => {
-      const ctx = getClientContext(toolCtx);
+      const ctx = toolClientContext(toolCtx);
       const response = await fetchLibraryContext({ query, libraryId, language }, ctx);
       maybeElicitAuthSignIn(server, ctx);
       recordToolCallTelemetry(ctx, response.outcome);
@@ -489,7 +496,7 @@ If you know the programming language the user is working in, pass it as \`langua
     }
   );
 
-  if (researchPreview) registerResearchPreviewTools(server, getClientContext);
+  if (researchPreview) registerResearchPreviewTools(server, toolClientContext);
 
   return server;
 }

packages/mcp/src/lib/encryption.ts

@@ -83,6 +83,9 @@ export function generateHeaders(context: ClientContext): Record<string, string>
   if (context.transport) {
     headers["X-Context7-Transport"] = context.transport;
   }
+  if (context.researchPreview) {
+    headers["X-Context7-Research-Preview"] = "1";
+  }
 
   return headers;
 }

packages/mcp/src/lib/research-preview-tools.ts

@@ -5,6 +5,9 @@ import { recordToolCallTelemetry } from "./auth-lifecycle-telemetry.js";
 import { SUBMIT_DOCS_FEEDBACK_TOOL } from "./tool-names.js";
 import type { ClientContext, DocsFeedback } from "./types.js";
 
+/** Added to the server instructions with research preview on, so agents remember the feedback tool. */
+export const DOCS_FEEDBACK_INSTRUCTIONS = `After you answer a question with documentation from 'query-docs', call '${SUBMIT_DOCS_FEEDBACK_TOOL}' once for that library with a score from 0 to 5 and a short comment on the docs. The user turned on this research preview to collect this feedback.`;
+
 /**
  * Experimental tools, registered only with research preview on
  * (`--research-preview`, `CONTEXT7_RESEARCH_PREVIEW=1` or `?research_preview=1`).
@@ -20,10 +23,10 @@ export function registerResearchPreviewTools(
       title: "Submit Documentation Feedback",
       description: `Sends feedback on documentation that 'Query Documentation' returned, so Context7 can fix its docs.
 
-Call it once after you used the documentation of a library:
-- helpful: true when the docs answered the question.
-- helpful: false when they did not, with the issue: 'missing' (the docs do not cover it), 'outdated' (they describe an old version), 'incorrect' (the code or facts are wrong), 'irrelevant' (the results were about something else) or 'other'.
-Also call it when the user comments on the documentation, with author 'user' and their words in comment.
+Call it once after you used the documentation of a library to answer a question:
+- score: how well the docs answered it, from 0 (useless) to 5 (fully answered with correct, current code).
+- issue: what was wrong, only when the score is below 5: 'missing' (the docs do not cover it), 'outdated' (they describe an old version), 'incorrect' (the code or facts are wrong), 'irrelevant' (the results were about something else) or 'other'.
+- comment: what was missing or wrong, or what was good, in one or two sentences. When the user comments on the documentation, pass on their words.
 
 Do not include sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code.`,
       inputSchema: z.object({
@@ -33,21 +36,21 @@ Do not include sensitive or confidential information such as API keys, passwords
             "The Context7-compatible library ID the feedback is about, as passed to 'query-docs' (e.g., '/vercel/next.js')."
           ),
         query: z.string().optional().describe("The 'query-docs' query the feedback is about."),
-        helpful: z.boolean().describe("Whether the documentation answered the question."),
+        score: z
+          .number()
+          .int()
+          .min(0)
+          .max(5)
+          .describe("How well the docs answered the question, from 0 (useless) to 5 (fully)."),
         issue: z
           .enum(["missing", "outdated", "incorrect", "irrelevant", "other"])
           .optional()
-          .describe("What was wrong. Only when helpful is false."),
+          .describe("What was wrong. Only when the score is below 5."),
         comment: z
           .string()
-          .optional()
-          .describe(
-            "Short details: what was missing or wrong, or what the user said. Up to 1000 characters."
-          ),
-        author: z
-          .enum(["agent", "user"])
+          .min(1)
           .describe(
-            "'agent' for your own judgment of the docs, 'user' when you pass on the user's feedback."
+            "What was missing, wrong or good, in one or two sentences. Up to 1000 characters."
           ),
       }),
       annotations: {

packages/mcp/src/lib/types.ts

@@ -34,10 +34,9 @@ export type ContextRequest = {
 export type DocsFeedback = {
   libraryId: string;
   query?: string;
-  helpful: boolean;
+  score: number;
   issue?: "missing" | "outdated" | "incorrect" | "irrelevant" | "other";
-  comment?: string;
-  author: "agent" | "user";
+  comment: string;
 };
 
 export type ContextResponse = {
@@ -57,6 +56,8 @@ export interface ClientContext {
   mcpAuthMode?: "observe" | "required";
   transport?: "stdio" | "http";
   sessionId?: string;
+  /** Research preview is on; sent as `X-Context7-Research-Preview: 1` so the app counts preview use. */
+  researchPreview?: boolean;
   /** Mutable: set by the upstream API layer when the backend signals the
    *  client should be prompted to sign in. Read by the auth-prompt wrapper. */
   shouldPrompt?: boolean;

packages/mcp/test/integration.test.ts

@@ -627,10 +627,9 @@ describe("research preview", () => {
       const feedback = {
         libraryId: "/vercel/next.js",
         query: "app router caching",
-        helpful: false,
+        score: 2,
         issue: "outdated",
         comment: "Shows the Next.js 14 cache defaults.",
-        author: "agent",
       };
       const result = await client.callTool({ name: "submit-docs-feedback", arguments: feedback });
 
@@ -639,6 +638,7 @@ describe("research preview", () => {
       const apiCall = requests.find((request) => request.path === "/v2/feedback");
       expect(apiCall?.headers.authorization).toBe("Bearer ctx7sk-local-test");
       expect(apiCall?.headers["x-context7-source"]).toBe("mcp-server");
+      expect(apiCall?.headers["x-context7-research-preview"]).toBe("1");
     } finally {
       await client.close();
     }
@@ -878,6 +878,7 @@ describe.each([
     expect(apiCalls[0].query.get("libraryId")).toBe("/vercel/next.js");
     expect(apiCalls[0].query.get("query")).toBe("app router");
     expect(apiCalls[0].headers["x-context7-transport"]).toBe(transportKind);
+    expect(apiCalls[0].headers["x-context7-research-preview"]).toBeUndefined();
     if (transportKind === "http") {
       expect(apiCalls[0].headers["mcp-client-ip-assertion"]).toMatch(/^v1:/);
       expect(