fix(mcp): fail-closed on reserved-path collision; drop dead reserved entry (review)

- Reserved-path collision now throws (refuses to start) instead of warning, so
  a QVERIS_MCP_HTTP_PATH set to /health or the catalog path can't silently start
  a server whose MCP endpoint is shadowed (every POST -> 405). Consistent with
  the fail-closed non-loopback-without-auth check.
- Drop the dead '${config.path}/server-card' reserved entry — it's always longer
  than config.path and could never match. Added a collision test.

Author: linfangw

packages/mcp/src/http.test.ts

@@ -305,6 +305,16 @@ describe('startHttpServer (end-to-end over Streamable HTTP)', () => {
     await res.text();
   });
 
+  it('refuses to start when the HTTP path collides with a reserved endpoint', async () => {
+    const config = resolveTransportConfig(
+      { QVERIS_MCP_TRANSPORT: 'http', QVERIS_MCP_HTTP_PORT: '0', QVERIS_MCP_HTTP_PATH: '/health' },
+      [],
+    );
+    await expect(
+      startHttpServer(config, (sessionId) => createQverisServer(undefined, sessionId), CARD_INFO),
+    ).rejects.toThrow(/reserved endpoint/);
+  });
+
   it('does not serve discovery endpoints when no card info is provided', async () => {
     await startServer(); // no cardInfo
     const res = await fetch(`http://127.0.0.1:${running!.port}/mcp/server-card`, {

packages/mcp/src/http.ts

@@ -284,12 +284,15 @@ export async function startHttpServer(
     );
   }
   // 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'];
+  // QVERIS_MCP_HTTP_PATH set to one of them would shadow the MCP endpoint, so
+  // fail fast rather than start a silently-broken server (consistent with the
+  // fail-closed auth check above). The card path (config.path + '/server-card')
+  // can't equal config.path, so it isn't a collision candidate.
+  const reservedPaths = cardInfo ? ['/health', CATALOG_PATH] : ['/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',
+    throw new Error(
+      `Refusing to start: QVERIS_MCP_HTTP_PATH="${config.path}" collides with a reserved ` +
+        `endpoint (${reservedPaths.join(', ')}) and would shadow the MCP transport; choose a different path.`,
     );
   }