Context7 Platform -- Up-to-date docs for AI agents
CTX7-2472: Consume self-cancelling JSON-RPC batches (#3355)
Enes Gules7cbd5fd052cc
diff --git a/.changeset/mcp-reject-self-cancelling-batches.md b/.changeset/mcp-reject-self-cancelling-batches.mdnew file mode 100644index 00000000..721619bf--- /dev/null+++ b/.changeset/mcp-reject-self-cancelling-batches.md@@ -0,0 +1,5 @@+---+"@upstash/context7-mcp": patch+---++Consume request/cancellation pairs contained in the same JSON-RPC batch before dispatch. This prevents the legacy stateless HTTP transport from leaving the response stream open when cancellation suppresses the terminal protocol response.diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex 02a4fc19..27a39c4a 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -4,6 +4,7 @@ import { toNodeHandler } from "@modelcontextprotocol/node";import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";import {McpServer,+ PROTOCOL_VERSION_META_KEY,createMcpHandler,type McpRequestContext,type ServerContext,@@ -36,6 +37,7 @@ import {observeAuthentication,observeUpstreamRequest,recordAuthenticationEvent,+ recordSelfCancellingBatch,} from "./lib/telemetry-runtime.js";import { mcpBodyErrorHandler } from "./lib/mcp-body-error-handler.js";import {@@ -159,6 +161,77 @@ const QUERY_DOCS_ALIASES: AliasMap = {libraryId: ["context7CompatibleLibraryID", "libraryID", "libraryName"],};+type JsonRpcId = string | number;++function jsonRpcRequestId(message: unknown): JsonRpcId | undefined {+ if (!message || typeof message !== "object") return undefined;++ const candidate = message as Record<string, unknown>;+ if (+ candidate.jsonrpc === "2.0" &&+ typeof candidate.method === "string" &&+ (typeof candidate.id === "string" || typeof candidate.id === "number")+ ) {+ return candidate.id;+ }+}++function cancellationRequestId(message: unknown): JsonRpcId | undefined {+ if (!message || typeof message !== "object") return undefined;++ const candidate = message as Record<string, unknown>;+ if (+ candidate.jsonrpc !== "2.0" ||+ candidate.method !== "notifications/cancelled" ||+ "id" in candidate ||+ !candidate.params ||+ typeof candidate.params !== "object"+ ) {+ return undefined;+ }++ const requestId = (candidate.params as Record<string, unknown>).requestId;+ if (typeof requestId === "string" || typeof requestId === "number") return requestId;+}++/** True for a 2026-07-28 message: its `params._meta` names a protocol version. */+function hasProtocolVersionClaim(message: unknown): boolean {+ if (!message || typeof message !== "object") return false;+ const params = (message as Record<string, unknown>).params;+ if (!params || typeof params !== "object") return false;+ const meta = (params as Record<string, unknown>)._meta;+ return !!meta && typeof meta === "object" && PROTOCOL_VERSION_META_KEY in meta;+}++function filterBatchSelfCancellations(body: unknown): {+ body: unknown;+ removedSelfCancellation: boolean;+} {+ if (!Array.isArray(body)) return { body, removedSelfCancellation: false };+ // The SDK answers 400 to a batch with a 2026-07-28 element. Leave such a+ // batch whole, so removing a pair cannot hide that element from the SDK.+ if (body.some(hasProtocolVersionClaim)) return { body, removedSelfCancellation: false };++ const requestIds = new Set(body.map(jsonRpcRequestId).filter((id) => id !== undefined));+ const selfCancelledIds = new Set(+ body+ .map(cancellationRequestId)+ .filter((id): id is JsonRpcId => id !== undefined && requestIds.has(id))+ );+ if (selfCancelledIds.size === 0) return { body, removedSelfCancellation: false };++ return {+ body: body.filter((message) => {+ const requestId = jsonRpcRequestId(message);+ if (requestId !== undefined && selfCancelledIds.has(requestId)) return false;++ const cancelledId = cancellationRequestId(message);+ return cancelledId === undefined || !selfCancelledIds.has(cancelledId);+ }),+ removedSelfCancellation: true,+ };+}+// z.preprocess step that rewrites aliased arg names before validation. Living// in the schema keeps aliasing transport-agnostic: the SDK parses the wire// message (any transport, any protocol era) and runs this on validation.@@ -447,11 +520,10 @@ async function main() {// millisecond vector query (p100 ~28s), so no legitimate exchange needs a// heartbeat to stay alive — but a hung exchange kept "alive" by heartbeats// can never be reaped by the gateway's stream idle timeout. A batch- // carrying a request plus its own notifications/cancelled produces exactly- // that: per spec the cancelled request gets no response, the SDK transport- // then never closes the stream, and with heartbeats it survived until the- // gateway's 1200s hard cap (the 2026-08-11 outage). Silent hangs instead- // go idle and the gateway reaps them at streamIdleTimeout (300s).+ // carrying a request plus its own notifications/cancelled produced exactly+ // that (the 2026-08-11 outage); handleMcpRequest now consumes such pairs+ // before dispatch. Any other silent hang goes idle and the gateway reaps+ // it at streamIdleTimeout (300s) instead of its 1200s hard cap.const rawMcpHandler = createMcpHandler((mcpContext) => createMcpServer(mcpContext), {keepAliveMs: 0,onerror: (error) => console.error("MCP handler error:", error),@@ -497,6 +569,29 @@ async function main() {return;}+ // A cancelled request deliberately produces no protocol response, but+ // the SDK's legacy stateless transport still waits for one before it+ // closes the batch's POST stream. Consume request/cancellation pairs+ // that occur in the same batch before SDK dispatch. This applies the+ // cancellation without starting the tool and without leaving an ID in+ // the transport's response accounting. Only POST carries messages;+ // other methods keep the SDK's own method handling (405). A batch that+ // is fully consumed is answered here, before the SDK's Accept check.+ const filteredBody =+ req.method === "POST"+ ? filterBatchSelfCancellations(req.body)+ : { body: req.body, removedSelfCancellation: false };+ if (filteredBody.removedSelfCancellation) {+ recordSelfCancellingBatch(req.headers["user-agent"]);+ }+ if (+ filteredBody.removedSelfCancellation &&+ Array.isArray(filteredBody.body) &&+ filteredBody.body.length === 0+ ) {+ return res.status(202).end();+ }+const context: ClientContext = {clientIp: req.ip,apiKey,@@ -515,7 +610,7 @@ async function main() {});await requestContext.run(context, async () => {- await nodeHandler(req, res, req.body);+ await nodeHandler(req, res, filteredBody.body);});} catch (error) {console.error("Error handling MCP request:", error);diff --git a/packages/mcp/src/lib/telemetry-runtime.ts b/packages/mcp/src/lib/telemetry-runtime.tsindex 7b666f78..53b0255f 100644--- a/packages/mcp/src/lib/telemetry-runtime.ts+++ b/packages/mcp/src/lib/telemetry-runtime.ts@@ -106,6 +106,10 @@ export function recordAuthenticationEvent(observation: AuthenticationEventObservimplementation?.recordAuthenticationEvent(observation);}+export function recordSelfCancellingBatch(userAgent: string | undefined): void {+ implementation?.recordSelfCancellingBatch(userAgent);+}+export async function observeUpstreamRequest<T>(operationName: UpstreamOperation,request: () => Promise<Response>,diff --git a/packages/mcp/src/lib/telemetry.ts b/packages/mcp/src/lib/telemetry.tsindex 8942c10c..06ca0213 100644--- a/packages/mcp/src/lib/telemetry.ts+++ b/packages/mcp/src/lib/telemetry.ts@@ -61,6 +61,10 @@ function createInstruments() {description: "Number of hosted MCP authentication lifecycle events",unit: "{event}",}),+ selfCancellingBatches: meter.createCounter("context7.mcp.batches.self_cancelling", {+ description: "JSON-RPC batches in which a request was cancelled by the same batch",+ unit: "{batch}",+ }),authenticationDuration: meter.createHistogram("context7.mcp.authentication.duration", {description: "Duration of hosted MCP authentication decisions",unit: "s",@@ -256,6 +260,23 @@ export async function observeAuthentication<T extends AuthenticationObservation>}}+const MAX_BATCH_CLIENT_NAMES = 50;+const batchClientNames = new Set<string>();++/**+ * Counts a batch that cancelled its own request, by the product token of the+ * caller's User-Agent. The header is caller-controlled, so the label set is+ * capped per process; later names are counted as "other".+ */+export function recordSelfCancellingBatch(userAgent: string | undefined): void {+ let client = /^[\w.-]{1,40}/.exec(userAgent ?? "")?.[0].toLowerCase() ?? "unknown";+ if (!batchClientNames.has(client)) {+ if (batchClientNames.size >= MAX_BATCH_CLIENT_NAMES) client = "other";+ else batchClientNames.add(client);+ }+ getInstruments().selfCancellingBatches.add(1, { "user_agent.name": client });+}+export function recordAuthenticationEvent(observation: AuthenticationEventObservation): void {const attributes: Attributes = {"context7.authentication.enforcement": observation.enforcementMode,diff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.tsindex f415cd4a..1b547f0c 100644--- a/packages/mcp/test/integration.test.ts+++ b/packages/mcp/test/integration.test.ts@@ -466,6 +466,175 @@ describe("HTTP API key headers", () => {});});+describe("HTTP batch cancellation", () => {+ beforeEach(() => {+ requests.length = 0;+ });++ test("consumes a request cancelled by the same batch and closes promptly", async () => {+ const response = await fetch(httpUrl, {+ method: "POST",+ headers: {+ "content-type": "application/json",+ accept: "application/json, text/event-stream",+ authorization: "Bearer ctx7sk-local-test",+ },+ body: JSON.stringify([+ {+ jsonrpc: "2.0",+ id: 102,+ method: "tools/call",+ params: {+ name: "resolve-library-id",+ arguments: { query: "framework documentation", libraryName: "Next.js" },+ },+ },+ {+ jsonrpc: "2.0",+ method: "notifications/cancelled",+ params: { requestId: 102, reason: "regression-test" },+ },+ ]),+ signal: AbortSignal.timeout(1_000),+ });++ expect(response.status).toBe(202);+ expect(await response.text()).toBe("");+ expect(requests).toHaveLength(0);+ });++ test("returns responses for the uncancelled requests in a mixed batch", async () => {+ const response = await fetch(httpUrl, {+ method: "POST",+ headers: {+ "content-type": "application/json",+ accept: "application/json, text/event-stream",+ authorization: "Bearer ctx7sk-local-test",+ },+ body: JSON.stringify([+ {+ jsonrpc: "2.0",+ id: 104,+ method: "tools/call",+ params: {+ name: "resolve-library-id",+ arguments: { query: "cancelled", libraryName: "Cancelled.js" },+ },+ },+ {+ jsonrpc: "2.0",+ id: 105,+ method: "tools/call",+ params: {+ name: "resolve-library-id",+ arguments: { query: "framework documentation", libraryName: "Next.js" },+ },+ },+ {+ jsonrpc: "2.0",+ method: "notifications/cancelled",+ params: { requestId: 104, reason: "regression-test" },+ },+ ]),+ signal: AbortSignal.timeout(1_000),+ });++ expect(response.status).toBe(200);+ const responseText = await response.text();+ expect(responseText).not.toContain('"id":104');+ expect(responseText).toContain('"id":105');+ expect(requests.filter((request) => request.path === "/v2/libs/search")).toHaveLength(1);+ expect(requests[0].query.get("libraryName")).toBe("Next.js");+ });++ test("allows a cancellation for an ID outside the batch", async () => {+ const response = await fetch(httpUrl, {+ method: "POST",+ headers: {+ "content-type": "application/json",+ accept: "application/json, text/event-stream",+ authorization: "Bearer ctx7sk-local-test",+ },+ body: JSON.stringify([+ {+ jsonrpc: "2.0",+ id: 103,+ method: "tools/call",+ params: {+ name: "resolve-library-id",+ arguments: { query: "framework documentation", libraryName: "Next.js" },+ },+ },+ {+ jsonrpc: "2.0",+ method: "notifications/cancelled",+ params: { requestId: 999, reason: "different-request" },+ },+ ]),+ signal: AbortSignal.timeout(1_000),+ });++ expect(response.status).toBe(200);+ expect(await response.text()).toContain('"id":103');+ expect(requests.filter((request) => request.path === "/v2/libs/search")).toHaveLength(1);+ });++ test("leaves a batch with a 2026-07-28 element to the SDK, which rejects it", async () => {+ const modernParams = { _meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } };+ const response = await fetch(httpUrl, {+ method: "POST",+ headers: {+ "content-type": "application/json",+ accept: "application/json, text/event-stream",+ authorization: "Bearer ctx7sk-local-test",+ },+ body: JSON.stringify([+ { jsonrpc: "2.0", id: 107, method: "tools/list", params: modernParams },+ {+ jsonrpc: "2.0",+ method: "notifications/cancelled",+ params: { requestId: 107, reason: "regression-test" },+ },+ {+ jsonrpc: "2.0",+ id: 108,+ method: "tools/call",+ params: {+ name: "resolve-library-id",+ arguments: { query: "framework documentation", libraryName: "Next.js" },+ },+ },+ ]),+ signal: AbortSignal.timeout(1_000),+ });++ expect(response.status).toBe(400);+ expect(requests).toHaveLength(0);+ });++ test("keeps 405 for a self-cancelling batch sent with DELETE", async () => {+ const response = await fetch(httpUrl, {+ method: "DELETE",+ headers: {+ "content-type": "application/json",+ accept: "application/json, text/event-stream",+ authorization: "Bearer ctx7sk-local-test",+ },+ body: JSON.stringify([+ { jsonrpc: "2.0", id: 106, method: "tools/list" },+ {+ jsonrpc: "2.0",+ method: "notifications/cancelled",+ params: { requestId: 106, reason: "regression-test" },+ },+ ]),+ signal: AbortSignal.timeout(1_000),+ });++ expect(response.status).toBe(405);+ });+});+describe.each([["http", "modern"],["http", "legacy"],