mcp-rubber-duck 1.9.5 → 1.11.0

package/jest.config.js

@@ -22,5 +22,6 @@ export default {
     'src/**/*.ts',
     '!src/**/*.d.ts',
     '!src/index.ts',
+    '!src/ui/**',
   ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-rubber-duck",
-  "version": "1.9.5",
+  "version": "1.11.0",
   "description": "An MCP server that bridges to multiple OpenAI-compatible LLMs - your AI rubber duck debugging panel",
   "main": "dist/index.js",
   "type": "module",
@@ -8,7 +8,8 @@
     "mcp-rubber-duck": "./dist/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run build:ui",
+    "build:ui": "VITE_UI_ENTRY=compare-ducks vite build && VITE_UI_ENTRY=duck-vote vite build && VITE_UI_ENTRY=duck-debate vite build && VITE_UI_ENTRY=usage-stats vite build",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
@@ -42,6 +43,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.0.1",
     "@modelcontextprotocol/sdk": "^1.24.0",
     "@semantic-release/npm": "^13.1.3",
     "ajv": "^8.17.1",
@@ -65,7 +67,9 @@
     "semantic-release": "^25.0.2",
     "ts-jest": "^29.0.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vite": "^7.3.1",
+    "vite-plugin-singlefile": "^2.3.0"
   },
   "overrides": {
     "js-yaml": "^4.1.1",

package/src/providers/enhanced-manager.ts

@@ -209,6 +209,55 @@ export class EnhancedProviderManager extends ProviderManager {
     return Promise.all(promises);
   }
 
+  async compareDucksWithProgressMCP(
+    prompt: string,
+    providerNames: string[] | undefined,
+    options: Partial<ChatOptions> | undefined,
+    onProviderComplete: (providerName: string, completed: number, total: number) => void
+  ): Promise<Array<DuckResponse & { pendingApprovals?: { id: string; message: string }[]; mcpResults?: MCPResult[] }>> {
+    if (!this.mcpEnabled) {
+      return this.compareDucksWithProgress(prompt, providerNames, options, onProviderComplete);
+    }
+
+    const providersToUse = providerNames
+      ? providerNames.map(name => this.enhancedProviders.get(name)).filter(Boolean)
+      : Array.from(this.enhancedProviders.values());
+
+    if (providersToUse.length === 0) {
+      throw new Error('No valid enhanced providers specified');
+    }
+
+    const total = providersToUse.length;
+    let completed = 0;
+
+    const promises = providersToUse.map(provider =>
+      provider ? this.askDuckWithMCP(provider.name, prompt, options)
+        .catch(error => ({
+          provider: provider.name,
+          nickname: provider.nickname,
+          model: '',
+          content: `Error: ${error instanceof Error ? error.message : String(error)}`,
+          latency: 0,
+          cached: false,
+        }))
+        .then(result => {
+          completed++;
+          onProviderComplete(provider.name, completed, total);
+          return result;
+        })
+      : Promise.resolve({
+          provider: 'unknown',
+          nickname: 'Unknown',
+          model: '',
+          content: 'Error: Invalid provider',
+          latency: 0,
+          cached: false,
+        })
+    );
+
+    return Promise.all(promises);
+  }
+
   async duckCouncilWithMCP(
     prompt: string,
     options?: Partial<ChatOptions>

package/src/providers/manager.ts

@@ -183,6 +183,51 @@ export class ProviderManager {
     return Promise.all(promises);
   }
 
+  async compareDucksWithProgress(
+    prompt: string,
+    providerNames: string[] | undefined,
+    options: Partial<ChatOptions> | undefined,
+    onProviderComplete: (providerName: string, completed: number, total: number) => void
+  ): Promise<DuckResponse[]> {
+    const providersToUse = providerNames
+      ? providerNames.map(name => this.providers.get(name)).filter(Boolean)
+      : Array.from(this.providers.values());
+
+    if (providersToUse.length === 0) {
+      throw new Error('No valid providers specified');
+    }
+
+    const total = providersToUse.length;
+    let completed = 0;
+
+    const promises = providersToUse.map(provider =>
+      provider ? this.askDuck(provider.name, prompt, options)
+        .catch(error => ({
+          provider: provider.name,
+          nickname: provider.nickname,
+          model: '',
+          content: `Error: ${error instanceof Error ? error.message : String(error)}`,
+          latency: 0,
+          cached: false,
+        }))
+        .then(result => {
+          completed++;
+          onProviderComplete(provider.name, completed, total);
+          return result;
+        })
+      : Promise.resolve({
+          provider: 'unknown',
+          nickname: 'Unknown',
+          model: '',
+          content: 'Error: Invalid provider',
+          latency: 0,
+          cached: false,
+        })
+    );
+
+    return Promise.all(promises);
+  }
+
   async duckCouncil(
     prompt: string,
     options?: Partial<ChatOptions>

package/src/server.ts

@@ -2,6 +2,14 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  registerAppTool,
+  registerAppResource,
+  RESOURCE_MIME_TYPE,
+} from '@modelcontextprotocol/ext-apps/server';
 
 import { ConfigManager } from './config/config.js';
 import { ProviderManager } from './providers/manager.js';
@@ -16,6 +24,8 @@ import { DuckResponse } from './config/types.js';
 import { ApprovalService } from './services/approval.js';
 import { FunctionBridge } from './services/function-bridge.js';
 import { GuardrailsService } from './guardrails/service.js';
+import { TaskManager } from './services/task-manager.js';
+import { createProgressReporter } from './services/progress.js';
 import { logger } from './utils/logger.js';
 import { duckArt, getRandomDuckMessage } from './utils/ascii-art.js';
 
@@ -61,13 +71,32 @@ export class RubberDuckServer {
   private functionBridge?: FunctionBridge;
   private mcpEnabled: boolean = false;
 
+  // Task management
+  private taskManager: TaskManager;
+
   constructor() {
+    this.taskManager = new TaskManager();
+
     this.server = new McpServer(
       {
         name: 'mcp-rubber-duck',
         version: '1.0.0',
       },
-      {}
+      {
+        capabilities: {
+          tasks: {
+            list: {},
+            cancel: {},
+            requests: {
+              tools: { call: {} },
+            },
+          },
+        },
+        taskStore: this.taskManager.taskStore,
+        taskMessageQueue: this.taskManager.taskMessageQueue,
+        defaultTaskPollInterval: this.taskManager.config.pollInterval,
+        maxTaskQueueSize: this.taskManager.config.maxQueueSize,
+      }
     );
 
     // Initialize managers
@@ -94,6 +123,7 @@ export class RubberDuckServer {
 
     this.registerTools();
     this.registerPrompts();
+    this.registerUIResources();
 
     // Handle errors
     this.server.server.onerror = (error) => {
@@ -288,7 +318,8 @@ export class RubberDuckServer {
     );
 
     // compare_ducks
-    this.server.registerTool(
+    registerAppTool(
+      this.server,
       'compare_ducks',
       {
         description: 'Ask the same question to multiple ducks simultaneously',
@@ -301,13 +332,15 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: true,
         },
+        _meta: { ui: { resourceUri: 'ui://rubber-duck/compare-ducks' } },
       },
-      async (args) => {
+      async (args, extra) => {
         try {
+          const progress = createProgressReporter(extra._meta?.progressToken, extra.sendNotification);
           if (this.mcpEnabled && this.enhancedProviderManager) {
-            return this.toolResult(await this.handleCompareDucksWithMCP(args as Record<string, unknown>));
+            return this.toolResult(await this.handleCompareDucksWithMCP(args as Record<string, unknown>, progress));
           }
-          return this.toolResult(await compareDucksTool(this.providerManager, args as Record<string, unknown>));
+          return this.toolResult(await compareDucksTool(this.providerManager, args as Record<string, unknown>, progress));
         } catch (error) {
           return this.toolErrorResult(error);
         }
@@ -328,12 +361,13 @@ export class RubberDuckServer {
           openWorldHint: true,
         },
       },
-      async (args) => {
+      async (args, extra) => {
         try {
+          const progress = createProgressReporter(extra._meta?.progressToken, extra.sendNotification);
           if (this.mcpEnabled && this.enhancedProviderManager) {
-            return this.toolResult(await this.handleDuckCouncilWithMCP(args as Record<string, unknown>));
+            return this.toolResult(await this.handleDuckCouncilWithMCP(args as Record<string, unknown>, progress));
           }
-          return this.toolResult(await duckCouncilTool(this.providerManager, args as Record<string, unknown>));
+          return this.toolResult(await duckCouncilTool(this.providerManager, args as Record<string, unknown>, progress));
         } catch (error) {
           return this.toolErrorResult(error);
         }
@@ -341,7 +375,8 @@ export class RubberDuckServer {
     );
 
     // duck_vote
-    this.server.registerTool(
+    registerAppTool(
+      this.server,
       'duck_vote',
       {
         description: 'Have multiple ducks vote on options with reasoning. Returns vote tally, confidence scores, and consensus level.',
@@ -355,10 +390,12 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: true,
         },
+        _meta: { ui: { resourceUri: 'ui://rubber-duck/duck-vote' } },
       },
-      async (args) => {
+      async (args, extra) => {
         try {
-          return this.toolResult(await duckVoteTool(this.providerManager, args as Record<string, unknown>));
+          const progress = createProgressReporter(extra._meta?.progressToken, extra.sendNotification);
+          return this.toolResult(await duckVoteTool(this.providerManager, args as Record<string, unknown>, progress));
         } catch (error) {
           return this.toolErrorResult(error);
         }
@@ -395,8 +432,8 @@ export class RubberDuckServer {
       }
     );
 
-    // duck_iterate
-    this.server.registerTool(
+    // duck_iterate (task-based: supports async execution for long-running iterations)
+    this.server.experimental.tasks.registerToolTask(
       'duck_iterate',
       {
         description: 'Iteratively refine a response between two ducks. One generates, the other critiques/improves, alternating for multiple rounds.',
@@ -410,18 +447,36 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: true,
         },
+        execution: {
+          taskSupport: 'optional',
+        },
       },
-      async (args) => {
-        try {
-          return this.toolResult(await duckIterateTool(this.providerManager, args as Record<string, unknown>));
-        } catch (error) {
-          return this.toolErrorResult(error);
-        }
+      {
+        createTask: async (args, extra) => {
+          const task = await extra.taskStore.createTask({
+            ttl: this.taskManager.config.defaultTtl,
+            pollInterval: this.taskManager.config.pollInterval,
+          });
+          const progress = createProgressReporter(extra._meta?.progressToken, extra.sendNotification);
+          this.taskManager.startBackground(task.taskId, async (signal) => {
+            return this.toolResult(
+              await duckIterateTool(this.providerManager, args as Record<string, unknown>, progress, signal)
+            );
+          });
+          return { task };
+        },
+        getTask: async (_args, extra) => {
+          const task = await extra.taskStore.getTask(extra.taskId);
+          return task;
+        },
+        getTaskResult: async (_args, extra) => {
+          return await extra.taskStore.getTaskResult(extra.taskId) as CallToolResult;
+        },
       }
     );
 
-    // duck_debate
-    this.server.registerTool(
+    // duck_debate (task-based: supports async execution for multi-round debates)
+    this.server.experimental.tasks.registerToolTask(
       'duck_debate',
       {
         description: 'Structured multi-round debate between ducks. Supports oxford (pro/con), socratic (questioning), and adversarial (attack/defend) formats.',
@@ -436,18 +491,38 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: true,
         },
+        _meta: { ui: { resourceUri: 'ui://rubber-duck/duck-debate' } },
+        execution: {
+          taskSupport: 'optional',
+        },
       },
-      async (args) => {
-        try {
-          return this.toolResult(await duckDebateTool(this.providerManager, args as Record<string, unknown>));
-        } catch (error) {
-          return this.toolErrorResult(error);
-        }
+      {
+        createTask: async (args, extra) => {
+          const task = await extra.taskStore.createTask({
+            ttl: this.taskManager.config.defaultTtl,
+            pollInterval: this.taskManager.config.pollInterval,
+          });
+          const progress = createProgressReporter(extra._meta?.progressToken, extra.sendNotification);
+          this.taskManager.startBackground(task.taskId, async (signal) => {
+            return this.toolResult(
+              await duckDebateTool(this.providerManager, args as Record<string, unknown>, progress, signal)
+            );
+          });
+          return { task };
+        },
+        getTask: async (_args, extra) => {
+          const task = await extra.taskStore.getTask(extra.taskId);
+          return task;
+        },
+        getTaskResult: async (_args, extra) => {
+          return await extra.taskStore.getTaskResult(extra.taskId) as CallToolResult;
+        },
       }
     );
 
     // get_usage_stats
-    this.server.registerTool(
+    registerAppTool(
+      this.server,
       'get_usage_stats',
       {
         description: 'Get usage statistics for a time period. Shows token counts and costs (when pricing configured).',
@@ -458,6 +533,7 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: false,
         },
+        _meta: { ui: { resourceUri: 'ui://rubber-duck/usage-stats' } },
       },
       (args) => {
         try {
@@ -581,6 +657,44 @@ export class RubberDuckServer {
     }
   }
 
+  private registerUIResources() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const uiDir = join(currentDir, '..', 'dist', 'ui');
+
+    const uiApps = [
+      { name: 'Compare Ducks', uri: 'ui://rubber-duck/compare-ducks', file: 'compare-ducks/mcp-app.html' },
+      { name: 'Duck Vote', uri: 'ui://rubber-duck/duck-vote', file: 'duck-vote/mcp-app.html' },
+      { name: 'Duck Debate', uri: 'ui://rubber-duck/duck-debate', file: 'duck-debate/mcp-app.html' },
+      { name: 'Usage Stats', uri: 'ui://rubber-duck/usage-stats', file: 'usage-stats/mcp-app.html' },
+    ];
+
+    for (const app of uiApps) {
+      registerAppResource(
+        this.server,
+        app.name,
+        app.uri,
+        { description: `Interactive UI for ${app.name}` },
+        () => {
+          let html: string;
+          try {
+            html = readFileSync(join(uiDir, app.file), 'utf-8');
+          } catch {
+            html = `<html><body><p>UI not built. Run npm run build:ui</p></body></html>`;
+          }
+          return {
+            contents: [
+              {
+                uri: app.uri,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: html,
+              },
+            ],
+          };
+        }
+      );
+    }
+  }
+
   // MCP-enhanced tool handlers
   private async handleAskDuckWithMCP(args: Record<string, unknown>) {
     if (!this.enhancedProviderManager || !this.cache) {
@@ -622,7 +736,7 @@ export class RubberDuckServer {
     };
   }
 
-  private async handleCompareDucksWithMCP(args: Record<string, unknown>) {
+  private async handleCompareDucksWithMCP(args: Record<string, unknown>, progress?: import('./services/progress.js').ProgressReporter) {
     if (!this.enhancedProviderManager) {
       throw new Error('Enhanced provider manager not available');
     }
@@ -633,32 +747,68 @@ export class RubberDuckServer {
       model?: string;
     };
 
-    const responses = await this.enhancedProviderManager.compareDucksWithMCP(prompt, providers, {
-      model,
-    });
+    const responses = progress
+      ? await this.enhancedProviderManager.compareDucksWithProgressMCP(
+          prompt,
+          providers,
+          { model },
+          (providerName, completed, total) => {
+            void progress.report(completed, total, `${providerName} responded (${completed}/${total})`);
+          }
+        )
+      : await this.enhancedProviderManager.compareDucksWithMCP(prompt, providers, { model });
 
     const formattedResponse = responses
       .map((response) => this.formatEnhancedDuckResponse(response))
       .join('\n\n═══════════════════════════════════════\n\n');
 
+    // Build structured data for UI consumption (same shape as compareDucksTool)
+    const structuredData = responses.map(r => ({
+      provider: r.provider,
+      nickname: r.nickname,
+      model: r.model,
+      content: r.content,
+      latency: r.latency,
+      tokens: r.usage ? {
+        prompt: r.usage.prompt_tokens,
+        completion: r.usage.completion_tokens,
+        total: r.usage.total_tokens,
+      } : null,
+      cached: r.cached,
+      error: r.content.startsWith('Error:') ? r.content : undefined,
+    }));
+
     return {
       content: [
         {
           type: 'text' as const,
           text: formattedResponse,
         },
+        {
+          type: 'text' as const,
+          text: JSON.stringify(structuredData),
+        },
       ],
     };
   }
 
-  private async handleDuckCouncilWithMCP(args: Record<string, unknown>) {
+  private async handleDuckCouncilWithMCP(args: Record<string, unknown>, progress?: import('./services/progress.js').ProgressReporter) {
     if (!this.enhancedProviderManager) {
       throw new Error('Enhanced provider manager not available');
     }
 
     const { prompt, model } = args as { prompt: string; model?: string };
 
-    const responses = await this.enhancedProviderManager.duckCouncilWithMCP(prompt, { model });
+    const responses = progress
+      ? await this.enhancedProviderManager.compareDucksWithProgressMCP(
+          prompt,
+          undefined,
+          { model },
+          (providerName, completed, total) => {
+            void progress.report(completed, total, `${providerName} responded (${completed}/${total})`);
+          }
+        )
+      : await this.enhancedProviderManager.duckCouncilWithMCP(prompt, { model });
 
     const header = '🦆 Duck Council in Session 🦆\n=============================';
     const formattedResponse = responses
@@ -764,6 +914,9 @@ export class RubberDuckServer {
   }
 
   async stop() {
+    // Cleanup task manager (cancel active tasks, clear timers)
+    this.taskManager.shutdown();
+
     // Cleanup usage service (flush pending writes)
     this.usageService.shutdown();
 

package/src/services/progress.ts

@@ -0,0 +1,59 @@
+/**
+ * Progress notification service for MCP tools.
+ *
+ * Provides a lightweight abstraction over MCP's stable `notifications/progress`
+ * mechanism. Tool functions accept an optional `ProgressReporter` to emit
+ * per-step progress without depending on the full `RequestHandlerExtra` type.
+ */
+
+export interface ProgressReporter {
+  /** Report that step `current` of `total` is done, with an optional status message. */
+  report(current: number, total: number, message?: string): Promise<void>;
+  /** Whether the client actually requested progress (sent a progressToken). */
+  readonly enabled: boolean;
+}
+
+/**
+ * Creates a `ProgressReporter` from an MCP tool handler's `extra` parameter.
+ *
+ * If the client did not include a `progressToken` in `_meta`, the returned
+ * reporter is a no-op (`.enabled === false`), so callers can always call
+ * `progress.report()` unconditionally.
+ *
+ * @param progressToken   Value of `extra._meta?.progressToken`
+ * @param sendNotification  Value of `extra.sendNotification` — typed loosely to
+ *   avoid coupling to SDK's strict discriminated union. At runtime the SDK
+ *   accepts any valid JSON-RPC notification including `notifications/progress`.
+ */
+export function createProgressReporter(
+  progressToken: string | number | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  sendNotification: (notification: any) => Promise<void>
+): ProgressReporter {
+  if (progressToken === undefined) {
+    return {
+      enabled: false,
+      report: async () => {},
+    };
+  }
+
+  return {
+    enabled: true,
+    report: async (current: number, total: number, message?: string) => {
+      try {
+        await sendNotification({
+          method: 'notifications/progress',
+          params: {
+            progressToken,
+            progress: current,
+            total,
+            ...(message !== undefined ? { message } : {}),
+          },
+        });
+      } catch {
+        // Swallow notification errors (e.g., client disconnected).
+        // Progress is best-effort — tool execution should continue regardless.
+      }
+    },
+  };
+}