mcp-rubber-duck 1.9.5 → 1.10.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.10.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/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';
@@ -94,6 +102,7 @@ export class RubberDuckServer {
 
     this.registerTools();
     this.registerPrompts();
+    this.registerUIResources();
 
     // Handle errors
     this.server.server.onerror = (error) => {
@@ -288,7 +297,8 @@ export class RubberDuckServer {
     );
 
     // compare_ducks
-    this.server.registerTool(
+    registerAppTool(
+      this.server,
       'compare_ducks',
       {
         description: 'Ask the same question to multiple ducks simultaneously',
@@ -301,6 +311,7 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: true,
         },
+        _meta: { ui: { resourceUri: 'ui://rubber-duck/compare-ducks' } },
       },
       async (args) => {
         try {
@@ -341,7 +352,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,6 +367,7 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: true,
         },
+        _meta: { ui: { resourceUri: 'ui://rubber-duck/duck-vote' } },
       },
       async (args) => {
         try {
@@ -421,7 +434,8 @@ export class RubberDuckServer {
     );
 
     // duck_debate
-    this.server.registerTool(
+    registerAppTool(
+      this.server,
       'duck_debate',
       {
         description: 'Structured multi-round debate between ducks. Supports oxford (pro/con), socratic (questioning), and adversarial (attack/defend) formats.',
@@ -436,6 +450,7 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: true,
         },
+        _meta: { ui: { resourceUri: 'ui://rubber-duck/duck-debate' } },
       },
       async (args) => {
         try {
@@ -447,7 +462,8 @@ export class RubberDuckServer {
     );
 
     // 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 +474,7 @@ export class RubberDuckServer {
           readOnlyHint: true,
           openWorldHint: false,
         },
+        _meta: { ui: { resourceUri: 'ui://rubber-duck/usage-stats' } },
       },
       (args) => {
         try {
@@ -581,6 +598,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) {
@@ -641,12 +696,32 @@ export class RubberDuckServer {
       .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),
+        },
       ],
     };
   }

package/src/tools/compare-ducks.ts

@@ -55,12 +55,32 @@ export async function compareDucksTool(
 
   logger.info(`Compared ${responses.length} ducks, ${successCount} successful`);
 
+  // Build structured data for UI consumption
+  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',
         text: response,
       },
+      {
+        type: 'text',
+        text: JSON.stringify(structuredData),
+      },
     ],
   };
 }

package/src/tools/duck-debate.ts

@@ -124,12 +124,39 @@ export async function duckDebateTool(
 
   logger.info(`Debate completed: ${rounds} rounds, synthesized by ${synthesizerProvider}`);
 
+  // Build structured data for UI consumption
+  const structuredData = {
+    topic: result.topic,
+    format: result.format,
+    totalRounds: result.totalRounds,
+    participants: result.participants.map(p => ({
+      provider: p.provider,
+      nickname: p.nickname,
+      position: p.position,
+    })),
+    rounds: result.rounds.map(roundArgs =>
+      roundArgs.map(arg => ({
+        round: arg.round,
+        provider: arg.provider,
+        nickname: arg.nickname,
+        position: arg.position,
+        content: arg.content,
+      }))
+    ),
+    synthesis: result.synthesis,
+    synthesizer: result.synthesizer,
+  };
+
   return {
     content: [
       {
         type: 'text',
         text: formattedOutput,
       },
+      {
+        type: 'text',
+        text: JSON.stringify(structuredData),
+      },
     ],
   };
 }

package/src/tools/duck-vote.ts

@@ -76,12 +76,36 @@ export async function duckVoteTool(
     `winner: ${aggregatedResult.winner || 'none'}`
   );
 
+  // Build structured data for UI consumption
+  const structuredData = {
+    question: aggregatedResult.question,
+    options: aggregatedResult.options,
+    winner: aggregatedResult.winner,
+    isTie: aggregatedResult.isTie,
+    tally: aggregatedResult.tally,
+    confidenceByOption: aggregatedResult.confidenceByOption,
+    votes: aggregatedResult.votes.map(v => ({
+      voter: v.voter,
+      nickname: v.nickname,
+      choice: v.choice,
+      confidence: v.confidence,
+      reasoning: v.reasoning,
+    })),
+    totalVoters: aggregatedResult.totalVoters,
+    validVotes: aggregatedResult.validVotes,
+    consensusLevel: aggregatedResult.consensusLevel,
+  };
+
   return {
     content: [
       {
         type: 'text',
         text: formattedOutput,
       },
+      {
+        type: 'text',
+        text: JSON.stringify(structuredData),
+      },
     ],
   };
 }

package/src/tools/get-usage-stats.ts

@@ -75,12 +75,26 @@ export function getUsageStatsTool(
 
   logger.info(`Retrieved usage stats for period: ${period}`);
 
+  // Build structured data for UI consumption
+  const structuredData = {
+    period: stats.period,
+    startDate: stats.startDate,
+    endDate: stats.endDate,
+    totals: stats.totals,
+    usage: stats.usage,
+    costByProvider: stats.costByProvider,
+  };
+
   return {
     content: [
       {
         type: 'text',
         text: output,
       },
+      {
+        type: 'text',
+        text: JSON.stringify(structuredData),
+      },
     ],
   };
 }

package/src/ui/compare-ducks/app.ts

@@ -0,0 +1,88 @@
+import { App } from '@modelcontextprotocol/ext-apps';
+
+interface CompareResponse {
+  provider: string;
+  nickname: string;
+  model: string;
+  content: string;
+  latency: number;
+  tokens: { prompt: number; completion: number; total: number } | null;
+  cached: boolean;
+  error?: string;
+}
+
+const app = new App({ name: 'CompareDucks', version: '1.0.0' }, {});
+
+app.ontoolresult = (params) => {
+  const container = document.getElementById('app')!;
+  if (params.isError) {
+    container.innerHTML = `<div class="error-banner">Tool execution failed</div>`;
+    return;
+  }
+
+  // Parse JSON from second content item
+  const content = params.content;
+  if (!content || !Array.isArray(content) || content.length < 2) {
+    container.innerHTML = `<div class="error-banner">No structured data received</div>`;
+    return;
+  }
+
+  try {
+    const data: CompareResponse[] = JSON.parse(
+      (content[1] as { type: string; text: string }).text
+    );
+    render(data);
+  } catch {
+    container.innerHTML = `<div class="error-banner">Failed to parse response data</div>`;
+  }
+};
+
+function render(responses: CompareResponse[]) {
+  const container = document.getElementById('app')!;
+  const successCount = responses.filter((r) => !r.error).length;
+
+  let html = `<div class="summary-bar">${successCount}/${responses.length} ducks responded successfully</div>`;
+  html += `<div class="grid">`;
+
+  for (const r of responses) {
+    const isError = !!r.error;
+    const latencyClass =
+      r.latency < 2000 ? 'fast' : r.latency < 5000 ? 'medium' : 'slow';
+
+    html += `<div class="card${isError ? ' card-error' : ''}">`;
+    html += `<div class="card-header">`;
+    html += `<span class="nickname">${esc(r.nickname)}</span>`;
+    html += `<span class="provider">${esc(r.provider)}</span>`;
+    html += `</div>`;
+
+    if (!isError) {
+      html += `<div class="badges">`;
+      html += `<span class="badge model">${esc(r.model)}</span>`;
+      if (r.tokens) {
+        html += `<span class="badge tokens">${r.tokens.total} tokens</span>`;
+      }
+      if (r.cached) {
+        html += `<span class="badge cached">Cached</span>`;
+      }
+      html += `</div>`;
+      html += `<div class="latency-bar ${latencyClass}" style="width:${Math.min(100, (r.latency / 10000) * 100)}%"></div>`;
+      html += `<div class="latency-label">${r.latency}ms</div>`;
+      html += `<div class="content"><pre>${esc(r.content)}</pre></div>`;
+    } else {
+      html += `<div class="content error-text"><pre>${esc(r.content)}</pre></div>`;
+    }
+
+    html += `</div>`;
+  }
+
+  html += `</div>`;
+  container.innerHTML = html;
+}
+
+function esc(s: string): string {
+  const d = document.createElement('div');
+  d.textContent = s;
+  return d.innerHTML;
+}
+
+app.connect().catch(console.error);

package/src/ui/compare-ducks/mcp-app.html

@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Compare Ducks</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      line-height: 1.5;
+      color: #1a1a2e;
+      background: #f8f9fa;
+      padding: 16px;
+    }
+    .summary-bar {
+      background: #e3f2fd;
+      color: #1565c0;
+      padding: 8px 16px;
+      border-radius: 8px;
+      font-weight: 600;
+      margin-bottom: 16px;
+      text-align: center;
+    }
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+      gap: 16px;
+    }
+    .card {
+      background: #fff;
+      border: 1px solid #e0e0e0;
+      border-radius: 12px;
+      padding: 16px;
+      overflow: hidden;
+    }
+    .card-error { border-color: #ef5350; }
+    .card-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 8px;
+    }
+    .nickname { font-weight: 700; font-size: 1.1em; }
+    .provider { font-size: 0.85em; opacity: 0.7; }
+    .badges { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 8px; }
+    .badge {
+      font-size: 0.75em;
+      padding: 2px 8px;
+      border-radius: 12px;
+      background: #e8eaf6;
+      color: #3949ab;
+      font-weight: 500;
+    }
+    .badge.cached { background: #e8f5e9; color: #2e7d32; }
+    .latency-bar {
+      height: 4px;
+      border-radius: 2px;
+      margin-bottom: 4px;
+      min-width: 4px;
+    }
+    .latency-bar.fast { background: #4caf50; }
+    .latency-bar.medium { background: #ff9800; }
+    .latency-bar.slow { background: #f44336; }
+    .latency-label { font-size: 0.75em; opacity: 0.6; margin-bottom: 8px; }
+    .content pre {
+      white-space: pre-wrap;
+      word-break: break-word;
+      font-size: 0.9em;
+      background: #f5f5f5;
+      padding: 12px;
+      border-radius: 8px;
+      max-height: 300px;
+      overflow-y: auto;
+    }
+    .error-text pre { color: #ef5350; }
+    .error-banner {
+      background: #ffebee;
+      color: #c62828;
+      padding: 12px;
+      border-radius: 8px;
+      text-align: center;
+      font-weight: 600;
+    }
+    @media (prefers-color-scheme: dark) {
+      body { background: #1a1a2e; color: #e0e0e0; }
+      .card { background: #16213e; border-color: #0f3460; color: #e0e0e0; }
+      .badge { background: #0f3460; color: #a0c4ff; }
+      .summary-bar { background: #0f3460; color: #a0c4ff; }
+      .content pre { background: #0d1b2a; color: #d0d0d0; }
+      .error-banner { background: #5c1a1a; color: #ff8a80; }
+      .card-error { border-color: #8b3a3a; }
+      .latency-label { color: #a0a0a0; }
+      .provider { color: #9e9e9e; }
+    }
+  </style>
+</head>
+<body>
+  <div id="app"><p style="text-align:center;opacity:0.5">Waiting for results...</p></div>
+  <script type="module" src="./app.ts"></script>
+</body>
+</html>

package/src/ui/duck-debate/app.ts

@@ -0,0 +1,111 @@
+import { App } from '@modelcontextprotocol/ext-apps';
+
+interface DebateData {
+  topic: string;
+  format: 'oxford' | 'socratic' | 'adversarial';
+  totalRounds: number;
+  participants: { provider: string; nickname: string; position: string }[];
+  rounds: { round: number; provider: string; nickname: string; position: string; content: string }[][];
+  synthesis: string;
+  synthesizer: string;
+}
+
+const formatMeta: Record<string, { emoji: string; label: string; style: string }> = {
+  oxford: { emoji: '\uD83C\uDF93', label: 'Oxford', style: 'oxford' },
+  socratic: { emoji: '\uD83C\uDFDB\uFE0F', label: 'Socratic', style: 'socratic' },
+  adversarial: { emoji: '\u2694\uFE0F', label: 'Adversarial', style: 'adversarial' },
+};
+
+const positionColors: Record<string, string> = {
+  pro: '#4caf50',
+  con: '#f44336',
+  neutral: '#9e9e9e',
+};
+
+const app = new App({ name: 'DuckDebate', version: '1.0.0' }, {});
+
+app.ontoolresult = (params) => {
+  const container = document.getElementById('app')!;
+  if (params.isError) {
+    container.innerHTML = `<div class="error-banner">Tool execution failed</div>`;
+    return;
+  }
+
+  const content = params.content;
+  if (!content || !Array.isArray(content) || content.length < 2) {
+    container.innerHTML = `<div class="error-banner">No structured data received</div>`;
+    return;
+  }
+
+  try {
+    const data: DebateData = JSON.parse(
+      (content[1] as { type: string; text: string }).text
+    );
+    render(data);
+  } catch {
+    container.innerHTML = `<div class="error-banner">Failed to parse debate data</div>`;
+  }
+};
+
+function render(data: DebateData) {
+  const container = document.getElementById('app')!;
+  const fmt = formatMeta[data.format] || formatMeta.oxford;
+
+  let html = `<div class="debate ${fmt.style}">`;
+
+  // Header
+  html += `<div class="header">`;
+  html += `<div class="format-badge">${fmt.emoji} ${fmt.label} Debate</div>`;
+  html += `<h2 class="topic">${esc(data.topic)}</h2>`;
+  html += `<div class="meta">${data.totalRounds} rounds &middot; ${data.participants.length} participants</div>`;
+  html += `</div>`;
+
+  // Participants
+  html += `<div class="participants">`;
+  for (const p of data.participants) {
+    const color = positionColors[p.position] || '#9e9e9e';
+    html += `<span class="participant" style="border-color:${color}">`;
+    html += `<span class="pos-dot" style="background:${color}"></span>`;
+    html += `${esc(p.nickname)} <small>(${p.position})</small>`;
+    html += `</span>`;
+  }
+  html += `</div>`;
+
+  // Rounds
+  html += `<div class="rounds">`;
+  for (let i = 0; i < data.rounds.length; i++) {
+    const round = data.rounds[i];
+    html += `<details class="round">`;
+    html += `<summary class="round-header">Round ${i + 1}</summary>`;
+    html += `<div class="round-body">`;
+    for (const arg of round) {
+      const color = positionColors[arg.position] || '#9e9e9e';
+      html += `<div class="argument" style="border-left-color:${color}">`;
+      html += `<div class="arg-header">`;
+      html += `<span class="arg-name">${esc(arg.nickname)}</span>`;
+      html += `<span class="arg-pos" style="color:${color}">${arg.position.toUpperCase()}</span>`;
+      html += `</div>`;
+      html += `<div class="arg-content">${esc(arg.content)}</div>`;
+      html += `</div>`;
+    }
+    html += `</div></details>`;
+  }
+  html += `</div>`;
+
+  // Synthesis
+  html += `<div class="synthesis">`;
+  html += `<h3>Synthesis <small>by ${esc(data.synthesizer)}</small></h3>`;
+  html += `<div class="synthesis-content">${esc(data.synthesis)}</div>`;
+  html += `</div>`;
+
+  html += `</div>`;
+  container.innerHTML = html;
+}
+
+function esc(s: string): string {
+  const d = document.createElement('div');
+  d.textContent = s;
+  return d.innerHTML;
+}
+
+app.connect().catch(console.error);