fix(mcp): harden discovery caching + reserved-path guard (review)

- Discovery docs: when the advertised origin is derived from the request Host
  (no QVERIS_MCP_PUBLIC_URL), respond with Cache-Control: no-store + Vary so a
  shared cache can't be poisoned to serve a cross-host remote URL. With a
  configured public origin the response is host-independent and stays cacheable.
- Warn at startup if QVERIS_MCP_HTTP_PATH collides with a reserved public path
  (/health or a discovery path), which would shadow the MCP transport.

Author: linfangw

packages/mcp/src/http.test.ts

@@ -277,6 +277,9 @@ describe('startHttpServer (end-to-end over Streamable HTTP)', () => {
     expect(res.status).toBe(200);
     expect(res.headers.get('content-type')).toContain('application/mcp-server-card+json');
     expect(res.headers.get('access-control-allow-origin')).toBe('*');
+    // Host-derived origin must not be cached cross-host (poisoning guard).
+    expect(res.headers.get('cache-control')).toContain('no-store');
+    expect(res.headers.get('vary')).toContain('Host');
     const card = (await res.json()) as Record<string, unknown>;
     expect(card.name).toBe('io.github.QVerisAI/mcp');
     expect(card.version).toBe('9.9.9');
@@ -314,6 +317,8 @@ describe('startHttpServer (end-to-end over Streamable HTTP)', () => {
   it('honors QVERIS_MCP_PUBLIC_URL in discovery URLs (behind a proxy)', async () => {
     await startServer({ QVERIS_MCP_PUBLIC_URL: 'https://mcp.example.com' }, CARD_INFO);
     const res = await fetch(`http://127.0.0.1:${running!.port}/mcp/server-card`);
+    // A configured public origin is host-independent, so it's freely cacheable.
+    expect(res.headers.get('cache-control')).toContain('public');
     const card = (await res.json()) as { remotes: Array<{ url: string }> };
     expect(card.remotes[0].url).toBe('https://mcp.example.com/mcp');
   });

packages/mcp/src/http.ts

@@ -283,6 +283,15 @@ export async function startHttpServer(
         'Ensure an external auth layer protects the endpoint.\n',
     );
   }
+  // The reserved public paths are matched before the transport path; a custom
+  // QVERIS_MCP_HTTP_PATH set to one of them would shadow the MCP endpoint.
+  const reservedPaths = cardInfo ? ['/health', CATALOG_PATH, `${config.path}/server-card`] : ['/health'];
+  if (reservedPaths.includes(config.path)) {
+    logger(
+      `[qveris] WARNING: QVERIS_MCP_HTTP_PATH="${config.path}" collides with a reserved ` +
+        'endpoint (health/discovery) and would shadow the MCP transport; choose a different path.\n',
+    );
+  }
 
   const transports = new Map<string, StreamableHTTPServerTransport>();
   const lastSeen = new Map<string, number>();
@@ -372,7 +381,13 @@ export async function startHttpServer(
         }
         if (req.method === 'GET') {
           const origin = requestOrigin(req, config.publicUrl);
-          const cache = { 'Cache-Control': 'public, max-age=3600' };
+          // With a configured public origin the response is host-independent and
+          // freely cacheable. When the origin is derived from the request Host,
+          // don't let a shared cache serve it cross-host (cache-poisoning): mark
+          // it no-store and Vary on the headers it depends on.
+          const cache: Record<string, string> = config.publicUrl
+            ? { 'Cache-Control': 'public, max-age=3600' }
+            : { 'Cache-Control': 'no-store', Vary: 'Host, X-Forwarded-Proto' };
           if (url.pathname === cardPath) {
             const card = buildServerCard(cardInfo, `${origin}${config.path}`);
             writeJson(res, 200, card, { ...cors, ...cache, 'Content-Type': SERVER_CARD_MEDIA_TYPE });