mcp-rubber-duck 1.7.0 → 1.9.0

package/src/prompts/index.ts

@@ -0,0 +1,63 @@
+import { Prompt, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+import { PromptDefinition } from './types.js';
+
+// Import all prompt definitions
+import { perspectivesPrompt } from './perspectives.js';
+import { assumptionsPrompt } from './assumptions.js';
+import { blindspotsPrompt } from './blindspots.js';
+import { tradeoffsPrompt } from './tradeoffs.js';
+import { redTeamPrompt } from './red-team.js';
+import { reframePrompt } from './reframe.js';
+import { architecturePrompt } from './architecture.js';
+import { divergeConvergePrompt } from './diverge-converge.js';
+
+/**
+ * Registry of all available prompts.
+ */
+export const PROMPTS: Record<string, PromptDefinition> = {
+  perspectives: perspectivesPrompt,
+  assumptions: assumptionsPrompt,
+  blindspots: blindspotsPrompt,
+  tradeoffs: tradeoffsPrompt,
+  red_team: redTeamPrompt,
+  reframe: reframePrompt,
+  architecture: architecturePrompt,
+  diverge_converge: divergeConvergePrompt,
+};
+
+/**
+ * Get all available prompts (without buildMessages function).
+ * Used for prompts/list handler.
+ */
+export function getPrompts(): Prompt[] {
+  return Object.values(PROMPTS).map(({ buildMessages: _, ...prompt }) => prompt);
+}
+
+/**
+ * Get a specific prompt with generated messages.
+ * Used for prompts/get handler.
+ *
+ * @param name - The prompt name
+ * @param args - Arguments to pass to the prompt
+ * @returns GetPromptResult with description and messages
+ * @throws Error if prompt not found or required arguments missing
+ */
+export function getPrompt(name: string, args: Record<string, string>): GetPromptResult {
+  const prompt = PROMPTS[name];
+
+  if (!prompt) {
+    throw new Error(`Unknown prompt: ${name}`);
+  }
+
+  try {
+    const messages = prompt.buildMessages(args);
+    return {
+      description: prompt.description,
+      messages,
+    };
+  } catch (error) {
+    // Re-throw with more context
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to build prompt "${name}": ${errorMessage}`);
+  }
+}

package/src/prompts/perspectives.ts

@@ -0,0 +1,73 @@
+import { PromptDefinition } from './types.js';
+
+/**
+ * Multi-angle analysis prompt that assigns different analytical lenses
+ * to each LLM for comprehensive analysis.
+ */
+export const perspectivesPrompt: PromptDefinition = {
+  name: 'perspectives',
+  description:
+    'Analyze a problem from multiple perspectives. Each LLM adopts a different analytical lens (e.g., security, performance, UX) for comprehensive multi-angle analysis.',
+  arguments: [
+    {
+      name: 'problem',
+      description: 'The problem, design, or code to analyze',
+      required: true,
+    },
+    {
+      name: 'perspectives',
+      description:
+        'Comma-separated analytical lenses (e.g., "security, performance, UX, maintainability")',
+      required: true,
+    },
+    {
+      name: 'context',
+      description: 'Additional background or constraints',
+      required: false,
+    },
+  ],
+  buildMessages: (args: Record<string, string>) => {
+    const { problem, perspectives, context } = args;
+
+    if (!problem) {
+      throw new Error('problem argument is required');
+    }
+    if (!perspectives) {
+      throw new Error('perspectives argument is required');
+    }
+
+    let messageText = `I need multi-perspective analysis of this problem:
+
+**PROBLEM:**
+${problem}
+`;
+
+    if (context) {
+      messageText += `
+**CONTEXT:**
+${context}
+`;
+    }
+
+    messageText += `
+**PERSPECTIVES TO ANALYZE:**
+${perspectives}
+
+Please analyze from these perspectives, with each LLM adopting ONE lens. Each perspective should provide:
+1. Specific observations from that viewpoint
+2. Potential concerns or issues
+3. Recommendations aligned with that perspective
+
+Aim for productive disagreement - different lenses may have conflicting priorities, and that's valuable.`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: messageText,
+        },
+      },
+    ];
+  },
+};

package/src/prompts/red-team.ts

@@ -0,0 +1,91 @@
+import { PromptDefinition } from './types.js';
+
+/**
+ * Prompt for security and risk analysis from multiple attack angles.
+ */
+export const redTeamPrompt: PromptDefinition = {
+  name: 'red_team',
+  description:
+    'Conduct attack surface analysis from multiple angles. Each reviewer focuses on different risk dimensions (security, privacy, abuse, compliance).',
+  arguments: [
+    {
+      name: 'target',
+      description: 'The system, feature, code, or plan to red-team',
+      required: true,
+    },
+    {
+      name: 'threat_model',
+      description: 'Known threat actors, attack scenarios, or security context',
+      required: false,
+    },
+    {
+      name: 'dimensions',
+      description:
+        'Risk dimensions to focus on (e.g., "security, privacy, abuse, compliance, reputation")',
+      required: false,
+    },
+  ],
+  buildMessages: (args: Record<string, string>) => {
+    const { target, threat_model, dimensions } = args;
+
+    if (!target) {
+      throw new Error('target argument is required');
+    }
+
+    let messageText = `Conduct a red-team analysis of this target:
+
+**TARGET:**
+${target}
+`;
+
+    if (threat_model) {
+      messageText += `
+**THREAT MODEL/CONTEXT:**
+${threat_model}
+`;
+    }
+
+    if (dimensions) {
+      messageText += `
+**RISK DIMENSIONS TO FOCUS ON:**
+${dimensions}
+`;
+    } else {
+      messageText += `
+**RISK DIMENSIONS:**
+Consider security, privacy, abuse potential, compliance, and reputation risks.
+`;
+    }
+
+    messageText += `
+**YOUR TASK:**
+Each reviewer should focus on a different attack vector or risk dimension:
+
+1. **Identify vulnerabilities or abuse scenarios**
+   - How could this be exploited or misused?
+   - What could go wrong?
+
+2. **Rate each finding**
+   - Severity: How bad if it happens?
+   - Likelihood: How likely is exploitation?
+
+3. **Suggest mitigations**
+   - How can each risk be reduced or eliminated?
+   - What's the cost/benefit of the mitigation?
+
+**PRIORITIZE:**
+Identify the top 3 risks that need immediate attention. Explain why these are most critical.
+
+Think adversarially - what would a malicious actor, careless user, or edge case do?`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: messageText,
+        },
+      },
+    ];
+  },
+};

package/src/prompts/reframe.ts

@@ -0,0 +1,78 @@
+import { PromptDefinition } from './types.js';
+
+/**
+ * Prompt for problem reframing at different abstraction levels and angles.
+ */
+export const reframePrompt: PromptDefinition = {
+  name: 'reframe',
+  description:
+    'Reframe a problem from multiple angles and abstraction levels. Helps break out of mental ruts by viewing the problem differently.',
+  arguments: [
+    {
+      name: 'problem',
+      description: 'The current problem statement or challenge',
+      required: true,
+    },
+    {
+      name: 'stuck_on',
+      description: 'What specifically you are stuck on or frustrated by',
+      required: false,
+    },
+  ],
+  buildMessages: (args: Record<string, string>) => {
+    const { problem, stuck_on } = args;
+
+    if (!problem) {
+      throw new Error('problem argument is required');
+    }
+
+    let messageText = `Help me reframe this problem from multiple angles:
+
+**CURRENT PROBLEM:**
+${problem}
+`;
+
+    if (stuck_on) {
+      messageText += `
+**WHAT I'M STUCK ON:**
+${stuck_on}
+`;
+    }
+
+    messageText += `
+**YOUR TASK:**
+Provide three distinct reframings of this problem:
+
+1. **HIGHER ABSTRACTION**
+   - What's the core human need or job-to-be-done here?
+   - What problem behind the problem are we really solving?
+   - How might we phrase this as a "How might we...?" question?
+
+2. **INVERSION**
+   - What if we wanted this problem to occur? How would we cause it?
+   - What's the opposite of what we're trying to achieve?
+   - What would make this problem impossible to solve?
+
+3. **SIMPLIFICATION**
+   - How would you explain this to a non-expert?
+   - What's the simplest version of this problem?
+   - What would a child ask about this?
+
+For each reframing:
+- State the new problem formulation clearly
+- Explain what new solution directions this opens up
+- Note what aspects of the original problem this highlights or de-emphasizes
+
+The goal is to break out of the current mental frame and see new possibilities.`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: messageText,
+        },
+      },
+    ];
+  },
+};

package/src/prompts/tradeoffs.ts

@@ -0,0 +1,95 @@
+import { PromptDefinition } from './types.js';
+
+/**
+ * Prompt for structured comparison of options with explicit criteria.
+ */
+export const tradeoffsPrompt: PromptDefinition = {
+  name: 'tradeoffs',
+  description:
+    'Compare options with explicit criteria and trade-off analysis. Provides structured evaluation to help make informed decisions.',
+  arguments: [
+    {
+      name: 'options',
+      description: 'The options to compare (comma-separated list or detailed descriptions)',
+      required: true,
+    },
+    {
+      name: 'criteria',
+      description: 'Evaluation criteria (comma-separated, e.g., "cost, complexity, performance")',
+      required: true,
+    },
+    {
+      name: 'context',
+      description: 'Decision context, constraints, or background',
+      required: false,
+    },
+    {
+      name: 'weights',
+      description: 'Which criteria matter most (priority order or weights)',
+      required: false,
+    },
+  ],
+  buildMessages: (args: Record<string, string>) => {
+    const { options, criteria, context, weights } = args;
+
+    if (!options) {
+      throw new Error('options argument is required');
+    }
+    if (!criteria) {
+      throw new Error('criteria argument is required');
+    }
+
+    let messageText = `Provide a structured trade-off analysis:
+
+**OPTIONS TO COMPARE:**
+${options}
+
+**EVALUATION CRITERIA:**
+${criteria}
+`;
+
+    if (context) {
+      messageText += `
+**CONTEXT/CONSTRAINTS:**
+${context}
+`;
+    }
+
+    if (weights) {
+      messageText += `
+**PRIORITY CRITERIA:**
+${weights}
+`;
+    }
+
+    messageText += `
+**YOUR TASK:**
+1. **Assess each option** against each criterion
+   - Use concrete ratings or descriptions, not vague terms
+   - Note specific strengths and weaknesses
+
+2. **Identify trade-offs**
+   - Where do options excel vs struggle?
+   - What do you gain/lose with each choice?
+
+3. **Highlight disagreements**
+   - Where might reasonable people disagree?
+   - What depends on assumptions or preferences?
+
+4. **Recommendation**
+   - Given the stated priorities, which option fits best?
+   - Under what conditions might a different option be better?
+
+Present this as a structured analysis that helps decision-making, not just a list of pros/cons.`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: messageText,
+        },
+      },
+    ];
+  },
+};

package/src/prompts/types.ts

@@ -0,0 +1,14 @@
+import { Prompt, PromptMessage } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Extended Prompt definition that includes a buildMessages function
+ * to generate structured messages from user-provided arguments.
+ */
+export interface PromptDefinition extends Prompt {
+  /**
+   * Build the prompt messages from the provided arguments.
+   * @param args - Record of argument name to value
+   * @returns Array of PromptMessage objects
+   */
+  buildMessages: (args: Record<string, string>) => PromptMessage[];
+}

package/src/providers/duck-provider-enhanced.ts

@@ -4,6 +4,8 @@ import { FunctionBridge } from '../services/function-bridge.js';
 import { ConversationMessage } from '../config/types.js';
 import { logger } from '../utils/logger.js';
 import { SafeLogger } from '../utils/safe-logger.js';
+import { GuardrailsService } from '../guardrails/service.js';
+import { GuardrailBlockError } from '../guardrails/errors.js';
 
 export interface EnhancedChatResponse extends ChatResponse {
   pendingApprovals?: {
@@ -22,15 +24,43 @@ export class EnhancedDuckProvider extends DuckProvider {
     nickname: string,
     options: ProviderOptions,
     functionBridge: FunctionBridge,
-    mcpEnabled: boolean = true
+    mcpEnabled: boolean = true,
+    guardrailsService?: GuardrailsService
   ) {
-    super(name, nickname, options);
+    super(name, nickname, options, guardrailsService);
     this.functionBridge = functionBridge;
     this.mcpEnabled = mcpEnabled;
   }
 
   async chat(options: ChatOptions): Promise<EnhancedChatResponse> {
     try {
+      const modelToUse = options.model || this.options.model;
+
+      // Create guardrail context if service is enabled
+      const guardrailContext = this.guardrailsService?.isEnabled()
+        ? this.guardrailsService.createContext({
+            provider: this.name,
+            model: modelToUse,
+            messages: options.messages,
+            prompt: options.messages[options.messages.length - 1]?.content,
+          })
+        : undefined;
+
+      // Execute pre_request guardrails
+      if (guardrailContext && this.guardrailsService?.isEnabled()) {
+        const preResult = await this.guardrailsService.execute('pre_request', guardrailContext);
+        if (preResult.action === 'block') {
+          throw new GuardrailBlockError(
+            preResult.blockedBy || 'unknown',
+            preResult.blockReason || 'Request blocked by guardrails'
+          );
+        }
+        // Update messages if modified by guardrails (e.g., PII redaction)
+        if (preResult.action === 'modify' && guardrailContext.messages.length > 0) {
+          options = { ...options, messages: guardrailContext.messages };
+        }
+      }
+
       // If MCP is enabled, add function definitions
       if (this.mcpEnabled) {
         const functions = await this.functionBridge.getFunctionDefinitions();
@@ -43,7 +73,6 @@ export class EnhancedDuckProvider extends DuckProvider {
 
       // Prepare messages for function calling
       const messages = this.prepareMessages(options.messages, options.systemPrompt);
-      const modelToUse = options.model || this.options.model;
 
       const baseParams: Partial<OpenAIChatParams> = {
         model: modelToUse,
@@ -75,17 +104,52 @@ export class EnhancedDuckProvider extends DuckProvider {
 
       // Check if the model wants to call functions
       if (choice.message?.tool_calls && choice.message.tool_calls.length > 0) {
-        return await this.handleToolCalls(
+        const toolResult = await this.handleToolCalls(
           choice.message.tool_calls,
           messages as OpenAIMessage[],
           baseParams,
-          modelToUse
+          modelToUse,
+          guardrailContext
         );
+
+        // Execute post_response guardrails on final result
+        if (guardrailContext && this.guardrailsService?.isEnabled()) {
+          guardrailContext.response = toolResult.content;
+          const postResult = await this.guardrailsService.execute('post_response', guardrailContext);
+          if (postResult.action === 'block') {
+            throw new GuardrailBlockError(
+              postResult.blockedBy || 'unknown',
+              postResult.blockReason || 'Response blocked by guardrails'
+            );
+          }
+          if (postResult.action === 'modify' && guardrailContext.response) {
+            toolResult.content = guardrailContext.response;
+          }
+        }
+
+        return toolResult;
+      }
+
+      let content = choice.message?.content || '';
+
+      // Execute post_response guardrails
+      if (guardrailContext && this.guardrailsService?.isEnabled()) {
+        guardrailContext.response = content;
+        const postResult = await this.guardrailsService.execute('post_response', guardrailContext);
+        if (postResult.action === 'block') {
+          throw new GuardrailBlockError(
+            postResult.blockedBy || 'unknown',
+            postResult.blockReason || 'Response blocked by guardrails'
+          );
+        }
+        if (postResult.action === 'modify' && guardrailContext.response) {
+          content = guardrailContext.response;
+        }
       }
 
       // No tool calls, return regular response
       return {
-        content: choice.message?.content || '',
+        content,
         usage: response.usage ? {
           promptTokens: response.usage.prompt_tokens,
           completionTokens: response.usage.completion_tokens,
@@ -96,6 +160,10 @@ export class EnhancedDuckProvider extends DuckProvider {
       };
 
     } catch (error: unknown) {
+      // Re-throw GuardrailBlockError as-is
+      if (error instanceof GuardrailBlockError) {
+        throw error;
+      }
       logger.error(`Enhanced provider ${this.name} chat error:`, error);
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new Error(`Duck ${this.nickname} couldn't respond: ${errorMessage}`);
@@ -106,7 +174,8 @@ export class EnhancedDuckProvider extends DuckProvider {
     toolCalls: OpenAIToolCall[],
     messages: OpenAIMessage[],
     baseParams: Partial<OpenAIChatParams>,
-    modelToUse: string
+    modelToUse: string,
+    _guardrailContext?: import('../guardrails/types.js').GuardrailContext
   ): Promise<EnhancedChatResponse> {
     const pendingApprovals: { id: string; message: string }[] = [];
     const toolMessages: OpenAIMessage[] = [];

package/src/providers/enhanced-manager.ts

@@ -3,6 +3,7 @@ import { ProviderManager } from './manager.js';
 import { ConfigManager } from '../config/config.js';
 import { FunctionBridge } from '../services/function-bridge.js';
 import { UsageService } from '../services/usage.js';
+import { GuardrailsService } from '../guardrails/service.js';
 import { DuckResponse } from '../config/types.js';
 import { ChatOptions, MCPResult } from './types.js';
 import { logger } from '../utils/logger.js';
@@ -12,8 +13,8 @@ export class EnhancedProviderManager extends ProviderManager {
   private functionBridge?: FunctionBridge;
   private mcpEnabled: boolean = false;
 
-  constructor(configManager: ConfigManager, functionBridge?: FunctionBridge, usageService?: UsageService) {
-    super(configManager, usageService);
+  constructor(configManager: ConfigManager, functionBridge?: FunctionBridge, usageService?: UsageService, guardrailsService?: GuardrailsService) {
+    super(configManager, usageService, guardrailsService);
     this.functionBridge = functionBridge;
     this.mcpEnabled = !!functionBridge &&
       (configManager.getConfig().mcp_bridge?.enabled || false);
@@ -49,7 +50,8 @@ export class EnhancedProviderManager extends ProviderManager {
             systemPrompt: providerConfig.system_prompt,
           },
           this.functionBridge,
-          this.mcpEnabled
+          this.mcpEnabled,
+          this.guardrailsService
         );
 
         this.enhancedProviders.set(name, enhancedProvider);

package/src/providers/manager.ts

@@ -3,6 +3,7 @@ import { ConfigManager } from '../config/config.js';
 import { ProviderHealth, DuckResponse } from '../config/types.js';
 import { ChatOptions, ModelInfo } from './types.js';
 import { UsageService } from '../services/usage.js';
+import { GuardrailsService } from '../guardrails/service.js';
 import { logger } from '../utils/logger.js';
 import { getRandomDuckMessage } from '../utils/ascii-art.js';
 
@@ -11,11 +12,13 @@ export class ProviderManager {
   private healthStatus: Map<string, ProviderHealth> = new Map();
   protected configManager: ConfigManager;
   protected usageService?: UsageService;
+  protected guardrailsService?: GuardrailsService;
   private defaultProvider?: string;
 
-  constructor(configManager: ConfigManager, usageService?: UsageService) {
+  constructor(configManager: ConfigManager, usageService?: UsageService, guardrailsService?: GuardrailsService) {
     this.configManager = configManager;
     this.usageService = usageService;
+    this.guardrailsService = guardrailsService;
     this.initializeProviders();
   }
 
@@ -34,7 +37,7 @@ export class ProviderManager {
           timeout: providerConfig.timeout,
           maxRetries: providerConfig.max_retries,
           systemPrompt: providerConfig.system_prompt,
-        });
+        }, this.guardrailsService);
 
         this.providers.set(name, provider);
         logger.info(`Initialized provider: ${name} (${providerConfig.nickname})`);
@@ -44,7 +47,7 @@ export class ProviderManager {
     }
 
     this.defaultProvider = config.default_provider;
-    
+
     if (this.providers.size === 0) {
       throw new Error('No providers could be initialized');
     }