feat(agentic): add --base to devframe connect port probes

`--port` probes always looked for `__connection.json` at the root, so a
devframe or hub mounted below it (Vite DevTools at `/__devtools/`) could
not be reached, and the advertised MCP path was resolved against `/`.

Add a `base` connector option and a `--base <path>` CLI flag (default
`/`) for the explicit port probes, and resolve the MCP path against that
base, the same way the instance shell does for registry records.
`probePort` is exported for focused tests. Document the flag in the CLI
help and the MCP adapter's Discovery section.

Closes #403

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: zahidzorbaz

docs/content/2.adapters/7.mcp.md

@@ -107,7 +107,7 @@ Two gateway tools (`devframe:connect:*` ids; see [tool ids and wire names](/guid
 - **`devframe_connect_list-instances`**: list running dev servers and their MCP tools.
 - **`devframe_connect_call-tool`**: invoke one tool on a running devframe (`{ port, tool, args }`) over Streamable-HTTP.
 
-Discovery reads the **instance registry**: every `createDevServer` writes `~/.devframe/instances/<pid>-<port>.json`, dialed with a loopback origin. In-process host frameworks register via `registerDevframeInstance` (`devframe/node`). `--port <n>` probes a port; `DEVFRAME_INSTANCES_DIR` relocates the registry, `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` opts out.
+Discovery reads the **instance registry**: every `createDevServer` writes `~/.devframe/instances/<pid>-<port>.json`, dialed with a loopback origin. In-process host frameworks register via `registerDevframeInstance` (`devframe/node`). `--port <n>` probes a port for `__connection.json` at its root; add `--base <path>` for a devframe mounted below the root (e.g. `devframe connect --port 5173 --base /__devtools/` for Vite DevTools). A probe only counts a JSON object as connection meta, so an SPA fallback page on the wrong path reads as "no instance". `DEVFRAME_INSTANCES_DIR` relocates the registry, `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` opts out.
 
 The connector needs the same optional `@devframes/agentic` peer as the adapter; `devframe connect` without it throws [DF0046](/errors/DF0046).
 

packages/agentic/src/connect/__tests__/connect.test.ts

@@ -1,9 +1,12 @@
 import type { DevframeInstanceRecord, StartedServer } from 'devframe/internal'
 import type { DevframeDefinition } from 'devframe/types'
+import type { Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { createServer } from 'node:http'
 import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
 import { createDevServer } from 'devframe/adapters/dev'
 import { afterEach, describe, expect, it } from 'vitest'
-import { buildInstanceRequestHeaders, resolveAuthToken } from '../index'
+import { buildInstanceRequestHeaders, probePort, resolveAuthToken } from '../index'
 
 const TOKEN = 'a-high-entropy-connect-test-token'
 
@@ -59,6 +62,52 @@ describe('buildInstanceRequestHeaders', () => {
   })
 })
 
+describe('probePort', () => {
+  let server: Server | undefined
+
+  afterEach(async () => {
+    await new Promise<void>(resolve => (server ? server.close(() => resolve()) : resolve()))
+    server = undefined
+  })
+
+  // A Vite-like host: the hub's meta lives under `/__devtools/` and every
+  // other path falls back to the app's `index.html` with `200 text/html`.
+  async function startBasedHub(): Promise<number> {
+    server = createServer((req, res) => {
+      if (req.url === '/__devtools/__connection.json') {
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end('{"backend":"websocket","mcp":{"path":"__mcp"}}')
+        return
+      }
+      res.writeHead(200, { 'content-type': 'text/html' })
+      res.end('<!doctype html><html><body></body></html>')
+    })
+    await new Promise<void>(resolve => server!.listen(0, '127.0.0.1', resolve))
+    return (server.address() as AddressInfo).port
+  }
+
+  it('finds a hub mounted under a base and resolves its MCP path against it', async () => {
+    const port = await startBasedHub()
+    const record = await probePort(port, '/__devtools/', 2000)
+    expect(record).toMatchObject({
+      port,
+      basePath: '/__devtools/',
+      mcp: { path: '/__devtools/__mcp' },
+    })
+  })
+
+  it('normalizes a base given without slashes', async () => {
+    const port = await startBasedHub()
+    const record = await probePort(port, '__devtools', 2000)
+    expect(record).toMatchObject({ basePath: '/__devtools/', mcp: { path: '/__devtools/__mcp' } })
+  })
+
+  it('reports no instance (not an MCP-less one) when the root only serves the SPA fallback', async () => {
+    const port = await startBasedHub()
+    expect(await probePort(port, undefined, 2000)).toBeNull()
+  })
+})
+
 describe('connector bearer against a live authenticated MCP route', () => {
   let server: StartedServer | undefined
 

packages/agentic/src/connect/index.ts

@@ -6,15 +6,24 @@ import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
 import { diagnostics, listLiveDevframeInstances, probeDevframeOrigin } from 'devframe/internal'
 import { toAgentToolName } from 'devframe/utils/agent-tool-name'
 import { Diagnostic } from 'devframe/utils/nostics'
-import { joinURL } from 'devframe/utils/url'
+import { joinURL, withLeadingSlash, withTrailingSlash } from 'devframe/utils/url'
 
 export interface ConnectServerOptions {
   /**
    * Explicit ports to probe besides the registry, for instances started
    * before the registry existed, or reachable only by convention. Each port
-   * is probed at `/` (`http://localhost:<port>/__connection.json`).
+   * is probed at {@link ConnectServerOptions.base} (default `/`, i.e.
+   * `http://localhost:<port>/__connection.json`).
    */
   ports?: number[]
+  /**
+   * Base path the explicit {@link ConnectServerOptions.ports} probes look for
+   * `__connection.json` under, for a devframe or hub mounted below the root
+   * of its host (e.g. `/__devtools/` for Vite DevTools). The advertised MCP
+   * path is resolved against it. Default `/`. Registry records carry their
+   * own base and ignore this.
+   */
+  base?: string
   /** Override the registry directory (`DEVFRAME_INSTANCES_DIR` also applies). */
   instancesDir?: string
   /** Probe timeout per instance, ms. Default 1000. */
@@ -164,7 +173,7 @@ async function index(options: ConnectServerOptions): Promise<unknown> {
   for (const port of options.ports ?? []) {
     if (records.some(r => r.port === port))
       continue
-    const probed = await probePort(port, options.timeoutMs)
+    const probed = await probePort(port, options.base, options.timeoutMs)
     if (probed)
       records.push(probed)
   }
@@ -189,26 +198,29 @@ async function index(options: ConnectServerOptions): Promise<unknown> {
   return {
     instances,
     ...(instances.length === 0
-      ? { hint: 'No running devframe instances found. Start a devframe dev server (with --mcp for tools), or pass --port <n> to devframe connect if the instance predates the registry.' }
+      ? { hint: 'No running devframe instances found. Start a devframe dev server (with --mcp for tools), or pass --port <n> to devframe connect if the instance predates the registry (plus --base <path> when it is mounted below the root, e.g. --base /__devtools/).' }
       : {}),
   }
 }
 
 /**
- * Probe an explicit port for a devframe serving `__connection.json` at `/`,
- * reusing the registry's origin-candidate probe (a `localhost`-bound server
- * may listen on either address family).
+ * Probe an explicit port for a devframe serving `__connection.json` under
+ * `base` (default `/`), reusing the registry's origin-candidate probe (a
+ * `localhost`-bound server may listen on either address family). The
+ * advertised MCP path is relative to that base, as in the registry records
+ * the instance shell writes. Exported for focused tests.
  */
-async function probePort(port: number, timeoutMs?: number): Promise<DevframeInstanceRecord | null> {
-  const probed = await probeDevframeOrigin(`http://localhost:${port}`, '/', timeoutMs)
+export async function probePort(port: number, base = '/', timeoutMs?: number): Promise<DevframeInstanceRecord | null> {
+  const basePath = withTrailingSlash(withLeadingSlash(base))
+  const probed = await probeDevframeOrigin(`http://localhost:${port}`, basePath, timeoutMs)
   if (!probed)
     return null
-  const mcpPath = probed.meta.mcp ? joinURL('/', probed.meta.mcp.path) : null
+  const mcpPath = probed.meta.mcp ? joinURL(basePath, probed.meta.mcp.path) : null
   return {
     pid: -1,
     port,
     origin: probed.origin,
-    basePath: '/',
+    basePath,
     id: `port-${port}`,
     rootDir: '',
     mcp: mcpPath ? { path: mcpPath } : null,
@@ -232,7 +244,7 @@ async function call(
     timeoutMs: options.timeoutMs,
   })
   const record = live.find(record => record.port === args.port && record.mcp)
-    ?? await probePort(args.port, options.timeoutMs)
+    ?? await probePort(args.port, options.base, options.timeoutMs)
   if (!record)
     throw diagnostics.DF0050({ port: args.port })
   if (!record.mcp)

packages/devframe/src/cli/main.test.ts

@@ -33,5 +33,6 @@ describe('runDevframeCli', () => {
     await runDevframeCli(['node', 'devframe', 'connect', '--help'])
     expect(info).toHaveBeenCalledTimes(1)
     expect(info.mock.calls[0]![0]).toContain('--port')
+    expect(info.mock.calls[0]![0]).toContain('--base <path>')
   })
 })

packages/devframe/src/cli/main.ts

@@ -7,6 +7,7 @@ import { importRuntimeModule } from '../node/import-runtime-module'
 interface AgenticConnectModule {
   startConnectServer: (options: {
     ports?: number[]
+    base?: string
     instancesDir?: string
     timeoutMs?: number
     authToken?: string
@@ -46,12 +47,14 @@ export async function runDevframeCli(argv: string[] = process.argv): Promise<voi
   cli
     .command('connect', 'Run the devframe MCP connector on stdio (discovers running devframe dev servers and proxies their tools)')
     .option('--port <port>', 'Probe an explicit port besides the instance registry (repeatable)')
+    .option('--base <path>', 'Base path the --port probes look for __connection.json under, for a devframe mounted below the root (e.g. /__devtools/ for Vite DevTools)', { default: '/' })
     .option('--instances-dir <dir>', 'Override the instance registry directory (default: ~/.devframe/instances, or $DEVFRAME_INSTANCES_DIR)')
     .option('--timeout <ms>', 'Probe timeout per instance in milliseconds', { default: 1000 })
-    .action(async (options: { port?: unknown, instancesDir?: string, timeout?: number }) => {
+    .action(async (options: { port?: unknown, base?: unknown, instancesDir?: string, timeout?: number }) => {
       const { startConnectServer } = await importConnect()
       await startConnectServer({
         ports: parsePortsFlag(options.port),
+        base: typeof options.base === 'string' ? options.base : undefined,
         instancesDir: options.instancesDir,
         timeoutMs: options.timeout,
         /**

tests/__snapshots__/tsnapi/@devframes/agentic/connect.snapshot.d.ts

@@ -7,6 +7,7 @@ export interface ConnectServerHandle {
 }
 export interface ConnectServerOptions {
   ports?: number[];
+  base?: string;
   instancesDir?: string;
   timeoutMs?: number;
   authToken?: string | ((_: DevframeInstanceRecord) => string | undefined);
@@ -15,6 +16,7 @@ export interface ConnectServerOptions {
 
 // #region Functions
 export declare function buildInstanceRequestHeaders(_: string, _: string | undefined): Record<string, string>;
+export declare function probePort(_: number, _?: string, _?: number): Promise<DevframeInstanceRecord | null>;
 export declare function resolveAuthToken(_: ConnectServerOptions['authToken'], _: DevframeInstanceRecord): string | undefined;
 export declare function startConnectServer(_?: ConnectServerOptions): Promise<ConnectServerHandle>;
 // #endregion

tests/__snapshots__/tsnapi/@devframes/agentic/connect.snapshot.js

@@ -3,6 +3,7 @@
  */
 // #region Functions
 export function buildInstanceRequestHeaders(_, _) {}
+export async function probePort(_, _, _) {}
 export function resolveAuthToken(_, _) {}
 export async function startConnectServer(_) {}
 // #endregion