feat(mcp): elicitation — server-initiated structured input requests (#117)

Implements MCP elicitation (DEVELOPMENT_PLAN §3.3, form mode), the last
browser-free MCP capability. A server can ask the user for structured input
mid-tool-call via elicitation/create; DeepCode collects it and replies.

core (mcp/client.ts):
- connectMcpServer accepts ConnectMcpOpts.elicit. When provided, the client
  advertises the `elicitation` capability and registers an ElicitRequestSchema
  handler that routes `{ server, message, requestedSchema }` to the host
  callback, returning its { action: accept|decline|cancel, content? }.
  Omitting the handler leaves the capability undeclared (servers won't elicit).
- connectAllMcpServers threads `elicit` through to every server.

cli (repl.ts):
- Provides an interactive elicit callback (via a const holder filled once
  readline exists): prints the server's message, prompts for each field in
  requestedSchema.properties, returns accept{content} or cancel. Headless stays
  non-interactive (no handler → no elicitation).

Tests: +2 (a real spawned stdio server whose tool calls server.elicitInput →
client routes to the host handler → accepted content flows back into the tool
result; and: no handler → capability undeclared → the server's elicit errors
and the tool surfaces isError rather than hanging). Core MCP suite 31 green.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: oratis

apps/cli/src/repl.ts

@@ -21,6 +21,7 @@ import {
   getMcpPrompt,
   mcpPromptCommands,
   resolveMcpPromptInvocation,
+  type McpElicitHandler,
   expandCommandBody,
   findCustomCommand,
   findStyle,
@@ -161,12 +162,19 @@ export async function startRepl(opts: ReplOpts): Promise<number> {
   // M3c: connect MCP servers (best-effort; individual failures don't abort)
   let mcpServers: McpClientHandle[] = [];
   let mcpErrors: Array<{ serverName: string; error: string }> = [];
+  // Elicitation handler holder — filled once the readline interface exists
+  // (below). Until then (and there's nothing to elicit at connect time) it
+  // cancels. Servers see the `elicitation` capability via this passthrough.
+  const elicitHolder: { fn?: McpElicitHandler } = {};
+  const elicitForServers: McpElicitHandler = (req) =>
+    elicitHolder.fn ? elicitHolder.fn(req) : Promise.resolve({ action: 'cancel' });
   if (settings.mcpServers && Object.keys(settings.mcpServers).length > 0) {
     const enabled = settings.enabledMcpjsonServers;
     const disabled = settings.disabledMcpjsonServers ?? [];
     const result = await connectAllMcpServers(settings.mcpServers, {
       enabledOnly: enabled,
       disabled,
+      elicit: elicitForServers,
     });
     mcpServers = result.handles;
     mcpErrors = result.errors;
@@ -285,6 +293,23 @@ export async function startRepl(opts: ReplOpts): Promise<number> {
 
   const rl = createInterface({ input: opts.input, output, terminal: true });
 
+  // Now that readline exists, let MCP servers elicit structured input from the
+  // user: print the server's message, prompt for each requested field.
+  elicitHolder.fn = async (req) => {
+    output.write(`\n  ⊞ ${req.server} requests input: ${req.message}\n`);
+    const props = (req.requestedSchema.properties ?? {}) as Record<
+      string,
+      { description?: string }
+    >;
+    const content: Record<string, string> = {};
+    for (const [key, spec] of Object.entries(props)) {
+      const label = spec.description ? `${key} (${spec.description})` : key;
+      const ans = (await rl.question(`     ${label}: `)).trim();
+      if (ans) content[key] = ans;
+    }
+    return Object.keys(content).length > 0 ? { action: 'accept', content } : { action: 'cancel' };
+  };
+
   let ctrlCCount = 0;
   rl.on('SIGINT', () => {
     ctrlCCount++;

packages/core/src/index.ts

@@ -208,6 +208,10 @@ export {
   type ResourceRef,
   type ExpandResourcesResult,
   type McpPromptCommand,
+  type McpElicitRequest,
+  type McpElicitResult,
+  type McpElicitHandler,
+  type ConnectMcpOpts,
 } from './mcp/index.js';
 
 // Plugins (M5 — manifest + hash pin; M5.1 — subprocess runtime + RPC bridge;

packages/core/src/mcp/client.test.ts

@@ -49,12 +49,24 @@ async function writeFakeServer(
     arguments?: Array<{ name: string; required?: boolean }>;
     text: string;
   }>,
+  /** When set, the named tool triggers a server→client elicitation/create. */
+  elicit?: { toolName: string; message: string; requestedSchema: object },
 ): Promise<string> {
   const serverPath = join(dir, `${name}.mjs`);
   const capList = ['tools: {}'];
   if (resources) capList.push('resources: {}');
   if (prompts) capList.push('prompts: {}');
   const caps = `{ ${capList.join(', ')} }`;
+  const elicitBranch = elicit
+    ? `
+  if (req.params.name === ${JSON.stringify(elicit.toolName)}) {
+    const r = await server.elicitInput({
+      message: ${JSON.stringify(elicit.message)},
+      requestedSchema: ${JSON.stringify(elicit.requestedSchema)},
+    });
+    return { content: [{ type: 'text', text: 'elicited:' + JSON.stringify(r) }] };
+  }`
+    : '';
   const resourceBlock = resources
     ? `
 import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '${TYPES_INDEX}';
@@ -103,7 +115,7 @@ const server = new Server(
 const TOOLS = ${JSON.stringify(tools)};
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
+server.setRequestHandler(CallToolRequestSchema, async (req) => {${elicitBranch}
   const argsStr = JSON.stringify(req.params.arguments);
   return {
     content: [{ type: 'text', text: 'called: ' + req.params.name + ' args: ' + argsStr }],
@@ -326,6 +338,76 @@ describe('MCP client', () => {
       await handle.close();
     }
   }, 20_000);
+
+  it('routes a server elicitation/create request to the host elicit handler', async () => {
+    const serverScript = await writeFakeServer(
+      tmp,
+      'forms',
+      [
+        {
+          name: 'ask',
+          description: 'asks for input',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+      undefined,
+      undefined,
+      {
+        toolName: 'ask',
+        message: 'What is your name?',
+        requestedSchema: {
+          type: 'object',
+          properties: { name: { type: 'string' } },
+          required: ['name'],
+        },
+      },
+    );
+    let seen: { server: string; message: string } | null = null;
+    const handle = await connectMcpServer(
+      'forms',
+      { command: 'node', args: [serverScript] },
+      {
+        elicit: async (req) => {
+          seen = { server: req.server, message: req.message };
+          return { action: 'accept', content: { name: 'Ada' } };
+        },
+      },
+    );
+    try {
+      const ask = handle.tools.find((t) => t.name === 'mcp__forms__ask')!;
+      const result = await ask.execute({}, { cwd: tmp });
+      // The host handler was invoked with the server's prompt...
+      expect(seen).toEqual({ server: 'forms', message: 'What is your name?' });
+      // ...and the accepted content flowed back to the server's tool result.
+      expect(result.content).toContain('elicited:');
+      expect(result.content).toContain('"action":"accept"');
+      expect(result.content).toContain('"name":"Ada"');
+    } finally {
+      await handle.close();
+    }
+  }, 20_000);
+
+  it('does not advertise elicitation when no handler is supplied', async () => {
+    // A server that tries to elicit against a client without the capability
+    // gets an error from its elicitInput call; the tool surfaces it (no hang).
+    const serverScript = await writeFakeServer(
+      tmp,
+      'forms2',
+      [{ name: 'ask', description: 'asks', inputSchema: { type: 'object', properties: {} } }],
+      undefined,
+      undefined,
+      { toolName: 'ask', message: 'name?', requestedSchema: { type: 'object', properties: {} } },
+    );
+    const handle = await connectMcpServer('forms2', { command: 'node', args: [serverScript] });
+    try {
+      const ask = handle.tools.find((t) => t.name === 'mcp__forms2__ask')!;
+      const result = await ask.execute({}, { cwd: tmp });
+      // elicitInput rejects (client lacks the capability) → tool reports an error.
+      expect(result.isError).toBe(true);
+    } finally {
+      await handle.close();
+    }
+  }, 20_000);
 });
 
 describe('pickTransportKind', () => {

packages/core/src/mcp/client.ts

@@ -13,6 +13,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ElicitRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { McpServerConfig } from '../config/types.js';
 import type { ToolDefinition, ToolHandler, ToolResult } from '../types.js';
@@ -43,6 +44,35 @@ export interface McpPromptMeta {
   arguments?: Array<{ name: string; description?: string; required?: boolean }>;
 }
 
+/**
+ * A server-initiated request for structured input (elicitation/create, form
+ * mode). The host answers by collecting the fields described by `requestedSchema`.
+ */
+export interface McpElicitRequest {
+  server: string;
+  message: string;
+  /** JSON Schema (object) describing the fields the server wants. */
+  requestedSchema: Record<string, unknown>;
+}
+
+export type McpElicitResult =
+  | { action: 'accept'; content: Record<string, unknown> }
+  | { action: 'decline' }
+  | { action: 'cancel' };
+
+/** Host callback that answers a server's elicitation request. */
+export type McpElicitHandler = (req: McpElicitRequest) => Promise<McpElicitResult>;
+
+export interface ConnectMcpOpts {
+  /**
+   * Handler for server-initiated elicitation (structured input) requests. When
+   * provided, the client advertises the `elicitation` capability and routes
+   * `elicitation/create` requests here. Omit in non-interactive hosts so
+   * servers know not to elicit.
+   */
+  elicit?: McpElicitHandler;
+}
+
 export interface McpClientHandle {
   serverName: string;
   client: Client;
@@ -145,6 +175,7 @@ async function buildTransport(
 export async function connectMcpServer(
   serverName: string,
   config: McpServerConfig,
+  opts: ConnectMcpOpts = {},
 ): Promise<McpClientHandle> {
   const kind = pickTransportKind(config);
   if (!kind) {
@@ -153,7 +184,22 @@ export async function connectMcpServer(
     );
   }
   const transport = await buildTransport(serverName, config, kind);
-  const client = new Client({ name: 'deepcode', version: '0.1.0' }, { capabilities: {} });
+  // Advertise elicitation support only when the host gave us a handler — an
+  // empty `elicitation: {}` capability means form mode (SDK default).
+  const capabilities = opts.elicit ? { elicitation: {} } : {};
+  const client = new Client({ name: 'deepcode', version: '0.1.0' }, { capabilities });
+  if (opts.elicit) {
+    const elicit = opts.elicit;
+    // Register before connect so an early server request can't race the handler.
+    client.setRequestHandler(ElicitRequestSchema, async (req) => {
+      const params = req.params as { message?: string; requestedSchema?: Record<string, unknown> };
+      return elicit({
+        server: serverName,
+        message: params.message ?? '',
+        requestedSchema: params.requestedSchema ?? { type: 'object', properties: {} },
+      });
+    });
+  }
   await client.connect(transport);
 
   // List the tools the server exposes
@@ -430,7 +476,7 @@ export interface ConnectAllResult {
 
 export async function connectAllMcpServers(
   servers: Record<string, McpServerConfig>,
-  opts: { enabledOnly?: string[]; disabled?: string[] } = {},
+  opts: { enabledOnly?: string[]; disabled?: string[]; elicit?: McpElicitHandler } = {},
 ): Promise<ConnectAllResult> {
   const handles: McpClientHandle[] = [];
   const errors: Array<{ serverName: string; error: string }> = [];
@@ -441,7 +487,7 @@ export async function connectAllMcpServers(
     if (enabled && !enabled.has(name)) continue;
     if (disabled.has(name)) continue;
     try {
-      const handle = await connectMcpServer(name, cfg);
+      const handle = await connectMcpServer(name, cfg, { elicit: opts.elicit });
       handles.push(handle);
     } catch (err) {
       errors.push({ serverName: name, error: (err as Error).message });

packages/core/src/mcp/index.ts

@@ -24,6 +24,10 @@ export {
   type ResourceRef,
   type ExpandResourcesResult,
   type McpPromptCommand,
+  type McpElicitRequest,
+  type McpElicitResult,
+  type McpElicitHandler,
+  type ConnectMcpOpts,
 } from './client.js';
 
 export {