feat(mcp): Server Card + Catalog discovery documents (#107)

Adds connection-less discovery metadata to the Streamable HTTP transport
(SEP-2127 / SEP-1649) so registries and crawlers can learn about the server
before connecting:

- Server Card at GET {path}/server-card (media type
  application/mcp-server-card+json) — reverse-DNS name, version, description,
  and the streamable-http remote endpoint with supportedProtocolVersions.
- MCP Catalog at GET /.well-known/mcp/catalog.json — site-wide index whose
  entry points at the Server Card (urn:air:{publisher}:{name}).

Both endpoints are public (unauthenticated, CORS-enabled, cacheable) and served
before the auth check, like robots.txt / OAuth metadata. URLs derive from
QVERIS_MCP_PUBLIC_URL or the request (honoring X-Forwarded-Proto) so they're
correct behind a TLS proxy. Card metadata comes from package.json (mcpName,
version, description, homepage, repository) + the SDK's SUPPORTED_PROTOCOL_VERSIONS.

Pure builders in server-card.ts are unit-tested; the endpoints are covered
end-to-end (media type, CORS, preflight, public access under an auth token,
PUBLIC_URL override, 404 when no card info). 98 MCP tests pass. Full OAuth 2.1
remains the last #107 follow-up.

Author: linfangw

packages/mcp/README.md

@@ -296,7 +296,11 @@ npx -y @qverisai/mcp
 - **Inbound auth:** set `QVERIS_MCP_HTTP_AUTH_TOKEN` to require `Authorization: Bearer <token>` on the MCP endpoint. The server **refuses to start** when binding a non-loopback host without a token, unless you set `QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED=true` to delegate auth to an external proxy/gateway. Your `QVERIS_API_KEY` is the server's *outbound* credential to QVeris — it is **not** an inbound check, so anyone reaching an unauthenticated endpoint would spend your credits.
 - DNS-rebinding protection is **on by default** (localhost + the bound host/port are allow-listed). When exposing the server publicly, add your public host via `QVERIS_MCP_ALLOWED_HOSTS`.
 - Requests are capped at 4 MiB by default (`QVERIS_MCP_MAX_BODY_BYTES`), and idle sessions are evicted after 5 minutes (`QVERIS_MCP_SESSION_TIMEOUT_MS`).
-- Full OAuth 2.1 and a `.well-known` MCP Server Card are tracked as follow-ups in [#107](https://github.com/QVerisAI/qveris-agent-toolkit/issues/107).
+- **Discovery:** registries and crawlers can learn about the server without connecting:
+  - **Server Card** at `GET {path}/server-card` (default `/mcp/server-card`), media type `application/mcp-server-card+json` — server identity, version, and the remote endpoint.
+  - **MCP Catalog** at `GET /.well-known/mcp/catalog.json` — a site-wide index pointing at the Server Card.
+  - Both are public (unauthenticated, CORS-enabled), even when an auth token is set. Behind a TLS proxy, set `QVERIS_MCP_PUBLIC_URL` (or send `X-Forwarded-Proto`) so the advertised URLs use your public origin.
+- Full OAuth 2.1 authorization is tracked as a follow-up in [#107](https://github.com/QVerisAI/qveris-agent-toolkit/issues/107).
 
 ## Environment Variables
 
@@ -317,6 +321,7 @@ npx -y @qverisai/mcp
 | `QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED` | | `true` to allow a non-loopback bind without a token (auth delegated externally) |
 | `QVERIS_MCP_MAX_BODY_BYTES` | | Max request body size in bytes (default `4194304`) |
 | `QVERIS_MCP_SESSION_TIMEOUT_MS` | | Idle session TTL in ms (default `300000`) |
+| `QVERIS_MCP_PUBLIC_URL` | | Public origin advertised in discovery documents (e.g. `https://mcp.example.com`) |
 
 ## Region
 

packages/mcp/src/http.test.ts

@@ -105,14 +105,30 @@ describe('startHttpServer (end-to-end over Streamable HTTP)', () => {
     running = undefined;
   });
 
-  async function startServer(extraEnv: Record<string, string> = {}): Promise<void> {
+  const CARD_INFO = {
+    name: 'io.github.QVerisAI/mcp',
+    version: '9.9.9',
+    description: 'QVeris MCP server.',
+    title: 'QVeris',
+    websiteUrl: 'https://qveris.ai',
+    protocolVersions: ['2025-11-25'],
+  };
+
+  async function startServer(
+    extraEnv: Record<string, string> = {},
+    cardInfo?: typeof CARD_INFO,
+  ): Promise<void> {
     const config = resolveTransportConfig(
       { QVERIS_MCP_TRANSPORT: 'http', QVERIS_MCP_HTTP_PORT: '0', ...extraEnv },
       [],
     );
     // Server has no QVERIS_API_KEY, so tool listing works but calls return an
     // actionable error — exactly the credential-less path we want to exercise.
-    running = await startHttpServer(config, (sessionId) => createQverisServer(undefined, sessionId));
+    running = await startHttpServer(
+      config,
+      (sessionId) => createQverisServer(undefined, sessionId),
+      cardInfo,
+    );
   }
 
   async function connectClient(
@@ -251,4 +267,54 @@ describe('startHttpServer (end-to-end over Streamable HTTP)', () => {
     expect(res.status).toBe(200);
     await res.text();
   });
+
+  it('serves the Server Card unauthenticated with the right media type and CORS', async () => {
+    // A token is set to prove the card is reachable WITHOUT credentials.
+    await startServer({ QVERIS_MCP_HTTP_AUTH_TOKEN: 'tok' }, CARD_INFO);
+    const res = await fetch(`http://127.0.0.1:${running!.port}/mcp/server-card`, {
+      headers: { Accept: 'application/mcp-server-card+json' },
+    });
+    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('*');
+    const card = (await res.json()) as Record<string, unknown>;
+    expect(card.name).toBe('io.github.QVerisAI/mcp');
+    expect(card.version).toBe('9.9.9');
+    expect((card.remotes as Array<{ url: string }>)[0].url).toBe(`http://127.0.0.1:${running!.port}/mcp`);
+  });
+
+  it('serves the MCP Catalog pointing at the Server Card', async () => {
+    await startServer({}, CARD_INFO);
+    const res = await fetch(`http://127.0.0.1:${running!.port}/.well-known/mcp/catalog.json`);
+    expect(res.status).toBe(200);
+    const catalog = (await res.json()) as { specVersion: string; entries: Array<Record<string, string>> };
+    expect(catalog.specVersion).toBe('draft');
+    expect(catalog.entries[0].mediaType).toBe('application/mcp-server-card+json');
+    expect(catalog.entries[0].url).toBe(`http://127.0.0.1:${running!.port}/mcp/server-card`);
+    expect(catalog.entries[0].identifier).toBe('urn:air:qveris.ai:mcp');
+  });
+
+  it('answers a CORS preflight for the Server Card', async () => {
+    await startServer({}, CARD_INFO);
+    const res = await fetch(`http://127.0.0.1:${running!.port}/mcp/server-card`, { method: 'OPTIONS' });
+    expect(res.status).toBe(204);
+    expect(res.headers.get('access-control-allow-methods')).toContain('GET');
+    await res.text();
+  });
+
+  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`, {
+      headers: { Accept: 'application/mcp-server-card+json' },
+    });
+    expect(res.status).toBe(404);
+    await res.text();
+  });
+
+  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`);
+    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

@@ -30,6 +30,14 @@ import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 
+import {
+  buildCatalog,
+  buildServerCard,
+  CATALOG_PATH,
+  SERVER_CARD_MEDIA_TYPE,
+  type ServerCardInfo,
+} from './server-card.js';
+
 /** Transport selection plus the HTTP-mode settings. */
 export interface TransportConfig {
   mode: 'stdio' | 'http';
@@ -53,6 +61,8 @@ export interface TransportConfig {
   maxBodyBytes: number;
   /** Idle session TTL in ms; stale sessions are closed and evicted. */
   sessionTimeoutMs: number;
+  /** Public origin (e.g. behind a TLS proxy) used in discovery documents. */
+  publicUrl?: string;
 }
 
 const DEFAULT_PORT = 3000;
@@ -171,9 +181,21 @@ export function resolveTransportConfig(
     allowUnauthenticated: parseBool(env.QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED, false),
     maxBodyBytes: parsePositiveInt(env.QVERIS_MCP_MAX_BODY_BYTES, DEFAULT_MAX_BODY_BYTES),
     sessionTimeoutMs: parsePositiveInt(env.QVERIS_MCP_SESSION_TIMEOUT_MS, DEFAULT_SESSION_TIMEOUT_MS),
+    publicUrl: env.QVERIS_MCP_PUBLIC_URL?.trim().replace(/\/+$/, '') || undefined,
   };
 }
 
+/** Absolute origin for discovery URLs: the configured public origin, or derived
+ *  from the request (honoring an `X-Forwarded-Proto` from a TLS-terminating proxy). */
+function requestOrigin(req: IncomingMessage, publicUrl: string | undefined): string {
+  if (publicUrl) return publicUrl;
+  const forwarded = req.headers['x-forwarded-proto'];
+  const proto =
+    (typeof forwarded === 'string' ? forwarded.split(',')[0].trim() : undefined) || 'http';
+  const host = req.headers.host ?? 'localhost';
+  return `${proto}://${host}`;
+}
+
 /** Read and JSON-parse a request body with a hard size cap. */
 async function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<unknown> {
   const chunks: Buffer[] = [];
@@ -234,6 +256,8 @@ export interface RunningHttpServer {
  * @param config - Resolved HTTP transport settings.
  * @param makeServer - Factory that builds a fresh Qveris {@link Server} for a
  *   new client session. Called once per `initialize`.
+ * @param cardInfo - Metadata for the discovery documents (Server Card + Catalog).
+ *   When omitted those endpoints are not served.
  * @param logger - Where to write startup/lifecycle lines (defaults to stderr,
  *   keeping stdout clean).
  * @throws if binding a non-loopback host without an auth token and without an
@@ -242,6 +266,7 @@ export interface RunningHttpServer {
 export async function startHttpServer(
   config: TransportConfig,
   makeServer: (sessionId: string) => Server,
+  cardInfo?: ServerCardInfo,
   logger: (message: string) => void = (message) => process.stderr.write(message),
 ): Promise<RunningHttpServer> {
   const nonLoopback = !isLoopbackHost(config.host);
@@ -329,6 +354,40 @@ export async function startHttpServer(
         return;
       }
 
+      // Public, unauthenticated discovery documents (Server Card + Catalog).
+      // Like robots.txt / OAuth metadata, these are meant to be crawled without
+      // credentials, so they are handled before the auth check.
+      const cardPath = `${config.path}/server-card`;
+      if (cardInfo && (url.pathname === cardPath || url.pathname === CATALOG_PATH)) {
+        const cors = {
+          'Access-Control-Allow-Origin': '*',
+          'Access-Control-Allow-Methods': 'GET, OPTIONS',
+          'Access-Control-Allow-Headers': 'Accept',
+        };
+        if (req.method === 'OPTIONS') {
+          req.resume();
+          res.writeHead(204, { ...cors, 'Access-Control-Max-Age': '86400' });
+          res.end();
+          return;
+        }
+        if (req.method === 'GET') {
+          const origin = requestOrigin(req, config.publicUrl);
+          const cache = { 'Cache-Control': 'public, max-age=3600' };
+          if (url.pathname === cardPath) {
+            const card = buildServerCard(cardInfo, `${origin}${config.path}`);
+            writeJson(res, 200, card, { ...cors, ...cache, 'Content-Type': SERVER_CARD_MEDIA_TYPE });
+          } else {
+            const catalog = buildCatalog(cardInfo, `${origin}${cardPath}`);
+            writeJson(res, 200, catalog, { ...cors, ...cache });
+          }
+          return;
+        }
+        req.resume();
+        res.writeHead(405, { Allow: 'GET, OPTIONS' });
+        res.end();
+        return;
+      }
+
       if (url.pathname !== config.path) {
         req.resume(); // drain the body so the connection can be reused/closed
         writeJson(res, 404, jsonRpcError(null, -32601, `Not found: ${url.pathname}`));

packages/mcp/src/index.ts

@@ -29,9 +29,11 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  SUPPORTED_PROTOCOL_VERSIONS,
   type CallToolResult,
 } from '@modelcontextprotocol/sdk/types.js';
 import { resolveTransportConfig, startHttpServer } from './http.js';
+import type { ServerCardInfo } from './server-card.js';
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { v4 as uuidv4 } from 'uuid';
@@ -72,7 +74,26 @@ import { createRequire } from 'node:module';
 
 const SERVER_NAME = 'qveris';
 const require = createRequire(import.meta.url);
-const { version: SERVER_VERSION } = require('../package.json');
+const pkg = require('../package.json');
+const SERVER_VERSION: string = pkg.version;
+
+/** Discovery metadata (Server Card + Catalog) derived from package.json. */
+function buildServerCardInfo(): ServerCardInfo {
+  const repoUrl: string | undefined = pkg.repository?.url
+    ?.replace(/^git\+/, '')
+    .replace(/\.git$/, '');
+  return {
+    name: pkg.mcpName ?? 'io.github.QVerisAI/mcp',
+    version: SERVER_VERSION,
+    description: pkg.description,
+    title: 'QVeris',
+    websiteUrl: pkg.homepage,
+    repository: repoUrl
+      ? { source: 'github', url: repoUrl, subfolder: pkg.repository?.directory }
+      : undefined,
+    protocolVersions: SUPPORTED_PROTOCOL_VERSIONS,
+  };
+}
 
 /**
  * List the MCP tools exposed by this server.
@@ -479,7 +500,11 @@ export async function main(): Promise<void> {
 
   // Streamable HTTP: one Qveris server per MCP session, keyed by Mcp-Session-Id.
   if (transportConfig.mode === 'http') {
-    await startHttpServer(transportConfig, (sessionId) => createQverisServer(client, sessionId));
+    await startHttpServer(
+      transportConfig,
+      (sessionId) => createQverisServer(client, sessionId),
+      buildServerCardInfo(),
+    );
     return;
   }
 

packages/mcp/src/server-card.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildCatalog,
+  buildServerCard,
+  CATALOG_SPEC_VERSION,
+  SERVER_CARD_MEDIA_TYPE,
+  SERVER_CARD_SCHEMA_URL,
+  type ServerCardInfo,
+} from './server-card.js';
+
+const INFO: ServerCardInfo = {
+  name: 'io.github.QVerisAI/mcp',
+  version: '1.2.3',
+  description: 'QVeris MCP server.',
+  title: 'QVeris',
+  websiteUrl: 'https://qveris.ai',
+  repository: { source: 'github', url: 'https://github.com/QVerisAI/qveris-agent-toolkit', subfolder: 'packages/mcp' },
+  protocolVersions: ['2025-06-18', '2025-11-25'],
+};
+
+// The reverse-DNS name pattern from the Server Card schema.
+const NAME_PATTERN = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
+
+describe('buildServerCard', () => {
+  it('produces a schema-valid card with the required fields and remote', () => {
+    const card = buildServerCard(INFO, 'https://mcp.example.com/mcp');
+
+    expect(card.$schema).toBe(SERVER_CARD_SCHEMA_URL);
+    expect(card.name).toBe('io.github.QVerisAI/mcp');
+    expect(card.name).toMatch(NAME_PATTERN);
+    expect(card.version).toBe('1.2.3');
+    expect(card.description).toBe('QVeris MCP server.');
+    expect(card.title).toBe('QVeris');
+    expect(card.websiteUrl).toBe('https://qveris.ai');
+    expect(card.repository).toEqual(INFO.repository);
+    expect(card.remotes).toEqual([
+      {
+        type: 'streamable-http',
+        url: 'https://mcp.example.com/mcp',
+        supportedProtocolVersions: ['2025-06-18', '2025-11-25'],
+      },
+    ]);
+  });
+
+  it('omits optional fields and the protocol list when absent', () => {
+    const card = buildServerCard(
+      { name: 'example.org/x', version: '1.0.0', description: 'min' },
+      'http://127.0.0.1:3000/mcp',
+    );
+    expect(card.title).toBeUndefined();
+    expect(card.websiteUrl).toBeUndefined();
+    expect(card.repository).toBeUndefined();
+    expect(card.remotes?.[0]).toEqual({ type: 'streamable-http', url: 'http://127.0.0.1:3000/mcp' });
+    expect(card.remotes?.[0]).not.toHaveProperty('supportedProtocolVersions');
+  });
+});
+
+describe('buildCatalog', () => {
+  it('anchors the URN on the publisher domain and points at the card URL', () => {
+    const catalog = buildCatalog(INFO, 'https://mcp.example.com/mcp/server-card');
+
+    expect(catalog.specVersion).toBe(CATALOG_SPEC_VERSION);
+    expect(catalog.entries).toEqual([
+      {
+        identifier: 'urn:air:qveris.ai:mcp',
+        displayName: 'QVeris',
+        mediaType: SERVER_CARD_MEDIA_TYPE,
+        url: 'https://mcp.example.com/mcp/server-card',
+      },
+    ]);
+  });
+
+  it('falls back to localhost as the publisher when no website URL is set', () => {
+    const catalog = buildCatalog(
+      { name: 'example.org/weather', version: '1.0.0', description: 'x' },
+      'http://127.0.0.1:3000/mcp/server-card',
+    );
+    expect(catalog.entries[0].identifier).toBe('urn:air:localhost:weather');
+    expect(catalog.entries[0].displayName).toBe('example.org/weather');
+  });
+});