refactor(mcp-optimizer): remove the feature and migrate legacy users on startup (#2086)

* refactor(mcp-optimizer): remove sunset UI, route, and feature module

Follows the deprecation shipped in #1910. Deletes the /mcp-optimizer route,
the sunset banner, the features/meta-mcp module, and every optimizer-specific
branch that lived across MCP server orchestration, group actions, client
registration, and routing. Stops tracking the toolhive-mcp-optimizer image in
Renovate and drops the sunset blog URL constant. Trims constants.ts down to
the identifiers still used by the legacy-user cleanup migration.

* feat(mcp-optimizer): run cleanup once on startup for legacy users

Users who had MCP Optimizer enabled still have the __mcp-optimizer__ group,
its meta-mcp workload, and their clients registered to the optimizer group
after the feature is removed. On first launch post-upgrade, wait for the
ToolHive daemon to become ready and then run the same teardown that used to
fire when the experimental toggle was flipped off: restore clients to the
ALLOWED_GROUPS target and delete the optimizer group with its workloads.

- Add useMcpOptimizerStartupCleanup and wire it into RootComponent. It polls
  electronAPI.isToolhiveRunning before marking itself as run, so a slow
  daemon start cannot cause the migration to silently no-op.
- Rewrite useCleanupMetaOptimizer to fetch groups and the meta-mcp workload
  at call-time via queryClient.fetchQuery, decoupling it from React Query
  closures and from the feature-flag gate.
- Flip META_OPTIMIZER to isDisabled: true so the flag key is still defined
  (for one release) and the UI no longer surfaces it, while the cleanup path
  remains callable.

* test(e2e): cover MCP optimizer startup cleanup migration

Two-session Playwright spec that relaunches the app against the same
userDataDir to exercise the one-shot startup hook:

- Session 1 creates a custom group via the UI, then seeds __mcp-optimizer__,
  registers a client against it, and creates a meta-mcp workload pointing
  at a local test MCP server with ALLOWED_GROUPS set to the custom group.
- Session 2 polls the thv HTTP API until the optimizer group is gone, the
  client is re-registered to the custom group, and the meta-mcp workload
  returns 404 — with a best-effort thv CLI teardown in afterAll as a
  safety net.

Adds a reusable launchApp + thvFetch helper so future multi-session specs
don't have to re-implement Electron + userDataDir wiring.

* fix(mcp-optimizer): harden startup cleanup against edge cases

Addresses review feedback on #2086:

- useMcpOptimizerStartupCleanup no longer latches `hasRunCleanup` before
  awaiting ToolHive readiness. If the 60s readiness wait times out the hook
  can now retry on a subsequent effect re-fire. An `inFlight` ref still
  prevents concurrent starts.
- useCleanupMetaOptimizer parses ALLOWED_GROUPS defensively (trim, first
  non-empty comma entry) and only restores clients when the target group
  still exists in the fetched groups list. Unregister + group delete still
  proceed regardless, so the optimizer state never lingers.
- mcp-optimizer-startup-cleanup.spec.ts bumps the cleanup poll timeout
  from 60s to 120s so slow CI runners don't flake when the app-side
  readiness wait consumes most of the original budget.

Adds a regression test that asserts restoration is skipped when
ALLOWED_GROUPS points to a group that no longer exists.

Made-with: Cursor

* fix(mcp-optimizer): address deeper review feedback on startup migration

Second follow-up on #2086, addressing the more nuanced review points:

- useMcpOptimizerStartupCleanup now logs the elapsed cleanup duration on
  success, making slow CI runs easier to diagnose.
- useCleanupMetaOptimizer aborts before touching the optimizer group when
  restoring clients to the ALLOWED_GROUPS target fails. The startup hook
  retries on the next launch, so clients are never left orphaned between
  "removed from optimizer" and "restored to target".
- useCleanupMetaOptimizer wraps the final deleteGroup call in a try/catch
  that swallows 404s. In the rare race where the group is removed between
  our fetch and the delete (e.g. concurrent CLI teardown), the migration
  treats the end state as success instead of surfacing a phantom error.
- useDeleteServer drops the unused `group` param from its type and from
  its sole caller in RemoveServerMenuItem, keeping the hook contract
  honest now that the optimizer-specific notification path is gone.

Adds a regression test asserting that a failing clients/register call
leaves the optimizer group untouched (no unregister, no delete).

Made-with: Cursor

* fix(e2e): force-exit electron between sessions in optimizer cleanup test

On Linux CI, `ElectronApplication.close()` hung for the full 180s test
timeout after the first session seeded a running workload via the thv
API - the before-quit / graceful-shutdown path waits on a workload that
never drains. Add a `close()` helper on `LaunchedApp` that force-exits
via `app.exit(0)`, races `app.close()` against a 5s fallback, and
SIGKILLs the leftover process. Use it from both session teardowns in
the optimizer cleanup spec.

Made-with: Cursor

Author: samuv

common/app-info.ts

@@ -49,14 +49,11 @@ export const GITHUB_PAGES_MANIFEST_URL =
 export const DOCS_BASE_URL = 'https://docs.stacklok.com/toolhive'
 export const DISCORD_URL = 'https://discord.gg/stacklok'
 export const DEMO_URL = 'https://stacklok.com/demo/'
-export const MCP_OPTIMIZER_SUNSET_BLOG_URL =
-  'https://stacklok.com/blog/mcp-optimizer-is-now-built-into-the-stacklok-platform/'
 
 // ── Registry ─────────────────────────────────────────────────────────────────
 
 export const DEFAULT_REGISTRY_JSON_URL =
   'https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/pkg/registry/data/registry.json'
-export const MCP_OPTIMIZER_IMAGE = 'ghcr.io/stackloklabs/mcp-optimizer'
 
 // ── Privacy / legal ──────────────────────────────────────────────────────────
 

e2e-tests/helpers/app-relaunch.ts

@@ -0,0 +1,173 @@
+import path from 'path'
+import {
+  _electron as electron,
+  type ElectronApplication,
+  type Page,
+} from '@playwright/test'
+
+function getExecutablePath(): string {
+  const platform = process.platform
+  const arch = process.arch
+  const basePath = path.join(__dirname, '..', '..', 'out')
+
+  if (platform === 'darwin') {
+    return path.join(
+      basePath,
+      `ToolHive-darwin-${arch}`,
+      'ToolHive.app',
+      'Contents',
+      'MacOS',
+      'ToolHive'
+    )
+  } else if (platform === 'win32') {
+    return path.join(basePath, `ToolHive-win32-${arch}`, 'ToolHive.exe')
+  } else {
+    return path.join(basePath, `ToolHive-linux-${arch}`, 'ToolHive')
+  }
+}
+
+export interface LaunchedApp {
+  app: ElectronApplication
+  window: Page
+  baseUrl: string
+  /**
+   * Terminate the app without waiting on the renderer's before-quit teardown.
+   *
+   * On Linux CI the regular `ElectronApplication.close()` has been observed to
+   * hang indefinitely when a session has seeded a running workload via the thv
+   * API (the graceful shutdown path waits on a remote workload that never
+   * drains). We bypass that path via `app.exit(0)` and fall back to SIGKILL.
+   */
+  close: () => Promise<void>
+}
+
+/**
+ * Launch the Electron app bound to a specific userDataDir so the same
+ * directory can be reused across launches within a single test.
+ *
+ * Mirrors the setup in e2e-tests/fixtures/electron.ts but exposes the raw
+ * app/window instead of running the shared MCP server group bootstrap.
+ */
+export async function launchApp(userDataDir: string): Promise<LaunchedApp> {
+  const app = await electron.launch({
+    executablePath: getExecutablePath(),
+    ...(process.env.CI ? { recordVideo: { dir: 'test-videos' } } : {}),
+    args: ['--no-sandbox', `--user-data-dir=${userDataDir}`],
+    env: {
+      ...process.env,
+      TOOLHIVE_E2E: 'true',
+    },
+  })
+
+  const window = await app.firstWindow()
+
+  await window.route('https://*.sentry.io/**', (route) => {
+    throw new Error(`Sentry request blocked: ${route.request().url()}`)
+  })
+
+  // Disable quit confirmation dialog as a safety net; our close() helper also
+  // force-exits, so this mostly keeps manual tear-downs clean.
+  await window.evaluate(async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await (globalThis as any).electronAPI.setSkipQuitConfirmation(true)
+  })
+
+  await window.getByRole('link', { name: /mcp servers/i }).waitFor()
+
+  const port = await window.evaluate(async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (await (globalThis as any).electronAPI.getToolhivePort()) as number
+  })
+
+  if (!port) {
+    throw new Error('Failed to resolve ToolHive port from the launched app')
+  }
+
+  const baseUrl = `http://127.0.0.1:${port}`
+
+  await waitForThvReady(baseUrl)
+
+  const close = async () => {
+    // Force an immediate exit via Electron's app.exit(), bypassing before-quit
+    // handlers, the confirmation dialog, and any pending graceful-shutdown
+    // work (e.g. waiting on seeded workloads to drain).
+    try {
+      await app.evaluate(({ app: electronApp }) => electronApp.exit(0))
+    } catch {
+      // Renderer/main may already be gone; ignore.
+    }
+
+    // Give the process a short window to exit cleanly, then hard-kill.
+    const proc = app.process()
+    await Promise.race([
+      app.close().catch(() => {}),
+      new Promise<void>((resolve) => setTimeout(resolve, 5_000)),
+    ])
+
+    if (proc.exitCode === null && !proc.killed) {
+      try {
+        proc.kill('SIGKILL')
+      } catch {
+        // Process may have exited between the check and the kill.
+      }
+    }
+  }
+
+  return { app, window, baseUrl, close }
+}
+
+/**
+ * Thin wrapper around `fetch` that raises on non-2xx/4xx responses the caller
+ * wants to treat as failures, optionally returning parsed JSON.
+ */
+export async function thvFetch<T = unknown>(
+  baseUrl: string,
+  apiPath: string,
+  init?: RequestInit & { expectStatus?: number[] }
+): Promise<{ status: number; json: T | null }> {
+  const { expectStatus, ...rest } = init ?? {}
+  const res = await fetch(`${baseUrl}${apiPath}`, {
+    ...rest,
+    headers: {
+      'content-type': 'application/json',
+      ...(rest.headers ?? {}),
+    },
+  })
+
+  if (expectStatus && !expectStatus.includes(res.status)) {
+    const body = await res.text()
+    throw new Error(
+      `thvFetch ${apiPath} expected status in [${expectStatus.join(',')}], got ${res.status}: ${body}`
+    )
+  }
+
+  const text = await res.text()
+  let json: T | null = null
+  if (text) {
+    try {
+      json = JSON.parse(text) as T
+    } catch {
+      json = null
+    }
+  }
+  return { status: res.status, json }
+}
+
+async function waitForThvReady(
+  baseUrl: string,
+  { timeoutMs = 30_000 } = {}
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${baseUrl}/api/v1beta/groups`)
+      if (res.ok) return
+    } catch {
+      // keep polling
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
+  throw new Error(
+    `ToolHive API at ${baseUrl} did not become ready within ${timeoutMs}ms`
+  )
+}

e2e-tests/mcp-optimizer-startup-cleanup.spec.ts

@@ -0,0 +1,186 @@
+import path from 'path'
+import fs from 'fs'
+import os from 'os'
+import { execSync } from 'child_process'
+import { test, expect } from '@playwright/test'
+import { launchApp, thvFetch, type LaunchedApp } from './helpers/app-relaunch'
+import {
+  startTestMcpServer,
+  type TestMcpServer,
+} from './helpers/test-mcp-server'
+
+const OPTIMIZER_GROUP = '__mcp-optimizer__'
+const META_MCP_SERVER = 'toolhive-mcp-optimizer'
+const CUSTOM_GROUP = 'pw-optimizer-custom'
+const TEST_CLIENT = 'vscode'
+
+function getThvPath(): string {
+  const platform = process.platform
+  const arch = process.arch
+  const binName = platform === 'win32' ? 'thv.exe' : 'thv'
+  return path.join(__dirname, '..', 'bin', `${platform}-${arch}`, binName)
+}
+
+/**
+ * Best-effort cleanup of leftover groups via the thv CLI. The CLI requires a
+ * Docker-compatible runtime but we already require that for e2e tests.
+ */
+function bestEffortCliCleanup(): void {
+  const thvPath = getThvPath()
+  const env = { ...process.env, TOOLHIVE_SKIP_DESKTOP_CHECK: 'true' }
+  for (const group of [OPTIMIZER_GROUP, CUSTOM_GROUP]) {
+    try {
+      execSync(`"${thvPath}" group rm "${group}" --with-workloads`, {
+        input: 'y\n',
+        stdio: ['pipe', 'ignore', 'ignore'],
+        env,
+      })
+    } catch {
+      // Group does not exist - that's the happy path.
+    }
+  }
+}
+
+async function createGroupViaUi(
+  launched: LaunchedApp,
+  groupName: string
+): Promise<void> {
+  const { window } = launched
+  await window.getByRole('button', { name: /add a group/i }).click()
+  await window.getByRole('dialog').waitFor()
+  await window.getByLabel(/name/i).fill(groupName)
+  await window.getByRole('button', { name: /create/i }).click()
+  await window.getByRole('dialog').waitFor({ state: 'hidden' })
+}
+
+async function seedOptimizerState(
+  baseUrl: string,
+  testServer: TestMcpServer
+): Promise<void> {
+  await thvFetch(baseUrl, '/api/v1beta/groups', {
+    method: 'POST',
+    body: JSON.stringify({ name: OPTIMIZER_GROUP }),
+    expectStatus: [200, 201],
+  })
+
+  await thvFetch(baseUrl, '/api/v1beta/clients/register', {
+    method: 'POST',
+    body: JSON.stringify({
+      names: [TEST_CLIENT],
+      groups: [OPTIMIZER_GROUP],
+    }),
+    expectStatus: [200, 201],
+  })
+
+  // Create a remote meta-mcp workload so GET /workloads/meta-mcp later returns
+  // the ALLOWED_GROUPS env var that drives the restoration path. A remote
+  // workload avoids any Docker image pull complications.
+  await thvFetch(baseUrl, '/api/v1beta/workloads', {
+    method: 'POST',
+    body: JSON.stringify({
+      name: META_MCP_SERVER,
+      group: OPTIMIZER_GROUP,
+      url: testServer.url,
+      transport: 'streamable-http',
+      env_vars: {
+        ALLOWED_GROUPS: CUSTOM_GROUP,
+      },
+    }),
+    expectStatus: [200, 201, 202],
+  })
+}
+
+async function waitForOptimizerCleanup(baseUrl: string): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        const { json } = await thvFetch<{
+          groups?: Array<{ name?: string; registered_clients?: string[] }>
+        }>(baseUrl, '/api/v1beta/groups', { expectStatus: [200] })
+        const groups = json?.groups ?? []
+        const optimizerGroup = groups.find((g) => g.name === OPTIMIZER_GROUP)
+        const customGroup = groups.find((g) => g.name === CUSTOM_GROUP)
+        return {
+          optimizerGone: !optimizerGroup,
+          customHasClient:
+            customGroup?.registered_clients?.includes(TEST_CLIENT) ?? false,
+        }
+      },
+      // App-side readiness wait can itself take up to TOOLHIVE_READY_MAX_WAIT_MS
+      // (60s). Give the poll a budget that exceeds that plus cleanup time so
+      // slow CI runners don't flake even though in practice this completes
+      // well under a second.
+      { timeout: 120_000, intervals: [500, 1000, 2000] }
+    )
+    .toEqual({ optimizerGone: true, customHasClient: true })
+}
+
+test.describe('MCP Optimizer startup cleanup', () => {
+  let userDataDir: string
+  let testServer: TestMcpServer
+
+  test.beforeAll(async () => {
+    bestEffortCliCleanup()
+    testServer = await startTestMcpServer()
+  })
+
+  test.afterAll(async () => {
+    await testServer?.stop()
+    bestEffortCliCleanup()
+  })
+
+  test.beforeEach(() => {
+    userDataDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'toolhive-e2e-optimizer-cleanup-')
+    )
+  })
+
+  test.afterEach(() => {
+    fs.rmSync(userDataDir, { recursive: true, force: true })
+  })
+
+  test('restores clients to the custom group and deletes __mcp-optimizer__ on next launch', async () => {
+    // Session 1: seed the legacy MCP Optimizer state.
+    const firstLaunch = await launchApp(userDataDir)
+    try {
+      await createGroupViaUi(firstLaunch, CUSTOM_GROUP)
+      await seedOptimizerState(firstLaunch.baseUrl, testServer)
+
+      // Sanity: both groups exist and optimizer has the registered client.
+      const { json: seeded } = await thvFetch<{
+        groups?: Array<{ name?: string; registered_clients?: string[] }>
+      }>(firstLaunch.baseUrl, '/api/v1beta/groups', { expectStatus: [200] })
+      const seededOptimizer = seeded?.groups?.find(
+        (g) => g.name === OPTIMIZER_GROUP
+      )
+      expect(seededOptimizer?.registered_clients).toContain(TEST_CLIENT)
+      expect(seeded?.groups?.some((g) => g.name === CUSTOM_GROUP)).toBe(true)
+    } finally {
+      await firstLaunch.close()
+    }
+
+    // Session 2: relaunching with the same userDataDir should trigger the
+    // startup cleanup hook, which restores clients and deletes the group.
+    const secondLaunch = await launchApp(userDataDir)
+    try {
+      await waitForOptimizerCleanup(secondLaunch.baseUrl)
+
+      // The meta-mcp workload is deleted as part of ?with-workloads=true.
+      const { status: workloadStatus } = await thvFetch(
+        secondLaunch.baseUrl,
+        `/api/v1beta/workloads/${META_MCP_SERVER}`
+      )
+      expect(workloadStatus).toBe(404)
+
+      // The user's custom group is preserved.
+      const { json: finalGroups } = await thvFetch<{
+        groups?: Array<{ name?: string }>
+      }>(secondLaunch.baseUrl, '/api/v1beta/groups', { expectStatus: [200] })
+      expect(finalGroups?.groups?.some((g) => g.name === CUSTOM_GROUP)).toBe(
+        true
+      )
+    } finally {
+      await secondLaunch.close()
+    }
+  })
+})