Context7 Platform -- Up-to-date docs for AI agents
fix(mcp): stream tool-call responses so headers flush before 60s (#2520)
Fahreddin Özcan772da3a1646c
diff --git a/.changeset/stream-mcp-tool-responses.md b/.changeset/stream-mcp-tool-responses.mdnew file mode 100644index 00000000..276192b3--- /dev/null+++ b/.changeset/stream-mcp-tool-responses.md@@ -0,0 +1,5 @@+---+"@upstash/context7-mcp": patch+---++Stream MCP tool responses over SSE so HTTP headers flush before client `fetch` timeouts. Switching `enableJsonResponse` to `false` makes the SDK return the HTTP response synchronously after request validation, so headers are sent in milliseconds instead of being buffered until the tool completes. This fixes clients that cap the underlying `fetch` waiting for headers (e.g., Claude Code's 60s `wrapFetchWithTimeout`).diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex 54758b42..73bd0ae7 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -254,7 +254,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.-Do not call this tool more than 3 times per question.`,+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()@@ -266,6 +266,12 @@ Do not call this tool more than 3 times per 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,@@ -274,17 +280,49 @@ Do not call this tool more than 3 times per question.`,idempotentHint: true,},},- async ({ query, libraryId }) => {- const response = await fetchLibraryContext({ query, libraryId }, getClientContext());+ 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);+ }- return {- content: [- {- type: "text",- text: response.data,- },- ],- };+ try {+ const response = await fetchLibraryContext(+ { query, libraryId, researchMode },+ getClientContext()+ );++ return {+ content: [+ {+ type: "text",+ text: response.data,+ },+ ],+ };+ } finally {+ if (progressInterval) clearInterval(progressInterval);+ }});@@ -400,9 +438,14 @@ async function main() {transport: "http",};+ // 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.const transport = new StreamableHTTPServerTransport({sessionIdGenerator: undefined,- enableJsonResponse: true,+ enableJsonResponse: false,});res.on("close", () => {