Context7 Platform -- Up-to-date docs for AI agents
CTX7-3207: Update MCP SDK to 2.3.1, add list cache hints, flag resolve errors, drain HTTP on shutdown (#3435)
Enes Gules1b00727f345b
diff --git a/.changeset/mcp-sdk-2-3-cache-hints.md b/.changeset/mcp-sdk-2-3-cache-hints.mdnew file mode 100644index 00000000..8d2248b7--- /dev/null+++ b/.changeset/mcp-sdk-2-3-cache-hints.md@@ -0,0 +1,7 @@+---+"@upstash/context7-mcp": patch+---++Update the MCP SDK to `@modelcontextprotocol/server` 2.3.1 and `@modelcontextprotocol/node` 2.1.1, which converts tool schemas lazily, so each per-request server costs less to build. On the 2026-07-28 protocol, `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list` and `server/discover` now return `ttlMs: 3600000` and `cacheScope: "public"`, so clients can reuse them for an hour instead of listing on every request. `resolve-library-id` now sets `isError: true` when the library search fails; a search with no matches is still a normal result.++On SIGTERM the HTTP server now finishes the requests on open connections before it closes the MCP handler, and answers them with `Connection: close`. Before, those requests got HTTP 499 or 500 from the closed handler, and the shutdown hit its 5 s limit and exited with code 1. The SDK's rejections of malformed client requests are now logged as one line without a stack trace.diff --git a/packages/mcp/package.json b/packages/mcp/package.jsonindex 4d41c775..37f2758f 100644--- a/packages/mcp/package.json+++ b/packages/mcp/package.json@@ -46,8 +46,8 @@},"homepage": "https://github.com/upstash/context7#readme","dependencies": {- "@modelcontextprotocol/node": "2.1.0",- "@modelcontextprotocol/server": "2.2.0",+ "@modelcontextprotocol/node": "2.1.1",+ "@modelcontextprotocol/server": "2.3.1","@opentelemetry/api": "^1.9.1","@opentelemetry/exporter-prometheus": "^0.222.0","@opentelemetry/instrumentation-runtime-node": "^0.35.0",@@ -61,7 +61,7 @@"zod": "^4.6.5"},"devDependencies": {- "@modelcontextprotocol/client": "2.2.0",+ "@modelcontextprotocol/client": "2.3.1","@opentelemetry/context-async-hooks": "^2.11.0","@opentelemetry/core": "^2.11.0","@opentelemetry/sdk-trace-base": "^2.11.0",diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex b9ac7b7e..07149e75 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -62,6 +62,7 @@ import { parseOAuthAudienceEnforcement } from "./lib/oauth-audience.js";const DEFAULT_PORT = 3000;const OAUTH_METADATA_TIMEOUT_MS = 10_000;const CLAUDE_CODE_PLUGIN = "claude-code-plugin";+const STATIC_LIST_CACHE_HINT = { ttlMs: 3_600_000, cacheScope: "public" } as const;type McpInstrumentation = NonNullable<Awaited<ReturnType<typeof initializeTelemetry>>>;let mcpInstrumentation: McpInstrumentation | undefined;@@ -277,6 +278,17 @@ function createMcpServer(mcpContext: McpRequestContext) {prompts: { listChanged: false },resources: { listChanged: false, subscribe: false },},+ // These results are the same for every caller and change only on deploy, so+ // clients may reuse them for an hour instead of listing on every request.+ // After a deploy that changes a tool schema, clients can still call with the+ // old schema for that hour: keep old argument names accepted (aliasArgs).+ cacheHints: {+ "tools/list": STATIC_LIST_CACHE_HINT,+ "prompts/list": STATIC_LIST_CACHE_HINT,+ "resources/list": STATIC_LIST_CACHE_HINT,+ "resources/templates/list": STATIC_LIST_CACHE_HINT,+ "server/discover": STATIC_LIST_CACHE_HINT,+ },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, 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, writing scripts from scratch, debugging business logic, code review, or general programming concepts.`,@@ -359,6 +371,8 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot ftext,},],+ // Same rule as query-docs: an upstream failure is an error, an empty match is not.+ ...(searchResponse.error ? { isError: true } : {}),};}@@ -458,10 +472,14 @@ async function main() {// then walks the chain right-to-left and ignores attacker-added prefixes.app.set("trust proxy", ["loopback", "linklocal", "uniquelocal", "100.64.0.0/10"]);+ // Node keeps serving requests on kept-alive sockets after server.close(),+ // so during shutdown every response asks the gateway to reconnect elsewhere.+ let shuttingDown = false;// Registered ahead of the MCP router so its error responses carry the CORS// headers too; browser clients would otherwise see a CORS failure instead// of the status.app.use((req: express.Request, res: express.Response, next: express.NextFunction) => {+ if (shuttingDown) res.setHeader("Connection", "close");res.setHeader("Access-Control-Allow-Origin", "*");res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS,DELETE");// Mcp-Method / Mcp-Name are the SEP-2243 standard headers 2026-07-28@@ -524,7 +542,16 @@ async function main() {// 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),+ // The SDK reports each 4xx answer to a malformed client request as a new+ // Error whose stack only names SDK internals, so those log+ // their message alone. If the SDK rewords them, the stacks come back.+ onerror: (error) =>+ console.error(+ "MCP handler error:",+ error instanceof Error && /^(Rejected |Unsupported Media Type)/.test(error.message)+ ? error.message+ : error+ ),});const mcpHandler = mcpInstrumentation? mcpInstrumentation.instrumentHttpHandler(rawMcpHandler)@@ -741,25 +768,23 @@ async function main() {installProcessShutdown({close: async () => {+ shuttingDown = true;const server = activeHttpServer;- const operations: Promise<void>[] = [mcpHandler.close()];+ // Drain HTTP before closing the MCP handler: requests that still+ // arrive on open sockets would otherwise get a 500 from the closed+ // handler.if (server) {- operations.unshift(- new Promise<void>((resolve, reject) => {- server.close((error) => {- if (error) reject(error);- else resolve();- });- })- );- }- const results = await Promise.allSettled(operations);- const failures = results- .filter((result): result is PromiseRejectedResult => result.status === "rejected")- .map((result) => result.reason);- if (failures.length > 0) {- throw new AggregateError(failures, "MCP HTTP server failed to close cleanly");+ // A response that began before SIGTERM has no Connection: close, so+ // its socket then idles for keepAliveTimeout (5 s by default) and+ // server.close() waits for it. Node reads the timeout when a socket+ // goes idle, so this also covers responses already running.+ server.keepAliveTimeout = 1_000;+ await new Promise<void>((resolve, reject) => {+ server.close((error) => (error ? reject(error) : resolve()));+ server.closeIdleConnections();+ });}+ await mcpHandler.close();},},{diff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.tsindex 1b547f0c..0ce99edd 100644--- a/packages/mcp/test/integration.test.ts+++ b/packages/mcp/test/integration.test.ts@@ -24,6 +24,7 @@ const STUB_DOCS = "stub docs text";const EMPTY_CONTEXT_QUERY = "force-empty-context";const NO_RESULTS_QUERY = "force-no-results";const UPSTREAM_ERROR_QUERY = "force-upstream-error";+const SLOW_CONTEXT_QUERY = "force-slow-context";const INVALID_JSON_QUERY = "force-invalid-json";const CLIENT_IP_ASSERTION_KEY = "0123456789abcdef".repeat(4);const INVALID_OAUTH_TOKEN_BODY = {@@ -155,6 +156,10 @@ function startStubApi(): Promise<string> {return;}res.setHeader("Content-Type", "text/plain");+ if (url.searchParams.get("query") === SLOW_CONTEXT_QUERY) {+ setTimeout(() => res.end(STUB_DOCS), 500);+ return;+ }res.end(url.searchParams.get("query") === EMPTY_CONTEXT_QUERY ? "" : STUB_DOCS);} else {res.statusCode = 404;@@ -240,6 +245,91 @@ test("reports the bound port when port zero requests an ephemeral port", async (}});+// A modern query-docs call over a caller-chosen agent, so tests control socket reuse.+function callQueryDocsOver(url: string, agent: http.Agent, query: string) {+ return new Promise<{ status: number; connection: string | undefined }>((resolve, reject) => {+ const req = http.request(+ url,+ {+ method: "POST",+ agent,+ headers: {+ "content-type": "application/json",+ accept: "application/json, text/event-stream",+ authorization: "Bearer ctx7sk-local-test",+ "mcp-protocol-version": "2026-07-28",+ "mcp-method": "tools/call",+ "mcp-name": "query-docs",+ },+ },+ (res) => {+ res.resume();+ res.on("end", () =>+ resolve({ status: res.statusCode!, connection: res.headers.connection })+ );+ }+ );+ req.on("error", reject);+ req.end(+ JSON.stringify({+ jsonrpc: "2.0",+ id: 1,+ method: "tools/call",+ params: {+ name: "query-docs",+ arguments: { libraryId: "/vercel/next.js", query },+ _meta: {+ "io.modelcontextprotocol/protocolVersion": "2026-07-28",+ "io.modelcontextprotocol/clientCapabilities": {},+ },+ },+ })+ );+ });+}++describe("HTTP shutdown", () => {+ test("serves requests that arrive on a kept-alive socket during shutdown", async () => {+ const { child, url } = await startHttpChild({ port: 0 });+ const exited = new Promise<number | null>((resolve) => child.once("exit", resolve));+ // One socket, so the second request reuses the connection of the first.+ const agent = new http.Agent({ keepAlive: true, maxSockets: 1 });+ try {+ const inFlight = callQueryDocsOver(url, agent, SLOW_CONTEXT_QUERY);+ await new Promise((resolve) => setTimeout(resolve, 100));+ child.kill("SIGTERM");+ // Queued behind the in-flight call, so it reaches the server after SIGTERM.+ const afterSignal = callQueryDocsOver(url, agent, "app router");++ expect((await inFlight).status).toBe(200);+ expect(await afterSignal).toEqual({ status: 200, connection: "close" });+ expect(await exited).toBe(0);+ } finally {+ agent.destroy();+ child.kill();+ }+ });++ test("exits cleanly when a request in flight at SIGTERM leaves its socket open", async () => {+ const { child, url } = await startHttpChild({ port: 0 });+ const exited = new Promise<number | null>((resolve) => child.once("exit", resolve));+ const agent = new http.Agent({ keepAlive: true });+ try {+ const inFlight = callQueryDocsOver(url, agent, SLOW_CONTEXT_QUERY);+ await new Promise((resolve) => setTimeout(resolve, 100));+ child.kill("SIGTERM");++ // The response began before SIGTERM, so it keeps the socket alive and the+ // client sends nothing more; shutdown must still finish inside its limit.+ expect(await inFlight).toEqual({ status: 200, connection: "keep-alive" });+ expect(await exited).toBe(0);+ } finally {+ agent.destroy();+ child.kill();+ }+ });+});+async function connect(transportKind: "http" | "stdio", era: "modern" | "legacy") {const client = new Client({ name: "test-harness", version: "1.0.0" },@@ -720,6 +810,20 @@ describe.each([expect(text).toContain("stub upstream failure");});+ test("flags a failed resolve-library-id search as an error, not an empty match", async () => {+ const failed = await client.callTool({+ name: "resolve-library-id",+ arguments: { libraryName: "Next.js", query: INVALID_JSON_QUERY },+ });+ expect(failed.isError).toBe(true);++ const empty = await client.callTool({+ name: "resolve-library-id",+ arguments: { libraryName: "does-not-exist", query: NO_RESULTS_QUERY },+ });+ expect(empty.isError).toBeFalsy();+ });+test("calls resolve-library-id end to end", async () => {const result = await client.callTool({name: "resolve-library-id",diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex efc0e654..22b0e28f 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -152,11 +152,11 @@ importers:packages/mcp:dependencies:'@modelcontextprotocol/node':- specifier: 2.1.0- version: 2.1.0(@modelcontextprotocol/[email protected])([email protected])+ specifier: 2.1.1+ version: 2.1.1(@modelcontextprotocol/[email protected])'@modelcontextprotocol/server':- specifier: 2.2.0- version: 2.2.0+ specifier: 2.3.1+ version: 2.3.1'@opentelemetry/api':specifier: ^1.9.1version: 1.9.1@@ -192,8 +192,8 @@ importers:version: 4.6.5devDependencies:'@modelcontextprotocol/client':- specifier: 2.2.0- version: 2.2.0+ specifier: 2.3.1+ version: 2.3.1'@opentelemetry/context-async-hooks':specifier: ^2.11.0version: 2.11.0(@opentelemetry/[email protected])@@ -1386,23 +1386,19 @@ packages:resolution: {integrity: sha512-ABnA53mdfkGZwOFUdZNv2S0CWGO/EIuPj8Vv9xmBFmSYg/qFc7ihO6q5FcQjvoE67kZpWkEc4AhD6B/os04yuA==}engines: {node: '>= 10'}- '@modelcontextprotocol/[email protected]':- resolution: {integrity: sha512-LxCou/CSYQ6dwEnjhLZY0KnEuc8V4UJ3IEQCl/uR2yHobSQIEdJKUlKLRYRF5i5FqRGHy1eK7une3aAWDHLtig==}+ '@modelcontextprotocol/[email protected]':+ resolution: {integrity: sha512-mIGZXpHsjnZ6lD+gD/WCMpR5k8yVQQ8nNFH1N0Srf7AvnwTUMYD6pvTY8ng2+He5FfV7YMZLmrjL7cLa/cc3dQ==}engines: {node: '>=20'}- '@modelcontextprotocol/[email protected]':- resolution: {integrity: sha512-iLhmprRmWI8EcosOA3wVvww22z02NkgqhV4fBH6f/odQBsi7xnJc0HGmi21yWO+/iKw2yzqVE127Zhna5/+JXw==}+ '@modelcontextprotocol/[email protected]':+ resolution: {integrity: sha512-laVmIhPGpWi7rG9q+0UigblRN0Hws/Yjlb6qLFtVqryXVLkc4h+yN8z731POD2LnAGQlFe7/tXhUm7Bi0YB91g==}engines: {node: '>=20'}- '@modelcontextprotocol/[email protected]':- resolution: {integrity: sha512-6xg3iWVcOfiL8Y7rI6xUqXD0lI2AY5q3djsa/cOi1IJUSwx06t0gvhSwU/6mIIohrFlt40/ANUG56DQ0HLhILQ==}+ '@modelcontextprotocol/[email protected]':+ resolution: {integrity: sha512-EY92OAXN2xYL7tNS/MVsWJW1v8VHAPwl9B4Ca3pCrjmvqyC+S1C/6UHsMxF2GoFPraS5Yyg56vFz9brVpFojMA==}engines: {node: '>=20'}peerDependencies:- '@modelcontextprotocol/server': ^2.1.0- hono: ^4.11.4- peerDependenciesMeta:- hono:- optional: true+ '@modelcontextprotocol/server': ^2.3.0'@modelcontextprotocol/[email protected]':resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}@@ -1414,8 +1410,8 @@ packages:'@cfworker/json-schema':optional: true- '@modelcontextprotocol/[email protected]':- resolution: {integrity: sha512-qFnltjus6Gk8Lx6J1w2RXmr3YPN22MNT6qD6zjAkaiWIlFIFxWClz0rXHNuJF/KSUyn5YGhkSvXkWDbQHVLFEQ==}+ '@modelcontextprotocol/[email protected]':+ resolution: {integrity: sha512-e59MfWuSssj6DoQ96JCTqdW1AXT5/XtnTl0WWd6MU1Ka434fFUGGosCLJbGNySDhHGvxQWoRWK137FXYFkYNWw==}engines: {node: '>=20'}'@msgpackr-extract/[email protected]':@@ -2173,9 +2169,6 @@ packages:resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==}- resolution: {integrity: sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==}-resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==}@@ -2561,6 +2554,10 @@ packages:resolution: {integrity: sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==}engines: {node: '>=18.0.0'}+ resolution: {integrity: sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ==}+ engines: {node: '>=18.0.0'}+resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}engines: {node: '>=18.0.0'}@@ -4952,32 +4949,31 @@ snapshots:'@mariozechner/clipboard-win32-x64-msvc': 0.3.9optional: true- '@modelcontextprotocol/[email protected]':+ '@modelcontextprotocol/[email protected]':dependencies:- '@modelcontextprotocol/core': 2.2.0+ '@modelcontextprotocol/core': 2.3.1cross-spawn: 7.0.6eventsource: 3.0.7- eventsource-parser: 3.0.6+ eventsource-parser: 3.1.1jose: 6.2.12pkce-challenge: 5.0.0zod: 4.6.5- '@modelcontextprotocol/[email protected]':+ '@modelcontextprotocol/[email protected]':dependencies:zod: 4.6.5- '@modelcontextprotocol/[email protected](@modelcontextprotocol/[email protected])([email protected])':+ '@modelcontextprotocol/[email protected](@modelcontextprotocol/[email protected])':dependencies:'@hono/node-server': 1.19.14([email protected])- '@modelcontextprotocol/server': 2.2.0- optionalDependencies:+ '@modelcontextprotocol/server': 2.3.1hono: 4.12.23'@modelcontextprotocol/[email protected]([email protected])':dependencies:'@hono/node-server': 1.19.14([email protected])- ajv: 8.17.1- ajv-formats: 3.0.1([email protected])+ ajv: 8.20.0+ ajv-formats: 3.0.1([email protected])content-type: 1.0.5cors: 2.8.5cross-spawn: 7.0.6@@ -4996,9 +4992,9 @@ snapshots:- supports-coloroptional: true- '@modelcontextprotocol/[email protected]':+ '@modelcontextprotocol/[email protected]':dependencies:- '@modelcontextprotocol/core': 2.2.0+ '@modelcontextprotocol/core': 2.3.1zod: 4.6.5'@msgpackr-extract/[email protected]':@@ -5815,11 +5811,6 @@ snapshots:'@opentelemetry/api': 1.9.0zod: 4.6.5- optionalDependencies:- ajv: 8.17.1- optional: true-optionalDependencies:ajv: 8.20.0@@ -5831,14 +5822,6 @@ snapshots:json-schema-traverse: 0.4.1uri-js: 4.4.1- dependencies:- fast-deep-equal: 3.1.3- fast-uri: 3.1.0- json-schema-traverse: 1.0.0- require-from-string: 2.0.2- optional: true-dependencies:fast-deep-equal: 3.1.3@@ -6281,9 +6264,11 @@ snapshots:+ [email protected]: {}+dependencies:- eventsource-parser: 3.0.6+ eventsource-parser: 3.1.1