incur 0.4.9 → 0.4.11

package/src/Cli.ts

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs/promises'
 import * as os from 'node:os'
 import * as path from 'node:path'
+import { PassThrough } from 'node:stream'
 import { estimateTokenCount, sliceByTokens } from 'tokenx'
 import { z } from 'zod'
 
@@ -1002,12 +1003,16 @@ async function serveImpl(
     return
   }
 
-  // mcp add: register CLI as MCP server via `npx add-mcp`
+  // mcp add/doctor: register or smoke-test CLI MCP server integration.
   const mcpIdx = builtinIdx(filtered, name, 'mcp')
   if (mcpIdx !== -1) {
+    const builtin = findBuiltin('mcp')!
     const mcpSub = filtered[mcpIdx + 1]
-    if (mcpSub && mcpSub !== 'add') {
-      const suggestion = suggest(mcpSub, ['add'])
+    const sub = mcpSub ? findBuiltinSubcommand(builtin, mcpSub) : undefined
+    if (mcpSub && !sub) {
+      const candidates =
+        builtin.subcommands?.flatMap((sub) => [sub.name, ...(sub.aliases ?? [])]) ?? []
+      const suggestion = suggest(mcpSub, candidates)
       const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
       const message = `'${mcpSub}' is not a command for '${name} mcp'.${didYouMean}`
       const ctaCommands: FormattedCta[] = []
@@ -1028,13 +1033,17 @@ async function serveImpl(
       return
     }
     if (!mcpSub) {
-      const b = findBuiltin('mcp')!
-      writeln(formatBuiltinHelp(name, b))
+      writeln(formatBuiltinHelp(name, builtin))
       return
     }
     if (help) {
-      const b = findBuiltin('mcp')!
-      writeln(formatBuiltinSubcommandHelp(name, b, 'add'))
+      writeln(formatBuiltinSubcommandHelp(name, builtin, sub!.name))
+      return
+    }
+    if (sub!.name === 'doctor') {
+      const result = await runMcpDoctor(name, commands, options)
+      writeln(Formatter.format(result, formatExplicit ? formatFlag : 'toon'))
+      if (!result.ok) exit(1)
       return
     }
     const rest = filtered.slice(mcpIdx + 2)
@@ -2713,6 +2722,136 @@ function formatBuiltinSubcommandHelp(
   })
 }
 
+type McpDoctorResult = {
+  ok: boolean
+  toolCount: number
+  tools: { name: string; description?: string | undefined }[]
+  warnings: string[]
+  errors: { code: string; message: string }[]
+}
+
+async function runMcpDoctor(
+  name: string,
+  commands: Map<string, CommandEntry>,
+  options: serveImpl.Options,
+): Promise<McpDoctorResult> {
+  const warnings: string[] = []
+  const errors: McpDoctorResult['errors'] = []
+  const input = new PassThrough()
+  const output = new PassThrough()
+  const chunks: string[] = []
+  output.on('data', (chunk) => chunks.push(chunk.toString()))
+
+  let serveError: unknown
+  const done = Mcp.serve(name, options.version ?? '0.0.0', commands, {
+    input,
+    output,
+    middlewares: options.middlewares,
+    env: options.envSchema,
+    vars: options.vars,
+    version: options.version,
+    ...(options.mcp?.instructions ? { instructions: options.mcp.instructions } : undefined),
+  }).catch((error) => {
+    serveError = error
+  })
+
+  input.write(
+    `${Json.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'incur-doctor', version: '1.0.0' },
+      },
+    })}\n`,
+  )
+  input.write(`${Json.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} })}\n`)
+  await new Promise((resolve) => setTimeout(resolve, 20))
+  input.end()
+  await done
+
+  if (serveError)
+    return {
+      ok: false,
+      toolCount: 0,
+      tools: [],
+      warnings,
+      errors: [{ code: 'MCP_SERVER_FAILED', message: errorMessage(serveError) }],
+    }
+
+  let responses: Record<string, unknown>[]
+  try {
+    responses = parseMcpDoctorResponses(chunks)
+  } catch (error) {
+    return {
+      ok: false,
+      toolCount: 0,
+      tools: [],
+      warnings,
+      errors: [{ code: 'MCP_RESPONSE_PARSE_FAILED', message: errorMessage(error) }],
+    }
+  }
+
+  const initialize = responses.find((response) => response.id === 1)
+  if (!initialize)
+    errors.push({ code: 'MCP_INITIALIZE_MISSING', message: 'Missing initialize response.' })
+  else if (initialize.error)
+    errors.push({ code: 'MCP_INITIALIZE_FAILED', message: mcpErrorMessage(initialize.error) })
+
+  const toolsList = responses.find((response) => response.id === 2)
+  let tools: McpDoctorResult['tools'] = []
+  if (!toolsList)
+    errors.push({ code: 'MCP_TOOLS_LIST_MISSING', message: 'Missing tools/list response.' })
+  else if (toolsList.error)
+    errors.push({ code: 'MCP_TOOLS_LIST_FAILED', message: mcpErrorMessage(toolsList.error) })
+  else if (!isRecord(toolsList.result) || !Array.isArray(toolsList.result.tools))
+    errors.push({
+      code: 'MCP_TOOLS_LIST_INVALID',
+      message: 'tools/list did not return a tools array.',
+    })
+  else
+    tools = toolsList.result.tools
+      .filter(isRecord)
+      .map((tool) => ({
+        name: typeof tool.name === 'string' ? tool.name : '',
+        ...(typeof tool.description === 'string' ? { description: tool.description } : undefined),
+      }))
+      .filter((tool) => tool.name)
+
+  if (errors.length === 0 && tools.length === 0) warnings.push('No MCP tools exposed.')
+
+  return {
+    ok: errors.length === 0,
+    toolCount: tools.length,
+    tools,
+    warnings,
+    errors,
+  }
+}
+
+function parseMcpDoctorResponses(chunks: string[]): Record<string, unknown>[] {
+  const responses: Record<string, unknown>[] = []
+  for (const line of chunks.join('').split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    const parsed = JSON.parse(trimmed)
+    if (!isRecord(parsed)) throw new Error('Expected JSON-RPC response object.')
+    responses.push(parsed)
+  }
+  return responses
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function mcpErrorMessage(error: unknown): string {
+  if (isRecord(error) && typeof error.message === 'string') return error.message
+  return Json.stringify(error)
+}
+
 /** @internal Formats help text for a fetch gateway command. */
 function formatFetchHelp(name: string, description?: string): string {
   const lines: string[] = []
@@ -3492,6 +3631,10 @@ type CommandDefinition<
   /** MCP-specific metadata exposed when this command is served as a tool. */
   mcp?:
     | {
+        /** Override the command name exposed to MCP clients. */
+        name?: string | undefined
+        /** Override the command description exposed to MCP clients. */
+        description?: string | undefined
         /** MCP tool annotations that describe tool behavior to clients. */
         annotations?: Mcp.ToolAnnotations | undefined
         /** Tool-specific instructions surfaced to MCP clients. */

package/src/Completions.test.ts

@@ -599,6 +599,7 @@ describe('serve integration', () => {
       _COMPLETE_INDEX: '2',
     })
     expect(output).toContain('add')
+    expect(output).toContain('doctor')
   })
 
   test('COMPLETE=zsh with words outputs candidates in zsh format', async () => {

package/src/Help.test.ts

@@ -392,7 +392,7 @@ describe('formatRoot', () => {
 
       Integrations:
         completions  Generate shell completion script
-        mcp add      Register as MCP server
+        mcp          Register as MCP server (add, doctor)
         skills       Sync skill files to agents (add, list)
 
       Global Options:

package/src/Mcp.test.ts

@@ -84,14 +84,21 @@ async function mcpSession(
     input.write(`${JSON.stringify(rpc)}\n`)
   }
 
-  // Give time for async processing then close
-  await new Promise((r) => setTimeout(r, 20))
+  await waitForResponses(chunks, messages.filter((msg) => msg.id !== undefined).length)
   input.end()
   await done
 
   return chunks.map((c) => JSON.parse(c.trim()))
 }
 
+async function waitForResponses(chunks: string[], expected: number) {
+  const started = Date.now()
+  while (chunks.length < expected) {
+    if (Date.now() - started > 1_000) return
+    await new Promise((r) => setTimeout(r, 5))
+  }
+}
+
 describe('Mcp', () => {
   test('initialize responds with server info', async () => {
     const [res] = await mcpSession(createTestCommands(), [
@@ -134,6 +141,54 @@ describe('Mcp', () => {
     expect(echoTool.inputSchema.required).toContain('message')
   })
 
+  test('tools/list uses command MCP name and description overrides', async () => {
+    const commands = new Map<string, any>()
+    commands.set('whoami', {
+      description: 'Show wallet identity',
+      mcp: {
+        name: 'get_balance',
+        description: 'Get wallet balance',
+      },
+      run() {
+        return { balance: '1.00' }
+      },
+    })
+
+    const [, listRes] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/list', params: {} },
+    ])
+    const names = listRes.result.tools.map((tool: any) => tool.name)
+    expect(names).toEqual(['get_balance'])
+    expect(listRes.result.tools[0].description).toBe('Get wallet balance')
+
+    const [, callRes] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'get_balance', arguments: {} } },
+    ])
+    expect(callRes.result.content).toEqual([{ type: 'text', text: '{"balance":"1.00"}' }])
+  })
+
+  test('collectTools rejects duplicate MCP tool names', () => {
+    const commands = new Map<string, any>()
+    commands.set('whoami', {
+      mcp: { name: 'get_balance' },
+      run() {
+        return { balance: '1.00' }
+      },
+    })
+    commands.set('balance', {
+      mcp: { name: 'get_balance' },
+      run() {
+        return { balance: '1.00' }
+      },
+    })
+
+    expect(() => Mcp.collectTools(commands, [])).toThrowError(
+      'Duplicate MCP tool name: get_balance',
+    )
+  })
+
   test('notifications are ignored (no response)', async () => {
     const responses = await mcpSession(createTestCommands(), [
       { id: 1, method: 'initialize', params: initParams },
@@ -208,6 +263,54 @@ describe('Mcp', () => {
     expect(res.result.structuredContent).toEqual({ expiry: '2461152330' })
   })
 
+  test('tools/list tolerates non-object output schemas', async () => {
+    const commands = new Map<string, any>()
+    commands.set('list', {
+      description: 'List records',
+      output: z.array(z.object({ id: z.string() })),
+      run() {
+        return [{ id: 'foo' }]
+      },
+    })
+    commands.set('count', {
+      description: 'Count records',
+      output: z.number(),
+      run() {
+        return 1
+      },
+    })
+    commands.set('show', {
+      description: 'Show record',
+      output: z.object({ id: z.string() }),
+      run() {
+        return { id: 'foo' }
+      },
+    })
+
+    const tools = Mcp.collectTools(commands, [])
+    expect(tools.find((tool) => tool.name === 'list')?.outputSchema).toBeUndefined()
+    expect(tools.find((tool) => tool.name === 'count')?.outputSchema).toBeUndefined()
+    expect(tools.find((tool) => tool.name === 'show')?.outputSchema?.type).toBe('object')
+
+    const [, listRes] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/list', params: {} },
+    ])
+    expect(listRes.error).toBeUndefined()
+    expect(listRes.result.tools.map((tool: any) => tool.name).sort()).toEqual([
+      'count',
+      'list',
+      'show',
+    ])
+
+    const [, callRes] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'list', arguments: {} } },
+    ])
+    expect(callRes.result.content).toEqual([{ type: 'text', text: '[{"id":"foo"}]' }])
+    expect(callRes.result.structuredContent).toBeUndefined()
+  })
+
   test('tools/call surfaces cta metadata without changing structured content', async () => {
     const commands = new Map<string, any>()
     commands.set('show', {

package/src/Mcp.ts

@@ -1,3 +1,4 @@
+import type { Transport } from '@modelcontextprotocol/server'
 import type { Readable, Writable } from 'node:stream'
 import { z } from 'zod'
 
@@ -15,8 +16,10 @@ export async function serve(
   options: serve.Options = {},
 ): Promise<void> {
   // Lazy: only runs when actually serving MCP, so plain command runs don't pay for the SDK import.
-  const { fromJsonSchema, McpServer, StdioServerTransport } =
-    await import('@modelcontextprotocol/server')
+  const stdio = importStdioModule()
+  const mcp = await import('@modelcontextprotocol/server')
+  const { fromJsonSchema, McpServer } = mcp
+  const StdioServerTransport = await importStdioServerTransport(mcp, stdio)
 
   const server = new McpServer(
     { name, version },
@@ -62,6 +65,40 @@ export async function serve(
   await server.connect(transport)
 }
 
+type StdioServerTransport = new (
+  input?: Readable,
+  output?: Writable,
+  options?: { maxBufferSize?: number | undefined },
+) => Transport
+
+type StdioModule = {
+  StdioServerTransport: StdioServerTransport
+}
+
+type StdioImportResult =
+  | { module: unknown; error?: undefined }
+  | { module?: undefined; error: unknown }
+
+async function importStdioServerTransport(
+  mcp: unknown,
+  stdio: Promise<StdioImportResult>,
+): Promise<StdioServerTransport> {
+  const transport = (mcp as Partial<StdioModule>).StdioServerTransport
+  if (transport) return transport
+
+  const result = await stdio
+  if (result.error) throw result.error
+  return (result.module as StdioModule).StdioServerTransport
+}
+
+function importStdioModule(): Promise<StdioImportResult> {
+  return importModule('@modelcontextprotocol/server/stdio')
+    .then((module) => ({ module }))
+    .catch((error: unknown) => ({ error }))
+}
+
+const importModule = (specifier: string): Promise<unknown> => import(specifier)
+
 export declare namespace serve {
   /** Options for the MCP server. */
   type Options = {
@@ -221,13 +258,12 @@ export function collectTools(
       ]
       result.push(...collectTools(entry.commands, path, groupMw))
     } else {
+      const outputSchema = entry.output ? mcpOutputSchema(entry.output) : undefined
       result.push({
-        name: path.join('_'),
-        description: entry.description,
+        name: entry.mcp?.name ?? path.join('_'),
+        description: entry.mcp?.description ?? entry.description,
         inputSchema: buildToolSchema(entry.args, entry.options),
-        ...(entry.output
-          ? { outputSchema: Schema.toJsonSchema(entry.output) as Record<string, unknown> }
-          : undefined),
+        ...(outputSchema ? { outputSchema } : undefined),
         ...(entry.mcp?.annotations ? { annotations: entry.mcp.annotations } : undefined),
         ...(entry.mcp?.instructions ? { instructions: entry.mcp.instructions } : undefined),
         command: entry,
@@ -235,9 +271,24 @@ export function collectTools(
       })
     }
   }
+  assertUniqueToolNames(result)
   return result.sort((a, b) => a.name.localeCompare(b.name))
 }
 
+function assertUniqueToolNames(tools: ToolEntry[]) {
+  const seen = new Set<string>()
+  for (const tool of tools) {
+    if (seen.has(tool.name)) throw new Error(`Duplicate MCP tool name: ${tool.name}`)
+    seen.add(tool.name)
+  }
+}
+
+function mcpOutputSchema(output: any): Record<string, unknown> | undefined {
+  const schema = Schema.toJsonSchema(output) as Record<string, unknown>
+  if (schema.type === 'object') return schema
+  return undefined
+}
+
 /** @internal Builds a merged JSON Schema from args and options Zod schemas. */
 function buildToolSchema(
   args: any | undefined,

package/src/e2e.test.ts

@@ -984,7 +984,7 @@ describe('help', () => {
 
       Integrations:
         completions  Generate shell completion script
-        mcp add      Register as MCP server
+        mcp          Register as MCP server (add, doctor)
         skills       Sync skill files to agents (add, list)
 
       Global Options:
@@ -1759,7 +1759,7 @@ describe('root command with subcommands', () => {
 
       Integrations:
         completions  Generate shell completion script
-        mcp add      Register as MCP server
+        mcp          Register as MCP server (add, doctor)
         skills       Sync skill files to agents (add, list)
 
       Global Options:
@@ -2436,7 +2436,7 @@ describe('hosted OpenAPI CLI', () => {
 
         Integrations:
           completions  Generate shell completion script
-          mcp add      Register as MCP server
+          mcp          Register as MCP server (add, doctor)
           skills       Sync skill files to agents (add, list)
 
         Global Options:
@@ -2517,7 +2517,7 @@ describe('hosted OpenAPI CLI', () => {
 
         Integrations:
           completions  Generate shell completion script
-          mcp add      Register as MCP server
+          mcp          Register as MCP server (add, doctor)
           skills       Sync skill files to agents (add, list)
 
         Global Options:

package/src/internal/command.ts

@@ -419,6 +419,10 @@ export const builtinCommands = [
           noGlobal: z.boolean().optional().describe('Install to project instead of globally'),
         }),
       }),
+      subcommand({
+        name: 'doctor',
+        description: 'Validate MCP server startup and tool listing',
+      }),
     ],
   },
   {