mcp-rubber-duck 1.1.0

package/.dockerignore

@@ -0,0 +1,19 @@
+node_modules
+dist
+coverage
+.git
+.gitignore
+.env
+.env.*
+*.log
+.DS_Store
+tests
+*.test.ts
+jest.config.js
+.vscode
+.idea
+README.md
+LICENSE
+docker-compose.yml
+Dockerfile
+.dockerignore

package/.env.desktop.example

@@ -0,0 +1,145 @@
+# MCP Rubber Duck - Desktop/Server Configuration Example
+# Optimized for high-performance systems (macOS, Linux, Windows)
+# Copy this file to .env and add your API keys
+
+# =============================================================================
+# BASIC CONFIGURATION
+# =============================================================================
+
+# Docker image (multi-platform)
+DOCKER_IMAGE=ghcr.io/nesquikm/mcp-rubber-duck:latest
+
+# Default provider and settings
+DEFAULT_PROVIDER=openai
+DEFAULT_TEMPERATURE=0.7
+LOG_LEVEL=info
+
+# =============================================================================
+# DESKTOP/SERVER OPTIMIZATIONS
+# =============================================================================
+
+# Resource limits for powerful systems
+DOCKER_CPU_LIMIT=4.0
+DOCKER_MEMORY_LIMIT=2G
+DOCKER_MEMORY_RESERVATION=1G
+
+# Node.js memory optimization for desktop
+NODE_OPTIONS=--max-old-space-size=1024
+NODE_ENV=production
+
+# =============================================================================
+# MCP SERVER CONFIGURATION
+# =============================================================================
+
+# Enable MCP server mode
+MCP_SERVER=true
+
+# =============================================================================
+# AI PROVIDER API KEYS
+# =============================================================================
+
+# OpenAI (required - get from https://platform.openai.com/api-keys)
+OPENAI_API_KEY=sk-your-openai-key-here
+OPENAI_DEFAULT_MODEL=gpt-4o
+
+# Google Gemini (optional - get from https://aistudio.google.com/apikey)
+GEMINI_API_KEY=your-gemini-key-here
+GEMINI_DEFAULT_MODEL=gemini-2.5-pro
+
+# Groq (optional - fast inference - get from https://console.groq.com/keys)
+GROQ_API_KEY=gsk_your-groq-key-here
+GROQ_DEFAULT_MODEL=llama-3.3-70b-versatile
+
+# Together AI (optional - get from https://api.together.xyz/)
+TOGETHER_API_KEY=your-together-key-here
+
+# Perplexity AI (optional - get from https://perplexity.ai/)
+PERPLEXITY_API_KEY=your-perplexity-key-here
+
+# Anyscale (optional - get from https://app.endpoints.anyscale.com/)
+# ANYSCALE_API_KEY=your-anyscale-key-here
+
+# Azure OpenAI (optional)
+# AZURE_OPENAI_API_KEY=your-azure-key-here
+# AZURE_OPENAI_ENDPOINT=your-resource-name.openai.azure.com
+
+# =============================================================================
+# LOCAL AI (RECOMMENDED FOR DESKTOP)
+# =============================================================================
+
+# Ollama (local AI - enable with --profile with-ollama)
+# Desktop systems can handle larger models
+OLLAMA_BASE_URL=http://ollama:11434/v1
+OLLAMA_DEFAULT_MODEL=llama3.1:8b
+
+# Ollama resource limits for desktop
+OLLAMA_CPU_LIMIT=4.0
+OLLAMA_MEMORY_LIMIT=4G
+OLLAMA_MEMORY_RESERVATION=2G
+
+# LM Studio (alternative local AI)
+# LMSTUDIO_BASE_URL=http://localhost:1234/v1
+# LMSTUDIO_DEFAULT_MODEL=local-model
+
+# =============================================================================
+# CUSTOM PROVIDERS
+# =============================================================================
+
+# Example: Custom OpenAI-compatible API
+# CUSTOM_API_KEY=your-custom-key
+# CUSTOM_BASE_URL=https://api.example.com/v1
+# CUSTOM_DEFAULT_MODEL=custom-model
+# CUSTOM_NICKNAME=My Custom Duck
+
+# Example: Additional custom provider
+# CUSTOM_MYAPI_API_KEY=your-custom-key
+# CUSTOM_MYAPI_BASE_URL=https://api.example.com/v1
+# CUSTOM_MYAPI_DEFAULT_MODEL=custom-model
+# CUSTOM_MYAPI_NICKNAME=My API Duck
+
+# =============================================================================
+# MCP BRIDGE CONFIGURATION (ADVANCED)
+# =============================================================================
+
+# Enable MCP Bridge (allows ducks to use external MCP tools)
+MCP_BRIDGE_ENABLED=true
+
+# Approval mode: always, trusted, or never
+MCP_APPROVAL_MODE=trusted
+MCP_APPROVAL_TIMEOUT=300
+
+# Example: Context7 Documentation Server
+MCP_SERVER_CONTEXT7_TYPE=http
+MCP_SERVER_CONTEXT7_URL=https://mcp.context7.com/mcp
+MCP_SERVER_CONTEXT7_ENABLED=true
+MCP_TRUSTED_TOOLS_CONTEXT7=*
+
+# =============================================================================
+# PERFORMANCE TUNING FOR DESKTOP
+# =============================================================================
+
+# Cache settings (higher for desktop)
+CACHE_TTL=600
+
+# Network settings
+ENABLE_FAILOVER=true
+MAX_RETRIES=3
+REQUEST_TIMEOUT=60000
+
+# Monitoring (enable for development/debugging)
+ENABLE_PERFORMANCE_MONITORING=true
+ENABLE_REQUEST_LOGGING=false
+ENABLE_MEMORY_REPORTING=true
+
+# =============================================================================
+# DEVELOPMENT SETTINGS
+# =============================================================================
+
+# Enable debug mode for development
+# LOG_LEVEL=debug
+
+# Duck nicknames (optional fun customization)
+# OPENAI_NICKNAME=DUCK-4
+# GEMINI_NICKNAME=Duckmini  
+# GROQ_NICKNAME=Quackers
+# OLLAMA_NICKNAME=Local Quacker

package/.env.example

@@ -0,0 +1,45 @@
+# OpenAI Provider
+OPENAI_API_KEY=sk-...
+
+# Google Gemini Provider
+GEMINI_API_KEY=...
+
+# Groq Provider
+GROQ_API_KEY=gsk_...
+
+# Together AI Provider
+TOGETHER_API_KEY=...
+
+# Perplexity Provider
+PERPLEXITY_API_KEY=pplx-...
+
+# Custom Providers (you can add multiple)
+# Format: CUSTOM_{NAME}_* where NAME becomes the provider key (lowercase)
+# Required: API_KEY and BASE_URL. Optional: MODELS, DEFAULT_MODEL, NICKNAME
+
+# Example 1: Custom provider "MYAPI" (becomes provider key "myapi")
+# CUSTOM_MYAPI_API_KEY=sk-...
+# CUSTOM_MYAPI_BASE_URL=https://my-api.com/v1
+# CUSTOM_MYAPI_MODELS=model1,model2,model3
+# CUSTOM_MYAPI_DEFAULT_MODEL=model1
+# CUSTOM_MYAPI_NICKNAME=My API Duck
+
+# Example 2: Custom provider "AZURE" (becomes provider key "azure")
+# CUSTOM_AZURE_API_KEY=...
+# CUSTOM_AZURE_BASE_URL=https://myazure.openai.azure.com/v1
+# CUSTOM_AZURE_NICKNAME=Azure Duck
+
+# Optional: Default settings
+DEFAULT_PROVIDER=openai
+DEFAULT_TEMPERATURE=0.7
+
+# Optional: Logging
+LOG_LEVEL=info
+
+# Optional: Custom Duck Nicknames (Have fun with these!)
+# OPENAI_NICKNAME="DUCK-4"
+# GEMINI_NICKNAME="Duckmini"
+# GROQ_NICKNAME="Quackers"
+# TOGETHER_NICKNAME="Speedy Duck"
+# PERPLEXITY_NICKNAME="Search Duck"
+# OLLAMA_NICKNAME="Local Duck"

package/.env.pi.example

@@ -0,0 +1,106 @@
+# MCP Rubber Duck - Raspberry Pi Configuration Example
+# Optimized for low-memory devices (Pi 3+)
+# Copy this file to .env and add your API keys
+
+# =============================================================================
+# BASIC CONFIGURATION
+# =============================================================================
+
+# Docker image (multi-platform)
+DOCKER_IMAGE=ghcr.io/nesquikm/mcp-rubber-duck:latest
+
+# Default provider and settings
+DEFAULT_PROVIDER=openai
+DEFAULT_TEMPERATURE=0.7
+LOG_LEVEL=info
+
+# =============================================================================
+# RASPBERRY PI OPTIMIZATIONS
+# =============================================================================
+
+# Resource limits optimized for Pi
+DOCKER_CPU_LIMIT=1.5
+DOCKER_MEMORY_LIMIT=512M
+DOCKER_MEMORY_RESERVATION=256M
+
+# Node.js memory optimization for Pi
+NODE_OPTIONS=--max-old-space-size=256
+NODE_ENV=production
+
+# =============================================================================
+# MCP SERVER CONFIGURATION
+# =============================================================================
+
+# Enable MCP server mode
+MCP_SERVER=true
+
+# =============================================================================
+# AI PROVIDER API KEYS
+# =============================================================================
+
+# OpenAI (required - get from https://platform.openai.com/api-keys)
+OPENAI_API_KEY=sk-your-openai-key-here
+OPENAI_DEFAULT_MODEL=gpt-4o-mini
+
+# Google Gemini (optional - get from https://aistudio.google.com/apikey)
+GEMINI_API_KEY=your-gemini-key-here
+GEMINI_DEFAULT_MODEL=gemini-2.5-flash
+
+# Groq (optional - fast inference - get from https://console.groq.com/keys)
+GROQ_API_KEY=gsk_your-groq-key-here
+GROQ_DEFAULT_MODEL=llama-3.3-70b-versatile
+
+# Other providers (optional)
+# TOGETHER_API_KEY=your-together-key-here
+# PERPLEXITY_API_KEY=your-perplexity-key-here
+
+# =============================================================================
+# LOCAL AI (OPTIONAL)
+# =============================================================================
+
+# Ollama (local AI - enable with --profile with-ollama)
+# Warning: Ollama requires significant RAM on Pi
+# OLLAMA_BASE_URL=http://ollama:11434/v1
+# OLLAMA_DEFAULT_MODEL=llama3.2
+
+# Ollama resource limits for Pi (if enabled)
+OLLAMA_CPU_LIMIT=2.0
+OLLAMA_MEMORY_LIMIT=1G
+OLLAMA_MEMORY_RESERVATION=512M
+
+# =============================================================================
+# CUSTOM PROVIDERS
+# =============================================================================
+
+# Example: Custom OpenAI-compatible API
+# CUSTOM_API_KEY=your-custom-key
+# CUSTOM_BASE_URL=https://api.example.com/v1
+# CUSTOM_DEFAULT_MODEL=custom-model
+
+# =============================================================================
+# MCP BRIDGE CONFIGURATION (OPTIONAL)
+# =============================================================================
+
+# Enable MCP Bridge (allows ducks to use external MCP tools)
+MCP_BRIDGE_ENABLED=false
+
+# Approval mode: always, trusted, or never
+MCP_APPROVAL_MODE=trusted
+MCP_APPROVAL_TIMEOUT=300
+
+# =============================================================================
+# PERFORMANCE TUNING FOR PI
+# =============================================================================
+
+# Cache settings (lower for Pi)
+CACHE_TTL=300
+
+# Network settings
+ENABLE_FAILOVER=true
+MAX_RETRIES=3
+REQUEST_TIMEOUT=30000
+
+# Monitoring (disable to save resources)
+ENABLE_PERFORMANCE_MONITORING=false
+ENABLE_REQUEST_LOGGING=false
+ENABLE_MEMORY_REPORTING=true

package/.env.template

@@ -0,0 +1,165 @@
+# MCP Rubber Duck - Universal Configuration Template
+# Copy this file to .env and fill in your API keys
+# For platform-specific examples, see .env.pi.example or .env.desktop.example
+
+# =============================================================================
+# BASIC CONFIGURATION
+# =============================================================================
+
+# Docker image to use (multi-platform: AMD64, ARM64)
+# Works on: macOS, Linux, Windows, Raspberry Pi 3+
+DOCKER_IMAGE=ghcr.io/nesquikm/mcp-rubber-duck:latest
+
+# Default provider to use when none specified
+DEFAULT_PROVIDER=openai
+
+# Default temperature for LLM responses (0.0 - 2.0)
+DEFAULT_TEMPERATURE=0.7
+
+# Logging level (error, warn, info, debug)
+LOG_LEVEL=info
+
+# =============================================================================
+# NODE.JS & SYSTEM OPTIMIZATION
+# =============================================================================
+
+# Node.js memory optimization for Raspberry Pi (in MB)
+# Adjust based on your Pi model:
+# - Pi 3 (1GB RAM): --max-old-space-size=256
+# - Pi 4 (2GB RAM): --max-old-space-size=512  
+# - Pi 4 (4GB+): --max-old-space-size=1024
+NODE_OPTIONS=--max-old-space-size=256
+
+# Node environment
+NODE_ENV=production
+
+# =============================================================================
+# MCP SERVER CONFIGURATION
+# =============================================================================
+
+# Enable MCP server mode (required for Claude Desktop integration)
+MCP_SERVER=true
+
+# =============================================================================
+# AI PROVIDER API KEYS
+# Replace the placeholder values with your actual API keys
+# =============================================================================
+
+# OpenAI (https://platform.openai.com/api-keys)
+# Get your API key from: https://platform.openai.com/account/api-keys
+OPENAI_API_KEY=sk-your-openai-key-here
+OPENAI_DEFAULT_MODEL=gpt-4o-mini
+
+# Google Gemini (https://aistudio.google.com/apikey)
+# Get your API key from: https://aistudio.google.com/apikey
+GEMINI_API_KEY=your-gemini-key-here
+GEMINI_DEFAULT_MODEL=gemini-2.5-flash
+
+# Groq (https://console.groq.com/keys)
+# Get your API key from: https://console.groq.com/keys
+GROQ_API_KEY=gsk_your-groq-key-here
+GROQ_DEFAULT_MODEL=llama-3.3-70b-versatile
+
+# Together AI (https://api.together.xyz/)
+# Uncomment and fill if you have a Together AI account
+# TOGETHER_API_KEY=your-together-key-here
+
+# Perplexity AI (https://perplexity.ai/)
+# Uncomment and fill if you have a Perplexity account
+# PERPLEXITY_API_KEY=your-perplexity-key-here
+
+# Anyscale (https://app.endpoints.anyscale.com/)
+# Uncomment and fill if you have an Anyscale account
+# ANYSCALE_API_KEY=your-anyscale-key-here
+
+# Azure OpenAI (https://azure.microsoft.com/en-us/products/cognitive-services/openai-service/)
+# Uncomment and fill if you have Azure OpenAI
+# AZURE_OPENAI_API_KEY=your-azure-key-here
+# AZURE_OPENAI_ENDPOINT=your-resource-name.openai.azure.com
+
+# =============================================================================
+# LOCAL AI PROVIDERS (RASPBERRY PI)
+# =============================================================================
+
+# Ollama (Local AI on Raspberry Pi)
+# Only enable if you're running Ollama locally or in Docker
+# OLLAMA_BASE_URL=http://localhost:11434/v1
+# OLLAMA_DEFAULT_MODEL=llama3.2
+
+# LM Studio (Local AI)
+# Only enable if you're running LM Studio locally
+# LMSTUDIO_BASE_URL=http://localhost:1234/v1
+# LMSTUDIO_DEFAULT_MODEL=local-model
+
+# =============================================================================
+# CUSTOM PROVIDERS
+# You can add multiple custom providers using CUSTOM_{NAME}_* format
+# =============================================================================
+
+# Example: Custom OpenAI-compatible API
+# CUSTOM_MYAPI_API_KEY=your-custom-key
+# CUSTOM_MYAPI_BASE_URL=https://api.example.com/v1
+# CUSTOM_MYAPI_DEFAULT_MODEL=custom-model
+# CUSTOM_MYAPI_NICKNAME=My Custom Duck
+
+# =============================================================================
+# MCP BRIDGE CONFIGURATION (Advanced)
+# Allows ducks to access external MCP servers
+# =============================================================================
+
+# Enable MCP Bridge (allows ducks to use external MCP tools)
+MCP_BRIDGE_ENABLED=false
+
+# Approval mode for MCP tool usage: always, trusted, or never
+MCP_APPROVAL_MODE=trusted
+
+# Timeout for approval requests (seconds)
+MCP_APPROVAL_TIMEOUT=300
+
+# Example: Context7 Documentation Server
+# Uncomment to enable Context7 MCP server integration
+# MCP_SERVER_CONTEXT7_TYPE=http
+# MCP_SERVER_CONTEXT7_URL=https://mcp.context7.com/mcp
+# MCP_SERVER_CONTEXT7_ENABLED=true
+# MCP_TRUSTED_TOOLS_CONTEXT7=*
+
+# =============================================================================
+# DUCK NICKNAMES (Optional Fun Customization)
+# =============================================================================
+
+# Customize your duck names (optional)
+# OPENAI_NICKNAME=DUCK-4
+# GEMINI_NICKNAME=Duckmini  
+# GROQ_NICKNAME=Quackers
+# OLLAMA_NICKNAME=Local Quacker
+
+# =============================================================================
+# RASPBERRY PI SPECIFIC SETTINGS
+# =============================================================================
+
+# Cache TTL for responses (seconds)
+# Lower values use less memory but more API calls
+CACHE_TTL=300
+
+# Enable automatic failover to other providers
+ENABLE_FAILOVER=true
+
+# Maximum retries for failed API calls
+MAX_RETRIES=3
+
+# Request timeout (milliseconds)
+# Increase for slower internet connections
+REQUEST_TIMEOUT=30000
+
+# =============================================================================
+# MONITORING & DEBUGGING
+# =============================================================================
+
+# Enable performance monitoring
+ENABLE_PERFORMANCE_MONITORING=false
+
+# Enable detailed request logging (increases log size)
+ENABLE_REQUEST_LOGGING=false
+
+# Enable memory usage reporting
+ENABLE_MEMORY_REPORTING=true

package/.eslintrc.json

@@ -0,0 +1,40 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module",
+    "project": "./tsconfig.json"
+  },
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:@typescript-eslint/recommended-requiring-type-checking"
+  ],
+  "rules": {
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }
+    ],
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "no-console": [
+      "warn",
+      {
+        "allow": ["warn", "error"]
+      }
+    ]
+  },
+  "ignorePatterns": [
+    "dist/",
+    "node_modules/",
+    "coverage/",
+    "*.config.js"
+  ]
+}

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,65 @@
+---
+name: 🐛 Bug Report
+about: Found a bug? Help us debug the duck!
+title: 'bug: '
+labels: ['bug', '🐛 needs triage']
+assignees: ''
+---
+
+## 🦆 Duck Debugging Report
+
+Thanks for helping us squash bugs! Even rubber ducks need debugging sometimes. 🔧
+
+```
+     __
+   <(o )___
+    ( ._> /   "Quack! Something's not right here..."
+     `---'
+```
+
+### 🐛 What's Wrong?
+**Describe the bug clearly:**
+<!-- A clear and concise description of what the bug is -->
+
+### 🔄 How to Reproduce
+**Steps to make the bug happen:**
+1. Go to '...'
+2. Click on '...'
+3. Enter '...'
+4. See error
+
+### 🎯 Expected Behavior
+**What should have happened:**
+<!-- A clear description of what you expected to happen -->
+
+### 📷 Screenshots
+**If applicable, add screenshots to help explain your problem:**
+<!-- Drag and drop images here -->
+
+### 🌍 Your Duck Pond Environment
+**Please complete the following information:**
+- **OS:** [e.g., macOS 14.0, Ubuntu 22.04, Windows 11]
+- **Node.js version:** [e.g., 20.5.0]
+- **MCP Rubber Duck version:** [e.g., 1.2.0]
+- **Installation method:** [e.g., npm, Docker, source]
+- **LLM providers configured:** [e.g., OpenAI, Gemini, Groq]
+
+### 🔍 Error Details
+**Console output or error messages:**
+```
+Paste any error messages or logs here
+```
+
+### 📋 Additional Context
+**Anything else that might help:**
+<!-- Add any other context about the problem here -->
+
+### ✅ Checklist
+- [ ] I searched existing issues to make sure this isn't a duplicate
+- [ ] I included all the information requested above
+- [ ] I can reproduce this bug consistently
+- [ ] I'm using a supported version of Node.js (20+)
+
+---
+
+*"The best way to debug code is to explain it to a rubber duck. Thanks for explaining this bug to us!" 🦆*

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,58 @@
+---
+name: ✨ Feature Request
+about: Suggest an idea to make our ducks even more awesome!
+title: 'feat: '
+labels: ['enhancement', '✨ feature request']
+assignees: ''
+---
+
+## 🦆 Duck Enhancement Proposal
+
+Got an idea that would make our duck pond even better? We're all ears! (Do ducks have ears? 🤔)
+
+```
+     __
+   <(o )___
+    ( ._> /   "Quack! Tell me about your brilliant idea!"
+     `---'
+```
+
+### 💡 The Problem
+**What problem would this feature solve?**
+<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
+
+### 🚀 Proposed Solution
+**What would you like to happen?**
+<!-- A clear and concise description of what you want to happen -->
+
+### 🦆 Duck Use Cases
+**How would this make our ducks better?**
+<!-- Describe specific scenarios where this feature would be useful -->
+- **Example 1:** When using the duck council feature, users could...
+- **Example 2:** When configuring providers, it would help to...
+
+### 🎯 Alternatives Considered
+**What other solutions did you think about?**
+<!-- A clear and concise description of any alternative solutions or features you've considered -->
+
+### 📋 Implementation Ideas
+**Any thoughts on how this could work?** *(optional)*
+<!-- If you have ideas about implementation, share them! No pressure though. -->
+
+### 🌟 Additional Context
+**Anything else that would help?**
+<!-- Add any other context, screenshots, mockups, or examples about the feature request here -->
+
+### 🔗 Related Issues
+**Are there any related issues or discussions?**
+<!-- Link to any related issues or discussions -->
+
+### ✅ Checklist
+- [ ] I searched existing issues to make sure this isn't a duplicate
+- [ ] I described the problem this feature would solve
+- [ ] I explained how this would benefit users
+- [ ] I considered alternative approaches
+
+---
+
+*"Every great feature starts with a great idea. Thanks for sharing yours with our duck pond!" 🦆✨*