Context7 Platform -- Up-to-date docs for AI agents
Serve the MCP server card and fix README tool names (#3197)
Enes Gules72181dd4ac5b
diff --git a/.changeset/mcp-discovery-compat.md b/.changeset/mcp-discovery-compat.mdnew file mode 100644index 00000000..fd8ed81a--- /dev/null+++ b/.changeset/mcp-discovery-compat.md@@ -0,0 +1,5 @@+---+"@upstash/context7-mcp": patch+---++Serve a SEP-2127 server card at `/mcp/server-card`.diff --git a/packages/mcp/README.md b/packages/mcp/README.mdindex 679da158..2dbd2581 100644--- a/packages/mcp/README.md+++ b/packages/mcp/README.md@@ -1017,7 +1017,7 @@ Add the following configuration to the `mcp` section of your Copilot Coding Agen"headers": {"Authorization": "Bearer YOUR_API_KEY"},- "tools": ["get-library-docs", "resolve-library-id"]+ "tools": ["query-docs", "resolve-library-id"]}}}@@ -1042,7 +1042,7 @@ For more information, see the [official GitHub documentation](https://docs.githu"headers": {"Authorization": "Bearer YOUR_API_KEY"},- "tools": ["get-library-docs", "resolve-library-id"]+ "tools": ["query-docs", "resolve-library-id"]}}}@@ -1056,7 +1056,7 @@ Or, for a local server:"context7": {"type": "local","command": "npx",- "tools": ["get-library-docs", "resolve-library-id"],+ "tools": ["query-docs", "resolve-library-id"],"args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]}}@@ -1194,7 +1194,7 @@ Open the "Settings" page of the app, navigate to "Plugins," and enter the follow}```-Once saved, enter in the chat `get-library-docs` followed by your Context7 documentation ID (e.g., `get-library-docs /nuxt/ui`). More information is available on [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers). For BoltAI on iOS, [see this guide](https://docs.boltai.com/docs/boltai-mobile/mcp-servers).+Once saved, enter in the chat `query-docs` followed by your Context7 documentation ID (e.g., `query-docs /nuxt/ui how to set up a theme`). More information is available on [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers). For BoltAI on iOS, [see this guide](https://docs.boltai.com/docs/boltai-mobile/mcp-servers).</details>@@ -1391,11 +1391,13 @@ Context7 MCP provides the following tools that LLMs can use:- `resolve-library-id`: Resolves a general library name into a Context7-compatible library ID.- `libraryName` (required): The name of the library to search for+ - `query` (required): What you need the docs for, used to rank matches-- `get-library-docs`: Fetches documentation for a library using a Context7-compatible library ID.- - `context7CompatibleLibraryID` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`)- - `topic` (optional): Focus the docs on a specific topic (e.g., "routing", "hooks")- - `page` (optional, default 1): Page number for pagination (1-10). If the context is not sufficient, try page=2, page=3, etc. with the same topic.+- `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++`get-library-docs` was renamed to `query-docs`. Update client tool allowlists to use `query-docs`.## 🛟 Tipsdiff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex 1930ac5a..ff82d09f 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -27,6 +27,7 @@ import {OAUTH_AUTH_SERVER_URL,EMA_ISSUER,OPENAI_APPS_CHALLENGE_TOKEN,+ mcpServerCard,} 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";@@ -381,7 +382,7 @@ async function main() {// browser clients, so those are not needed.)res.setHeader("Access-Control-Allow-Headers",- "Content-Type, MCP-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization"+ "Content-Type, MCP-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization, If-None-Match");if (req.method === "OPTIONS") {res.sendStatus(200);@@ -529,6 +530,16 @@ async function main() {mcpRouter.all("/", (req, res) => handleMcpRequest(req, res));// OAuth-protected endpoint - requires authenticationmcpRouter.all("/oauth", (req, res) => handleMcpRequest(req, res));++ // SEP-2127 reserves `{streamable-http-url}/server-card`. Register it+ // before the /mcp router so it is not answered as MCP JSON-RPC.+ app.get("/mcp/server-card", (_req: express.Request, res: express.Response) => {+ res.setHeader("Content-Type", "application/mcp-server-card+json");+ res.setHeader("Cache-Control", "public, max-age=3600");+ res.setHeader("Access-Control-Expose-Headers", "ETag");+ // Express adds the ETag and answers a matching If-None-Match with 304.+ res.status(200).send(mcpServerCard());+ });app.use("/mcp", mcpRouter);app.get("/ping", (_req: express.Request, res: express.Response) => {diff --git a/packages/mcp/src/lib/constants.ts b/packages/mcp/src/lib/constants.tsindex f22cc9c3..f336ffb2 100644--- a/packages/mcp/src/lib/constants.ts+++ b/packages/mcp/src/lib/constants.ts@@ -33,3 +33,40 @@ export const EMA_ISSUER =process.env.EMA_ISSUER || process.env.AUTH_SERVER_URL || CONTEXT7_BASE_URL;export const EMA_JWKS_URL = process.env.EMA_JWKS_URL || `${CONTEXT7_API_BASE_URL}/oauth/ema-jwks`;export const OPENAI_APPS_CHALLENGE_TOKEN = process.env.OPENAI_APPS_CHALLENGE_TOKEN;++/** Describe the remote server using the experimental Server Card v1 schema. */+export function mcpServerCard(resourceUrl = RESOURCE_URL) {+ return {+ $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",+ name: "io.github.upstash/context7",+ title: "Context7",+ description:+ "Up-to-date, version-specific documentation and code examples for software libraries.",+ version: SERVER_VERSION,+ websiteUrl: "https://context7.com",+ icons: [{ src: "https://context7.com/context7-icon-green.png", mimeType: "image/png" }],+ remotes: [+ {+ type: "streamable-http",+ url: `${new URL(resourceUrl).origin}/mcp`,+ headers: [+ {+ name: "Authorization",+ description:+ "Optional. A Context7 API key from https://context7.com/dashboard raises the rate limit.",+ isRequired: false,+ isSecret: true,+ value: "Bearer {api_key}",+ variables: {+ api_key: {+ description: "Context7 API key",+ isSecret: true,+ placeholder: "ctx7sk-...",+ },+ },+ },+ ],+ },+ ],+ };+}diff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.tsindex cff8bf91..4292d0d0 100644--- a/packages/mcp/test/integration.test.ts+++ b/packages/mcp/test/integration.test.ts@@ -221,6 +221,42 @@ describe("OAuth discovery", () => {authorization_servers: ["https://clerk.context7.com", "https://context7.com"],});});++ test("serves the SEP-2127 server card at /mcp/server-card", async () => {+ const response = await fetch(new URL("/mcp/server-card", httpUrl));++ expect(response.status).toBe(200);+ expect(response.headers.get("content-type")).toMatch(/application\/mcp-server-card\+json/);+ const card = await response.json();+ expect(card).toMatchObject({+ $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",+ name: "io.github.upstash/context7",+ remotes: [{ type: "streamable-http", url: "https://mcp.context7.com/mcp" }],+ });+ expect(card.description.length).toBeLessThanOrEqual(100);+ expect(card.remotes[0].headers).toEqual([+ expect.objectContaining({ name: "Authorization", isRequired: false, isSecret: true }),+ ]);+ expect(response.headers.get("cache-control")).toBe("public, max-age=3600");+ expect(response.headers.get("access-control-expose-headers")).toBe("ETag");++ const etag = response.headers.get("etag");+ expect(etag).toBeTruthy();+ // node:http, because fetch adds Cache-Control: no-cache to conditional requests.+ const status = await new Promise<number | undefined>((resolve, reject) => {+ http+ .get(+ new URL("/mcp/server-card", httpUrl),+ { headers: { "If-None-Match": etag! } },+ (res) => {+ res.resume();+ resolve(res.statusCode);+ }+ )+ .on("error", reject);+ });+ expect(status).toBe(304);+ });});// A malformed body fails inside express.json(), which calls next(err). That