mcp-rubber-duck 1.1.0

package/.github/workflows/semantic-release.yml

@@ -0,0 +1,89 @@
+name: 📦 Semantic Release
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: 🧪 Test Before Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v4
+
+      - name: 📦 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: 📥 Install dependencies
+        run: npm ci
+
+      - name: 🔍 Lint
+        run: npm run lint
+
+      - name: 🏗️ Build
+        run: npm run build
+
+      - name: 🔬 Type check
+        run: npm run typecheck
+
+      # Enable when tests are working
+      # - name: 🧪 Test
+      #   run: npm test
+
+  release:
+    name: 📦 Release
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      packages: write
+
+    steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: 📦 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: 📥 Install dependencies
+        run: npm ci
+
+      - name: 🏗️ Build
+        run: npm run build
+
+      - name: 📦 Run semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release
+
+      - name: 📊 Release Summary
+        if: success()
+        run: |
+          echo "🎉 **Semantic Release Completed Successfully!**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "📋 **What happened:**" >> $GITHUB_STEP_SUMMARY
+          echo "- 🔍 Analyzed commits since last release" >> $GITHUB_STEP_SUMMARY
+          echo "- 📝 Generated changelog entries" >> $GITHUB_STEP_SUMMARY
+          echo "- 🏷️ Created git tag (if new version)" >> $GITHUB_STEP_SUMMARY
+          echo "- 📦 Updated package.json version" >> $GITHUB_STEP_SUMMARY
+          echo "- 🐳 Tagged version will trigger Docker build via release.yml" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "🔄 **Next Steps:**" >> $GITHUB_STEP_SUMMARY
+          echo "- If a new version was released, the release.yml workflow will build Docker images" >> $GITHUB_STEP_SUMMARY
+          echo "- Check the releases page for the new version" >> $GITHUB_STEP_SUMMARY

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/.releaserc.json

@@ -0,0 +1,66 @@
+{
+  "branches": [
+    "master",
+    "main"
+  ],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    "@semantic-release/npm",
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "package.json",
+          "CHANGELOG.md"
+        ],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ],
+  "releaseRules": [
+    {
+      "type": "feat",
+      "release": "minor"
+    },
+    {
+      "type": "fix",
+      "release": "patch"
+    },
+    {
+      "type": "docs",
+      "release": false
+    },
+    {
+      "type": "style",
+      "release": false
+    },
+    {
+      "type": "refactor",
+      "release": "patch"
+    },
+    {
+      "type": "perf",
+      "release": "patch"
+    },
+    {
+      "type": "test",
+      "release": false
+    },
+    {
+      "type": "chore",
+      "release": false
+    },
+    {
+      "scope": "no-release",
+      "release": false
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# [1.1.0](https://github.com/nesquikm/mcp-rubber-duck/compare/v1.0.0...v1.1.0) (2025-09-17)
+
+
+### Features
+
+* add NPM publishing for MCP Registry ([96a7a5b](https://github.com/nesquikm/mcp-rubber-duck/commit/96a7a5b6e2e25f7113c0ec87880e39d4a2fae02f))
+
+# 1.0.0 (2025-09-11)
+
+
+### Bug Fixes
+
+* Always silence console logs in MCP mode to prevent JSON-RPC parsing errors ([0761756](https://github.com/nesquikm/mcp-rubber-duck/commit/076175671f67c7bf10118e578a81078b7e798fc0))
+* Clean up MCP server output to prevent JSON parsing errors ([e391c46](https://github.com/nesquikm/mcp-rubber-duck/commit/e391c46b1cbd151abc99304055f9a2217ee0e2e6))
+* Configure Jest for ESM modules compatibility ([221492d](https://github.com/nesquikm/mcp-rubber-duck/commit/221492dd5aaf049aba637467767626bad6e0bebe))
+* Correct Gemini API endpoint URL and add comprehensive tests ([36f4c3d](https://github.com/nesquikm/mcp-rubber-duck/commit/36f4c3d0f3385d3d374fdff6078b8c3204a8fc77))
+* Display requested model name instead of resolved API model name ([9acfe25](https://github.com/nesquikm/mcp-rubber-duck/commit/9acfe25e56ac67bb52957e594eb0022187129a33))
+* Health checks for reasoning models (GPT-5, Gemini-2.5) ([2af7816](https://github.com/nesquikm/mcp-rubber-duck/commit/2af7816698fac18cf64026404f8cca5061ddb9ce))
+* Implement smart parameter detection for OpenAI API compatibility ([fed002f](https://github.com/nesquikm/mcp-rubber-duck/commit/fed002f6db8d61d0fee520d13b454d15533db9ea))
+* Prevent Ollama auto-detection when not configured ([9409441](https://github.com/nesquikm/mcp-rubber-duck/commit/940944121500cc54740339c2167040fdb327761f))
+* Remove conventionalcommits preset from semantic-release config ([f34934f](https://github.com/nesquikm/mcp-rubber-duck/commit/f34934f4e06b0b9106132415e98b42016c2fcd5d))
+* Remove npm publishing from semantic-release configuration ([e3f0f4b](https://github.com/nesquikm/mcp-rubber-duck/commit/e3f0f4b374ff5579565f1bcfcee445bc084c7ae1))
+* Remove token limits completely to resolve empty responses from reasoning models ([ac41f73](https://github.com/nesquikm/mcp-rubber-duck/commit/ac41f738ac3b166c8845b271e77ba8315ac9d0b9))
+* Temporarily disable lint in CI to fix deployment ([30d8b3b](https://github.com/nesquikm/mcp-rubber-duck/commit/30d8b3bb2412a53086190752bfc95e970382efa2))
+* Temporarily disable tests in CI to fix deployment ([d023a32](https://github.com/nesquikm/mcp-rubber-duck/commit/d023a32847115dae6144fe5fe1e3c04b21c85a7e))
+
+
+### Features
+
+* 🦆 Ducks can now use MCP tools! Per-server trust & smart approvals ([2fa5a0f](https://github.com/nesquikm/mcp-rubber-duck/commit/2fa5a0f1ab3cb81736494ddda7f29919c5c93a51))
+* Add automated versioning with semantic-release ([b3c7470](https://github.com/nesquikm/mcp-rubber-duck/commit/b3c7470ba27e2d043b9080b0fe0fcdb54ef56ab3))
+* Add conversation reset functionality ([92dc489](https://github.com/nesquikm/mcp-rubber-duck/commit/92dc4895951200afadf7b82e634e12ddd072afa2))
+* Add dynamic model listing and selection ([ce84823](https://github.com/nesquikm/mcp-rubber-duck/commit/ce84823eb94c09f767671d8d24875c125ddd21b6))
+* Add environment variable support for provider default models ([4ac2272](https://github.com/nesquikm/mcp-rubber-duck/commit/4ac2272cb57bba21195504dea191aaa5bafd5dfe))
+* Add GitHub Actions for automated Docker builds and releases ([2ff30d6](https://github.com/nesquikm/mcp-rubber-duck/commit/2ff30d635116f5db2f860412642d794ee5ad2531))
+* Add Google Gemini support ([359db64](https://github.com/nesquikm/mcp-rubber-duck/commit/359db641a22d447df25297bee2889352f97614b3))
+* Add optional custom duck nicknames via environment variables ([c3b3e6a](https://github.com/nesquikm/mcp-rubber-duck/commit/c3b3e6a9c6ce863e4a0ec03fb8a14099b795d8cd))
+* Add systemd service files for production deployment ([63333fb](https://github.com/nesquikm/mcp-rubber-duck/commit/63333fb851b8546fc0e803b7a43d921385b471cc))
+* Add universal multi-platform Docker deployment support ([37ea1cb](https://github.com/nesquikm/mcp-rubber-duck/commit/37ea1cb0c2b13cb5b2a82addf23888f3c1898550))
+* Display model name in all duck responses ([ab87434](https://github.com/nesquikm/mcp-rubber-duck/commit/ab874347a611406fb47c1002f87696580ed416fe))
+* Enhance MCP rubber duck functionality with improved provider support and error handling ([2356389](https://github.com/nesquikm/mcp-rubber-duck/commit/23563898a90c101d794648c411f4d8e29fbaf687))
+* Support multiple custom providers via CUSTOM_{NAME}_* environment variables ([5bfeb82](https://github.com/nesquikm/mcp-rubber-duck/commit/5bfeb8224d2d1057d66422253d912424d254b943))
+
+
+### BREAKING CHANGES
+
+* Removes old CUSTOM_API_KEY/CUSTOM_BASE_URL pattern.
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-09-11
+
+### Added
+- 🦆 **Multiple AI Provider Support:** Query OpenAI, Gemini, Groq, Ollama, and custom providers
+- 💬 **Conversation Management:** Maintain context across messages with conversation IDs
+- 🏛️ **Duck Council:** Get responses from all configured LLMs simultaneously
+- 🔗 **MCP Bridge:** Connect to external MCP servers with approval system
+- 🛡️ **Security Features:** Per-server trust settings and smart tool approval workflow
+- 🐳 **Universal Deployment:** Multi-platform Docker support (AMD64, ARM64)
+- 📦 **Multiple Configuration Options:** Desktop, Raspberry Pi, and remote deployment configs
+- 🔧 **Flexible Provider Configuration:** Support for custom providers via environment variables
+- 🧪 **Comprehensive Testing:** Jest-based test suite with ESM module support
+- 🚀 **CI/CD Pipeline:** Automated Docker builds and releases via GitHub Actions
+- 📝 **Rich Logging:** Winston-based logging with safe credential handling
+- 🔄 **Conversation Reset:** Clear conversation history functionality
+- 🏷️ **Custom Duck Nicknames:** Optional custom names for AI providers
+
+### Features
+- Support for multiple OpenAI-compatible LLM providers
+- Conversation context management with unique IDs
+- MCP server integration with security approval system
+- Docker-based deployment with multi-architecture support
+- Comprehensive configuration via environment variables
+- Automated versioning and release system (semantic-release)
+- GitHub Actions workflows for CI/CD
+- Systemd service files for production deployment
+
+### Technical Improvements
+- TypeScript support with strict type checking
+- ESLint and Prettier for code quality
+- Jest testing framework configured for ESM modules
+- Winston logging with credential sanitization
+- Zod schema validation for configuration
+- Docker multi-stage builds for optimized images
+- GitHub Container Registry integration
+
+[Unreleased]: https://github.com/nesquikm/mcp-rubber-duck/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/nesquikm/mcp-rubber-duck/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,242 @@
+# 🦆 Contributing to MCP Rubber Duck
+
+Welcome to the duck pond! 🏞️ We're thrilled that you want to help make our rubber duck debugging experience even better.
+
+```
+     __
+   <(o )___
+    ( ._> /   "Quack! Let's build something amazing together!"
+     `---'
+```
+
+## 🏊 Getting Your Feet Wet
+
+Before you can swim with the ducks, let's make sure you have everything set up properly.
+
+### Prerequisites
+
+- **Node.js 20+** (because even ducks need modern JavaScript)
+- **npm or yarn** (for managing our duck food... er, dependencies)
+- **Git** (for version control that doesn't ruffle any feathers)
+- **A sense of humor** (optional but highly recommended)
+
+### 🥚 Hatching Your Development Environment
+
+1. **Fork and clone the repository**
+   ```bash
+   git clone https://github.com/nesquikm/mcp-rubber-duck.git
+   cd mcp-rubber-duck
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Build the project**
+   ```bash
+   npm run build
+   ```
+
+4. **Run tests** (make sure everything floats properly)
+   ```bash
+   npm test
+   ```
+
+5. **Start developing!**
+   ```bash
+   npm run dev
+   ```
+
+## 🎯 Ways to Contribute
+
+### 🐛 Found a Bug? Help Us Debug the Duck!
+
+If something's not working right, don't just let it be a sitting duck! Here's how to report it:
+
+1. **Check existing issues** first (maybe another duck already spotted it)
+2. **Create a new issue** with:
+   - Clear description of what went wrong
+   - Steps to reproduce the quacking... er, cracking behavior
+   - Your environment details (OS, Node version, etc.)
+   - Any error messages (screenshots welcome!)
+
+### 💡 Duck Tales: Suggesting New Features
+
+Got an idea that would make our ducks even more awesome? We're all ears! (Do ducks have ears? 🤔)
+
+1. **Open a feature request issue**
+2. **Describe the problem** you're trying to solve
+3. **Explain your proposed solution**
+4. **Consider alternatives** (there's more than one way to float a duck)
+
+### 🔌 Teaching Ducks New Tricks (Adding Providers)
+
+Want to add support for a new LLM provider? Fantastic! Here's the duck-tested process:
+
+1. **Create a new provider configuration** in `src/providers/`
+2. **Add provider tests** (because untested ducks don't swim)
+3. **Update documentation** (help other ducks find their way)
+4. **Add environment variables** following the `PROVIDER_NAME_*` pattern
+
+## 📏 Duck Standards (Code Guidelines)
+
+We like to keep our code as clean as a duck's... code. Here are our standards:
+
+### TypeScript
+
+- **Use TypeScript** for all new code (even ducks need types)
+- **Prefer interfaces over types** when possible
+- **Add proper JSDoc comments** for public APIs
+- **Use strict null checks** (no undefined ducks allowed)
+
+### Code Style
+
+- **Run the linter**: `npm run lint`
+- **Use Prettier**: `npm run format`
+- **Follow existing patterns** (when in duck pond, do as the ducks do)
+- **Keep functions focused** (one quack per function)
+
+### File Organization
+
+```
+src/
+├── providers/     # Duck provider implementations
+├── tools/         # MCP tool implementations  
+├── services/      # Core services (cache, conversations, etc.)
+├── config/        # Configuration management
+└── utils/         # Utility functions (logging, validation, etc.)
+```
+
+## 🧪 Testing (Making Sure Ducks Float)
+
+> "If it walks like a duck and quacks like a duck, it better pass tests like a duck!"
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode (for active development)
+npm run test:watch
+
+# Run with coverage (see which ducks are covered)
+npm test -- --coverage
+```
+
+### Writing Tests
+
+- **Write tests for new features** (no test, no merge - that's the duck law)
+- **Use descriptive test names** (`should quack when duck is happy`)
+- **Test error conditions** (what happens when ducks get grumpy?)
+- **Mock external dependencies** (don't let real APIs mess with our test ducks)
+
+## 💬 Commit Messages (Duck Communication Protocol)
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) because our automated release system speaks duck:
+
+### Format
+```
+type(scope): description
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types That Make Our Ducks Happy
+- `feat:` - New feature (🦆 gets a new trick)
+- `fix:` - Bug fix (🔧 duck repairs)
+- `docs:` - Documentation changes (📚 duck education)
+- `style:` - Code style changes (💄 duck grooming)
+- `refactor:` - Code refactoring (🏗️ duck house renovation)
+- `test:` - Adding tests (🧪 duck quality assurance)
+- `chore:` - Maintenance tasks (🧹 duck pond cleaning)
+
+### Good Examples
+```bash
+feat: add support for Anthropic Claude API
+fix: prevent duck overflow in conversation cache
+docs: update setup instructions for macOS ducks
+test: add integration tests for duck council feature
+```
+
+### Version Impact
+- `fix:` → Patch release (1.0.0 → 1.0.1)
+- `feat:` → Minor release (1.0.0 → 1.1.0)  
+- `BREAKING CHANGE:` → Major release (1.0.0 → 2.0.0)
+
+## 🚀 Pull Request Process (Paddling Upstream)
+
+Ready to submit your contribution? Here's how to navigate the waters:
+
+### Before You Submit
+
+1. **Update documentation** if needed
+2. **Add tests** for your changes
+3. **Run the full test suite**: `npm test`
+4. **Lint your code**: `npm run lint`
+5. **Build successfully**: `npm run build`
+6. **Update CHANGELOG.md** if it's a notable change
+
+### PR Guidelines
+
+1. **Create a descriptive PR title** (following conventional commit format)
+2. **Fill out the PR template** (helps us understand your duck logic)
+3. **Link any related issues** (`Fixes #123`)
+4. **Keep PRs focused** (one feature per duck, please)
+5. **Be patient** - our duck reviewers are thorough but fair
+
+### The Review Process
+
+Our council of senior ducks will review your PR. They might:
+- **Request changes** (suggestions to make your duck even better)
+- **Ask questions** (rubber duck debugging in action!)
+- **Approve and merge** (welcome to the pond! 🎉)
+
+## 🤝 Duck Pond Etiquette
+
+We're building a welcoming community where all ducks can thrive:
+
+### The Golden Rules
+
+1. **Be respectful** - No aggressive quacking
+2. **Be constructive** - Help make things better
+3. **Be patient** - We're all learning to swim
+4. **Be inclusive** - Every duck has value
+5. **Have fun** - We're building cool stuff with AI ducks!
+
+### Getting Help
+
+- **💬 Discussions**: Use GitHub Discussions for questions
+- **🐛 Issues**: Bug reports and feature requests
+- **📖 Wiki**: Additional documentation and guides
+
+## 🏆 Recognition
+
+Contributors who help improve our duck pond will be:
+- **Listed in our README** (hall of fame!)
+- **Mentioned in release notes** (when appropriate)
+- **Given our eternal gratitude** (priceless!)
+
+## 📜 Legal Stuff (The Fine Print)
+
+By contributing, you agree that:
+- Your contributions will be licensed under the same MIT license
+- You have the right to contribute the code
+- No ducks were harmed in the making of your contribution
+
+---
+
+## 🦆 Ready to Dive In?
+
+Thanks for reading our contributing guide! Whether you're fixing bugs, adding features, or just improving documentation, every contribution makes our duck pond a better place.
+
+Remember: **Good code is like a good rubber duck - it helps you think clearly and solves problems!**
+
+Happy quacking! 🦆✨
+
+---
+
+*"The best way to debug code is to explain it to a rubber duck. The best way to improve open source is to contribute to it!"*

package/Dockerfile

@@ -0,0 +1,62 @@
+# Multi-stage build for optimal size
+FROM node:20-alpine AS builder
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Build the application
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+
+# Install dumb-init for proper signal handling
+RUN apk add --no-cache dumb-init
+
+# Create app user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install production dependencies only
+RUN npm ci --only=production && \
+    npm cache clean --force
+
+# Copy built application from builder
+COPY --from=builder /app/dist ./dist
+
+# Copy configuration examples
+COPY config/config.example.json ./config/
+
+# Change ownership
+RUN chown -R nodejs:nodejs /app
+
+# Switch to non-root user
+USER nodejs
+
+# Expose stdio
+EXPOSE 3000
+
+# Add healthcheck for monitoring
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=30s \
+  CMD node -e "process.exit(0)" || exit 1
+
+# Use dumb-init to handle signals properly
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start the application
+CMD ["node", "dist/index.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MCP Rubber Duck Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.