From 27e954c60bcbae90ad1a9cc221bf7c15a050faf0 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Fri, 16 Oct 2026 12:16:15 -0600 Subject: [PATCH 1/4] feat(mcp): advertise server title, description, website, and icon --- .changeset/mcp-server-metadata.md | 5 +++ .../src/mcp/__tests__/serverMetadata.test.ts | 26 ++++++++++++ packages/api/src/mcp/mcpServer.ts | 42 +++++++++++++++---- 3 files changed, 65 insertions(+), 8 deletions(-) create mode 100644 .changeset/mcp-server-metadata.md create mode 100644 packages/api/src/mcp/__tests__/serverMetadata.test.ts diff --git a/.changeset/mcp-server-metadata.md b/.changeset/mcp-server-metadata.md new file mode 100644 index 0000000000..45f2114e8d --- /dev/null +++ b/.changeset/mcp-server-metadata.md @@ -0,0 +1,5 @@ +--- +'@hyperdx/api': patch +--- + +feat(mcp): advertise a title, description, website URL, and SVG icon in the MCP server's initialize response diff --git a/packages/api/src/mcp/__tests__/serverMetadata.test.ts b/packages/api/src/mcp/__tests__/serverMetadata.test.ts new file mode 100644 index 0000000000..58175f15d7 --- /dev/null +++ b/packages/api/src/mcp/__tests__/serverMetadata.test.ts @@ -0,0 +1,26 @@ +import { McpContext } from '@/mcp/tools/types'; + +import { createTestClient } from './mcpTestUtils'; + +describe('MCP server metadata', () => { + const context: McpContext = { teamId: 'team-id', userId: 'user-id' }; + + it('advertises a title, description, website, and scalable icon', async () => { + const client = await createTestClient(context); + const info = client.getServerVersion(); + + expect(info).toMatchObject({ + name: 'clickstack', + title: 'ClickStack', + websiteUrl: expect.stringMatching(/^https:\/\//), + description: expect.any(String), + }); + expect(info?.icons).toEqual([ + expect.objectContaining({ + src: expect.stringMatching(/^data:image\/svg\+xml;base64,/), + mimeType: 'image/svg+xml', + sizes: ['any'], + }), + ]); + }); +}); diff --git a/packages/api/src/mcp/mcpServer.ts b/packages/api/src/mcp/mcpServer.ts index 33365a8662..84909816de 100644 --- a/packages/api/src/mcp/mcpServer.ts +++ b/packages/api/src/mcp/mcpServer.ts @@ -1,4 +1,5 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import type { Implementation } from '@modelcontextprotocol/sdk/types.js'; import { CODE_VERSION } from '@/config'; @@ -35,16 +36,41 @@ const SERVER_INSTRUCTIONS = [ 'dashboard authoring.', ].join('\n'); -export function createServer(context: McpContext) { - const server = new McpServer( - { - name: 'clickstack', - version: `${CODE_VERSION}-beta`, - }, +// Inlined as a data URI so the icon resolves no matter where the server is +// hosted. Mirrors packages/app/public/favicons/clickstack/favicon.svg. +const SERVER_ICON_SVG = + '' + + '' + + '' + + '' + + '' + + '' + + '' + + '' + + ''; + +const SERVER_INFO: Implementation = { + name: 'clickstack', + title: 'ClickStack', + version: `${CODE_VERSION}-beta`, + description: + 'Query and investigate logs, metrics, traces, and sessions stored in ' + + 'ClickHouse, and manage ClickStack dashboards, alerts, data sources, ' + + 'and saved searches.', + websiteUrl: 'https://clickhouse.com/docs/use-cases/observability/clickstack', + icons: [ { - instructions: SERVER_INSTRUCTIONS, + src: `data:image/svg+xml;base64,${Buffer.from(SERVER_ICON_SVG).toString('base64')}`, + mimeType: 'image/svg+xml', + sizes: ['any'], }, - ); + ], +}; + +export function createServer(context: McpContext) { + const server = new McpServer(SERVER_INFO, { + instructions: SERVER_INSTRUCTIONS, + }); const registerTool = createRegisterTool(server, context); const registrar = { server, context, registerTool }; From 9c9b6eb35cd4ab2bf892605f192d879ff80beb16 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Fri, 16 Oct 2026 13:43:25 -0600 Subject: [PATCH 2/4] feat(mcp): serve the HyperDX logo from the app instead of an inline SVG --- .../src/mcp/__tests__/serverMetadata.test.ts | 41 +++++++++++++++---- packages/api/src/mcp/mcpServer.ts | 31 +++++--------- 2 files changed, 43 insertions(+), 29 deletions(-) diff --git a/packages/api/src/mcp/__tests__/serverMetadata.test.ts b/packages/api/src/mcp/__tests__/serverMetadata.test.ts index 58175f15d7..c38bae5749 100644 --- a/packages/api/src/mcp/__tests__/serverMetadata.test.ts +++ b/packages/api/src/mcp/__tests__/serverMetadata.test.ts @@ -1,13 +1,29 @@ +import type { Implementation } from '@modelcontextprotocol/sdk/types.js'; + import { McpContext } from '@/mcp/tools/types'; -import { createTestClient } from './mcpTestUtils'; +const context: McpContext = { teamId: 'team-id', userId: 'user-id' }; -describe('MCP server metadata', () => { - const context: McpContext = { teamId: 'team-id', userId: 'user-id' }; +async function getServerInfo( + frontendUrl: string, +): Promise { + let createTestClient!: typeof import('./mcpTestUtils').createTestClient; + jest.isolateModules(() => { + jest.doMock('@/config', () => ({ + ...jest.requireActual('@/config'), + FRONTEND_URL: frontendUrl, + })); + // eslint-disable-next-line @typescript-eslint/no-require-imports + ({ createTestClient } = require('./mcpTestUtils')); + }); + jest.dontMock('@/config'); + const client = await createTestClient(context); + return client.getServerVersion(); +} - it('advertises a title, description, website, and scalable icon', async () => { - const client = await createTestClient(context); - const info = client.getServerVersion(); +describe('MCP server metadata', () => { + it('advertises a title, description, website, and app-hosted icon', async () => { + const info = await getServerInfo('https://app.example.com/'); expect(info).toMatchObject({ name: 'clickstack', @@ -16,11 +32,18 @@ describe('MCP server metadata', () => { description: expect.any(String), }); expect(info?.icons).toEqual([ - expect.objectContaining({ - src: expect.stringMatching(/^data:image\/svg\+xml;base64,/), + { + src: 'https://app.example.com/favicons/hyperdx/favicon.svg', mimeType: 'image/svg+xml', sizes: ['any'], - }), + }, ]); }); + + it('omits the icon when FRONTEND_URL is unset', async () => { + const info = await getServerInfo(''); + + expect(info?.title).toBe('ClickStack'); + expect(info?.icons).toBeUndefined(); + }); }); diff --git a/packages/api/src/mcp/mcpServer.ts b/packages/api/src/mcp/mcpServer.ts index 84909816de..ab4a6e85db 100644 --- a/packages/api/src/mcp/mcpServer.ts +++ b/packages/api/src/mcp/mcpServer.ts @@ -1,7 +1,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import type { Implementation } from '@modelcontextprotocol/sdk/types.js'; -import { CODE_VERSION } from '@/config'; +import { CODE_VERSION, FRONTEND_URL } from '@/config'; import dashboardPrompts from './prompts/dashboards/index'; import alertsTools from './tools/alerts/index'; @@ -36,18 +36,11 @@ const SERVER_INSTRUCTIONS = [ 'dashboard authoring.', ].join('\n'); -// Inlined as a data URI so the icon resolves no matter where the server is -// hosted. Mirrors packages/app/public/favicons/clickstack/favicon.svg. -const SERVER_ICON_SVG = - '' + - '' + - '' + - '' + - '' + - '' + - '' + - '' + - ''; +// Served by the app; omitted when FRONTEND_URL is unset because MCP icon +// sources must be absolute URLs. +const SERVER_ICON_URL = FRONTEND_URL + ? new URL('/favicons/hyperdx/favicon.svg', FRONTEND_URL).toString() + : undefined; const SERVER_INFO: Implementation = { name: 'clickstack', @@ -58,13 +51,11 @@ const SERVER_INFO: Implementation = { 'ClickHouse, and manage ClickStack dashboards, alerts, data sources, ' + 'and saved searches.', websiteUrl: 'https://clickhouse.com/docs/use-cases/observability/clickstack', - icons: [ - { - src: `data:image/svg+xml;base64,${Buffer.from(SERVER_ICON_SVG).toString('base64')}`, - mimeType: 'image/svg+xml', - sizes: ['any'], - }, - ], + ...(SERVER_ICON_URL && { + icons: [ + { src: SERVER_ICON_URL, mimeType: 'image/svg+xml', sizes: ['any'] }, + ], + }), }; export function createServer(context: McpContext) { From 16ac73d6a17783cfd47d011c1413eca7ffd74c09 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Fri, 16 Oct 2026 13:55:52 -0600 Subject: [PATCH 3/4] fix(mcp): keep FRONTEND_URL sub-path in the server icon URL --- packages/api/src/mcp/__tests__/serverMetadata.test.ts | 8 ++++++++ packages/api/src/mcp/mcpServer.ts | 5 +++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/packages/api/src/mcp/__tests__/serverMetadata.test.ts b/packages/api/src/mcp/__tests__/serverMetadata.test.ts index c38bae5749..a7d1d3bfc2 100644 --- a/packages/api/src/mcp/__tests__/serverMetadata.test.ts +++ b/packages/api/src/mcp/__tests__/serverMetadata.test.ts @@ -40,6 +40,14 @@ describe('MCP server metadata', () => { ]); }); + it('keeps the FRONTEND_URL sub-path in the icon URL', async () => { + const info = await getServerInfo('https://host.example.com/hyperdx'); + + expect(info?.icons?.[0]?.src).toBe( + 'https://host.example.com/hyperdx/favicons/hyperdx/favicon.svg', + ); + }); + it('omits the icon when FRONTEND_URL is unset', async () => { const info = await getServerInfo(''); diff --git a/packages/api/src/mcp/mcpServer.ts b/packages/api/src/mcp/mcpServer.ts index ab4a6e85db..2411a704a7 100644 --- a/packages/api/src/mcp/mcpServer.ts +++ b/packages/api/src/mcp/mcpServer.ts @@ -37,9 +37,10 @@ const SERVER_INSTRUCTIONS = [ ].join('\n'); // Served by the app; omitted when FRONTEND_URL is unset because MCP icon -// sources must be absolute URLs. +// sources must be absolute URLs. String concatenation (not `new URL`) keeps +// any sub-path the app is mounted under. The HyperDX logo is intentional. const SERVER_ICON_URL = FRONTEND_URL - ? new URL('/favicons/hyperdx/favicon.svg', FRONTEND_URL).toString() + ? `${FRONTEND_URL.replace(/\/+$/, '')}/favicons/hyperdx/favicon.svg` : undefined; const SERVER_INFO: Implementation = { From 3f87f27acb6f142ff83a417f6728ba999a0ca741 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Fri, 16 Oct 2026 14:03:02 -0600 Subject: [PATCH 4/4] test(mcp): drop eslint-disable from server metadata test --- packages/api/src/mcp/__tests__/serverMetadata.test.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/api/src/mcp/__tests__/serverMetadata.test.ts b/packages/api/src/mcp/__tests__/serverMetadata.test.ts index a7d1d3bfc2..e03a850a75 100644 --- a/packages/api/src/mcp/__tests__/serverMetadata.test.ts +++ b/packages/api/src/mcp/__tests__/serverMetadata.test.ts @@ -13,8 +13,8 @@ async function getServerInfo( ...jest.requireActual('@/config'), FRONTEND_URL: frontendUrl, })); - // eslint-disable-next-line @typescript-eslint/no-require-imports - ({ createTestClient } = require('./mcpTestUtils')); + ({ createTestClient } = + jest.requireActual('./mcpTestUtils')); }); jest.dontMock('@/config'); const client = await createTestClient(context);