refactor(mcp): guide agents through creating clean rundowns

apps/client/src/common/utils/__tests__/linkUtils.test.ts

@@ -1,4 +1,4 @@
-import { linkToOtherHost } from '../linkUtils';
+import { hostToBaseUrl, linkToOtherHost } from '../linkUtils';
 
 describe('linkToOTherHost', () => {
   it('should handle electron links', () => {
@@ -22,3 +22,18 @@ describe('linkToOTherHost', () => {
     expect(destination).toBe('https://app.getontime.no/user-hash/path');
   });
 });
+
+describe('hostToBaseUrl', () => {
+  it('uses http when the page is plain http', () => {
+    expect(hostToBaseUrl('192.168.10.166', 4001, 'http://localhost:4001')).toBe('http://192.168.10.166:4001');
+  });
+
+  it('keeps https when the page reaches the server over TLS on the same port', () => {
+    expect(hostToBaseUrl('192.168.10.166', 4001, 'https://localhost:4001')).toBe('https://192.168.10.166:4001');
+  });
+
+  it('falls back to http when the page is https on a different port (TLS proxy)', () => {
+    // the raw server port does not speak TLS, an https link to it would fail
+    expect(hostToBaseUrl('192.168.10.166', 4001, 'https://ontime.example.com')).toBe('http://192.168.10.166:4001');
+  });
+});

apps/client/src/common/utils/linkUtils.ts

@@ -54,3 +54,17 @@ export function linkToOtherHost(
   }
   return destination.toString();
 }
+
+/**
+ * Builds a base URL for reaching the Ontime server on a given network interface.
+ * The Ontime server itself only speaks HTTP, so we only keep https when the page
+ * already reaches the server over TLS on that same port (eg. a proxy in front of it);
+ * any other explicit server port gets http.
+ * externalServerUrl is used for testing
+ */
+export function hostToBaseUrl(host: string, port: number, externalServerUrl: string = serverURL): string {
+  const page = new URL(externalServerUrl);
+  const pagePort = page.port === '' ? (page.protocol === 'https:' ? 443 : 80) : Number(page.port);
+  const scheme = page.protocol === 'https:' && pagePort === port ? 'https' : 'http';
+  return `${scheme}://${host}:${port}`;
+}

apps/client/src/features/app-settings/panel/settings-panel/McpSection.tsx

@@ -2,33 +2,23 @@ import { useEffect, useState } from 'react';
 
 import { generateUrl } from '../../../../common/api/session';
 import CopyTag from '../../../../common/components/copy-tag/CopyTag';
-import useInfo from '../../../../common/hooks-query/useInfo';
-import { isOntimeCloud, serverURL } from '../../../../externals';
+import { serverURL } from '../../../../externals';
 import * as Panel from '../../panel-utils/PanelUtils';
 
 export default function McpSection() {
-  const { data: infoData } = useInfo();
   const [mcpEndpointUrl, setMcpEndpointUrl] = useState('');
 
   // generate url
   useEffect(() => {
-    const baseUrl = (() => {
-      if (isOntimeCloud) return serverURL;
-
-      // for local setups we prefer the localhost IP to avoid remote access
-      if (infoData.networkInterfaces.length > 0) {
-        return `http://${infoData.networkInterfaces[0].address}:${infoData.serverPort}`;
-      }
-      return serverURL;
-    })();
-
+    // the page origin is reachable wherever the user is browsing from,
+    // and follows the deployment (cloud, reverse proxy, port mappings)
     // we are reusing the endpoint, so locking config and nav have no effect
-    generateUrl({ baseUrl, path: 'mcp', authenticate: true, lockConfig: false, lockNav: false })
+    generateUrl({ baseUrl: serverURL, path: 'mcp', authenticate: true, lockConfig: false, lockNav: false })
       .then(setMcpEndpointUrl)
       .catch(() => {
         setMcpEndpointUrl('');
       });
-  }, [infoData]);
+  }, []);
 
   const mcpClientConfig = mcpEndpointUrl
     ? JSON.stringify({ mcpServers: { ontime: { url: mcpEndpointUrl } } }, null, 2)
@@ -40,14 +30,19 @@ export default function McpSection() {
         <Panel.SubHeader>MCP Server</Panel.SubHeader>
         <Panel.Paragraph>Connect any MCP-compatible AI agent to Ontime using the endpoint below.</Panel.Paragraph>
         <Panel.Divider />
-        <Panel.Field title='Endpoint URL' description='Add this URL to your MCP client settings' />
-        {mcpEndpointUrl && <CopyTag copyValue={mcpEndpointUrl}>{mcpEndpointUrl}</CopyTag>}
-        <Panel.Divider />
-        <Panel.Field
-          title='Client configuration snippet'
-          description='Paste this into your AI agent settings under "mcpServers"'
-        />
-        {mcpEndpointUrl && <CopyTag copyValue={mcpClientConfig}>{mcpClientConfig}</CopyTag>}
+        <Panel.ListGroup>
+          <Panel.ListItem>
+            <Panel.Field title='Endpoint URL' description='Add this URL to your MCP client settings' />
+            {mcpEndpointUrl && <CopyTag copyValue={mcpEndpointUrl}>{mcpEndpointUrl}</CopyTag>}
+          </Panel.ListItem>
+          <Panel.ListItem>
+            <Panel.Field
+              title='Client configuration snippet'
+              description='Paste this into your AI agent settings under "mcpServers"'
+            />
+            {mcpEndpointUrl && <CopyTag copyValue={mcpClientConfig}>{mcpClientConfig}</CopyTag>}
+          </Panel.ListItem>
+        </Panel.ListGroup>
       </Panel.Card>
     </Panel.Section>
   );

apps/client/src/features/sharing/GenerateLinkFormExport.tsx

@@ -3,6 +3,7 @@ import { useMemo } from 'react';
 
 import useInfo from '../../common/hooks-query/useInfo';
 import useUrlPresets from '../../common/hooks-query/useUrlPresets';
+import { hostToBaseUrl } from '../../common/utils/linkUtils';
 import GenerateLinkForm from './GenerateLinkForm';
 
 interface GenerateLinkFormExportProps {
@@ -21,7 +22,7 @@ export default function GenerateLinkFormExport({ lockedPath }: GenerateLinkFormE
    */
   const hostOptions = useMemo(() => {
     return infoData.networkInterfaces.map((nif) => ({
-      value: `http://${nif.address}:${infoData.serverPort}`,
+      value: hostToBaseUrl(nif.address, infoData.serverPort),
       label: `${nif.name} - ${nif.address}`,
     }));
   }, [infoData.networkInterfaces, infoData.serverPort]);