fix(cli): preserve MCP discovery metadata

Author: posva

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

@@ -4,7 +4,7 @@ import type { DevframeDefinition } from '../types/devframe'
 import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
 import { afterEach, describe, expect, it } from 'vitest'
 import { createDevServer } from '../adapters/dev'
-import { buildInstanceRequestHeaders, resolveAuthToken } from './connect'
+import { buildInstanceRequestHeaders, resolveAuthToken, selectInstanceRecord, toIndexedTool } from './connect'
 
 const TOKEN = 'a-high-entropy-connect-test-token'
 
@@ -60,6 +60,39 @@ describe('buildInstanceRequestHeaders', () => {
   })
 })
 
+describe('selectInstanceRecord', () => {
+  it('prefers an MCP-capable base when several instances share a port', () => {
+    const withoutMcp = makeRecord({ id: 'ui-only', mcp: null })
+    const withMcp = makeRecord({ id: 'vite-devtools', basePath: '/__devtools/' })
+
+    expect(selectInstanceRecord([withoutMcp, withMcp], 9999)).toBe(withMcp)
+  })
+})
+
+describe('connector discovery metadata', () => {
+  it('keeps downstream tool schemas available to gateway agents', () => {
+    expect(toIndexedTool({
+      name: 'refetch',
+      description: 'Refetch queries.',
+      inputSchema: {
+        type: 'object',
+        properties: { arg0: { type: 'object' } },
+        required: ['arg0'],
+      },
+      annotations: { readOnlyHint: false },
+    })).toEqual({
+      name: 'refetch',
+      description: 'Refetch queries.',
+      inputSchema: {
+        type: 'object',
+        properties: { arg0: { type: 'object' } },
+        required: ['arg0'],
+      },
+      annotations: { readOnlyHint: false },
+    })
+  })
+})
+
 describe('connector bearer against a live authenticated MCP route', () => {
   let server: StartedServer | undefined
 

packages/devframe/src/cli/connect.ts

@@ -66,10 +66,19 @@ export interface ConnectServerHandle {
 }
 
 /** One discovered instance in the `list-instances` payload: the registry record plus its probed MCP surface. */
+interface IndexedTool {
+  name: string
+  title?: string
+  description?: string
+  inputSchema: unknown
+  outputSchema?: unknown
+  annotations?: unknown
+}
+
 interface IndexedInstance extends Omit<DevframeInstanceRecord, 'mcp'> {
   mcp: {
     url: string
-    tools?: { name: string, description?: string }[]
+    tools?: IndexedTool[]
     error?: string
   } | null
   hint?: string
@@ -243,16 +252,25 @@ async function probePort(port: number, timeoutMs?: number): Promise<DevframeInst
   }
 }
 
-async function listInstanceTools(sdk: ConnectSdk, url: string, token: string | undefined): Promise<{ name: string, description?: string }[]> {
+async function listInstanceTools(sdk: ConnectSdk, url: string, token: string | undefined): Promise<IndexedTool[]> {
   return withInstanceClient(sdk, url, token, async (client) => {
     const listed = await client.listTools()
-    return listed.tools.map((tool: { name: string, description?: string }) => ({
-      name: tool.name,
-      description: tool.description,
-    }))
+    return listed.tools.map(toIndexedTool)
   })
 }
 
+/** Preserve downstream tool metadata needed by an agent before invocation. */
+export function toIndexedTool(tool: IndexedTool): IndexedTool {
+  return {
+    name: tool.name,
+    ...(tool.title ? { title: tool.title } : {}),
+    ...(tool.description ? { description: tool.description } : {}),
+    inputSchema: tool.inputSchema,
+    ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+    ...(tool.annotations ? { annotations: tool.annotations } : {}),
+  }
+}
+
 async function call(
   sdk: ConnectSdk,
   options: ConnectServerOptions,
@@ -265,7 +283,8 @@ async function call(
     instancesDir: options.instancesDir,
     timeoutMs: options.timeoutMs,
   })
-  const record = live.find(r => r.port === args.port) ?? await probePort(args.port, options.timeoutMs)
+  const record = selectInstanceRecord(live, args.port)
+    ?? await probePort(args.port, options.timeoutMs)
   if (!record)
     throw diagnostics.DF0050({ port: args.port })
   if (!record.mcp)
@@ -284,6 +303,15 @@ async function call(
   })
 }
 
+/** Select the agent-capable instance when several bases share one port. */
+export function selectInstanceRecord(
+  records: readonly DevframeInstanceRecord[],
+  port: number,
+): DevframeInstanceRecord | undefined {
+  const matching = records.filter(record => record.port === port)
+  return matching.find(record => record.mcp) ?? matching[0]
+}
+
 async function withInstanceClient<T>(
   sdk: ConnectSdk,
   url: string,