{
  "markdown": "# MCP Rubber Duck\n\nAn MCP (Model Context Protocol) server that acts as a bridge to query multiple LLMs -- both OpenAI-compatible HTTP APIs and CLI coding agents. Just like rubber duck debugging, explain your problems to various AI \"ducks\" and get different perspectives!\n\n[![npm version](https://img.shields.io/npm/v/mcp-rubber-duck.svg)](https://www.npmjs.com/package/mcp-rubber-duck)\n[![Docker Image](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/nesquikm/mcp-rubber-duck/pkgs/container/mcp-rubber-duck)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-green)](https://registry.modelcontextprotocol.io)\n\n<p align=\"center\">\n  <img src=\"assets/mcp-rubber-duck.jpg\" alt=\"MCP Rubber Duck - AI ducks helping debug code\" width=\"600\">\n</p>\n\n> **Why direct provider integration?** MCP's `sampling` primitive -- a server borrowing the *host's* model -- was deprecated in the [2026-07-28 spec RC](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) in favor of servers integrating directly with LLM provider APIs. Rubber Duck has always worked this way (it brings its own ducks), so it's aligned with where the protocol is heading -- no migration required.\n\n## Features\n\n- **Universal OpenAI Compatibility** -- Works with any OpenAI-compatible API endpoint\n- **CLI Agent Support** -- Use CLI coding agents (Claude Code, Codex, Gemini CLI, Grok, Aider) as ducks\n- **Multiple Ducks** -- Configure and query multiple LLM providers simultaneously\n- **Conversation Management** -- Maintain context across multiple messages\n- **Duck Council** -- Get responses from all your configured LLMs at once\n- **Consensus Voting** -- Multi-duck voting with reasoning and confidence scores\n- **LLM-as-Judge** -- Have ducks evaluate and rank each other's responses\n- **Iterative Refinement** -- Two ducks collaboratively improve responses\n- **Structured Debates** -- Oxford, Socratic, and adversarial debate formats\n- **MCP Prompts** -- 8 reusable prompt templates for multi-LLM workflows\n- **Vision Input** -- Send images alongside prompts to vision-capable models ([docs](./docs/tools.md#vision-input))\n- **Automatic Failover** -- Falls back to other providers if primary fails\n- **Health Monitoring** -- Real-time health checks for all providers\n- **Usage Tracking** -- Track requests, tokens, and estimated costs per provider\n- **MCP Bridge** -- Connect ducks to other MCP servers for extended functionality ([docs](./docs/mcp-bridge.md))\n- **Guardrails** -- Pluggable safety layer with rate limiting, token limits, pattern blocking, and PII redaction ([docs](./docs/guardrails.md))\n- **Granular Security** -- Per-server approval controls with session-based approvals\n- **Interactive UIs** -- Rich HTML panels for compare, vote, debate, and usage tools (via [MCP Apps](https://github.com/modelcontextprotocol/ext-apps))\n- **Tool Annotations** -- MCP-compliant hints for tool behavior (read-only, destructive, etc.)\n- **Structured Output** -- `outputSchema` on tools returning structured JSON for client-side validation (Cursor, VS Code/Copilot)\n- **Spec-Aligned by Design** -- connects directly to provider APIs, the path the MCP `2026-07-28` spec recommends now that server-side `sampling` is deprecated ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577))\n\n## Supported Providers\n\n### HTTP Providers (OpenAI-compatible API)\n\nAny provider with an OpenAI-compatible API endpoint, including:\n\n- **OpenAI**\n- **Google Gemini**\n- **Anthropic** (via OpenAI-compatible endpoints)\n- **Groq** (fast inference for open-weight models)\n- **Together AI** (broad open-weight model catalog)\n- **Perplexity** (online models with web search)\n- **Anyscale**, **Azure OpenAI**, **Ollama**, **LM Studio**, **Custom**\n\n### CLI Providers (Coding Agents)\n\nCommand-line coding agents that run as local processes:\n\n- **Claude Code** (`claude`) -- **Codex** (`codex`) -- **Gemini CLI** (`gemini`) -- **Grok CLI** (`grok`) -- **Aider** (`aider`) -- **Custom**\n\nSee [CLI Providers](./docs/cli-providers.md) for full setup and configuration.\n\n## Quick Start\n\n```bash\n# Install globally\nnpm install -g mcp-rubber-duck\n\n# Or use npx directly in Claude Desktop config\nnpx mcp-rubber-duck\n```\n\n**Using Claude Desktop?** Jump to [Claude Desktop Configuration](./docs/claude-desktop.md).\n**Using Cursor, VS Code, Windsurf, or another tool?** See the [Setup Guide](./docs/setup.md).\n\n## Installation\n\n### Prerequisites\n\n- Node.js 20 or higher\n- npm or yarn\n- At least one API key for an HTTP provider, **or** a CLI coding agent installed locally\n\n### Install from NPM\n\n```bash\nnpm install -g mcp-rubber-duck\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/nesquikm/mcp-rubber-duck.git\ncd mcp-rubber-duck\nnpm install\nnpm run build\nnpm start\n```\n\n## Configuration\n\nCreate a `.env` file or `config/config.json`. Key environment variables:\n\n| Variable | Description |\n|----------|-------------|\n| `OPENAI_API_KEY` | OpenAI API key |\n| `GEMINI_API_KEY` | Google Gemini API key |\n| `GROQ_API_KEY` | Groq API key |\n| `DEFAULT_PROVIDER` | Default provider (e.g., `openai`) |\n| `DEFAULT_TEMPERATURE` | Default temperature (e.g., `0.7`) |\n| `LOG_LEVEL` | `debug`, `info`, `warn`, `error` |\n| `MCP_SERVER` | Set to `true` for MCP server mode |\n| `MCP_BRIDGE_ENABLED` | Enable MCP Bridge (ducks access external MCP servers) |\n| `CUSTOM_{NAME}_*` | Custom HTTP providers |\n| `CLI_{AGENT}_ENABLED` | Enable CLI agents (`CLAUDE`, `CODEX`, `GEMINI`, `GROK`, `AIDER`) |\n\nFull reference: **[Configuration docs](./docs/configuration.md)**\n\n## Interactive UIs (MCP Apps)\n\nFour tools -- `compare_ducks`, `duck_vote`, `duck_debate`, and `get_usage_stats` -- can render rich interactive HTML panels inside supported MCP clients via [MCP Apps](https://github.com/modelcontextprotocol/ext-apps). Once this MCP server is configured in a supporting client, the UIs appear automatically -- no additional setup is required. Clients without MCP Apps support still receive the same plain text output (no functionality is lost). See the [MCP Apps repo](https://github.com/modelcontextprotocol/ext-apps) for an up-to-date list of supported clients.\n\n### Compare Ducks\n\nCompare multiple model responses side-by-side, with latency indicators, token counts, model badges, and error states.\n\n<p align=\"center\">\n  <img src=\"assets/ext-apps-compare.png\" alt=\"Compare Ducks interactive UI\" width=\"600\">\n</p>\n\n### Duck Vote\n\nHave multiple ducks vote on options, displayed as a visual vote tally with bar charts, consensus badge, winner card, confidence bars, and collapsible reasoning.\n\n<p align=\"center\">\n  <img src=\"assets/ext-apps-vote.png\" alt=\"Duck Vote interactive UI\" width=\"600\">\n</p>\n\n### Duck Debate\n\nStructured multi-round debate between ducks, shown as a round-by-round view with format badge, participant list, collapsible rounds, and synthesis section.\n\n<p align=\"center\">\n  <img src=\"assets/ext-apps-debate.png\" alt=\"Duck Debate interactive UI\" width=\"600\">\n</p>\n\n### Usage Stats\n\nUsage analytics with summary cards, provider breakdown with expandable rows, token distribution bars, and estimated costs.\n\n<p align=\"center\">\n  <img src=\"assets/ext-apps-usage-stats.png\" alt=\"Usage Stats interactive UI\" width=\"600\">\n</p>\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `ask_duck` | Ask a single question to a specific LLM provider |\n| `chat_with_duck` | Conversation with context maintained across messages |\n| `clear_conversations` | Clear all conversation history |\n| `list_ducks` | List configured providers and health status |\n| `list_models` | List available models for providers |\n| `compare_ducks` | Ask the same question to multiple providers simultaneously |\n| `duck_council` | Get responses from all configured ducks |\n| `get_usage_stats` | Usage statistics and estimated costs |\n| `duck_vote` | Multi-duck voting with reasoning and confidence |\n| `duck_judge` | Have one duck evaluate and rank others' responses |\n| `duck_iterate` | Iteratively refine a response between two ducks |\n| `duck_debate` | Structured multi-round debate between ducks |\n| `mcp_status` | MCP Bridge status and connected servers |\n| `get_pending_approvals` | Pending MCP tool approval requests |\n| `approve_mcp_request` | Approve or deny a duck's MCP tool request |\n\nFull reference with input schemas: **[Tools docs](./docs/tools.md)**\n\n## Available Prompts\n\n| Prompt | Purpose | Required Arguments |\n|--------|---------|-------------------|\n| `perspectives` | Multi-angle analysis with assigned lenses | `problem`, `perspectives` |\n| `assumptions` | Surface hidden assumptions in plans | `plan` |\n| `blindspots` | Hunt for overlooked risks and gaps | `proposal` |\n| `tradeoffs` | Structured option comparison | `options`, `criteria` |\n| `red_team` | Security/risk analysis from multiple angles | `target` |\n| `reframe` | Problem reframing at different levels | `problem` |\n| `architecture` | Design review across concerns | `design`, `workloads`, `priorities` |\n| `diverge_converge` | Divergent exploration then convergence | `challenge` |\n\nFull reference with examples: **[Prompts docs](./docs/prompts.md)**\n\n## Development\n\n```bash\nnpm run dev        # Development with watch mode\nnpm test           # Run all tests\nnpm run lint       # ESLint\nnpm run typecheck  # Type check without emit\n```\n\n## [Documentation](./docs/README.md)\n\n| Topic | Link |\n|-------|------|\n| **Setup guide (all tools)** | **[docs/setup.md](./docs/setup.md)** |\n| Full configuration reference | [docs/configuration.md](./docs/configuration.md) |\n| Claude Desktop setup | [docs/claude-desktop.md](./docs/claude-desktop.md) |\n| All tools with schemas | [docs/tools.md](./docs/tools.md) |\n| Prompt templates | [docs/prompts.md](./docs/prompts.md) |\n| CLI coding agents | [docs/cli-providers.md](./docs/cli-providers.md) |\n| MCP Bridge | [docs/mcp-bridge.md](./docs/mcp-bridge.md) |\n| Guardrails | [docs/guardrails.md](./docs/guardrails.md) |\n| Docker deployment | [docs/docker.md](./docs/docker.md) |\n| Provider-specific setup | [docs/provider-setup.md](./docs/provider-setup.md) |\n| Usage examples | [docs/usage-examples.md](./docs/usage-examples.md) |\n| Architecture | [docs/architecture.md](./docs/architecture.md) |\n| Roadmap | [docs/roadmap.md](./docs/roadmap.md) |\n\n## Troubleshooting\n\n### Provider Not Working\n1. Check API key is correctly set\n2. Verify endpoint URL is correct\n3. Run health check: `list_ducks({ check_health: true })`\n4. Check logs for detailed error messages\n\n### Connection Issues\n- For local providers (Ollama, LM Studio), ensure they're running\n- Check firewall settings for local endpoints\n- Verify network connectivity to cloud providers\n\n### Rate Limiting\n- Configure failover to alternate providers\n- Adjust `max_retries` and `timeout` settings\n- See [Guardrails](./docs/guardrails.md) for rate limiting configuration\n\n## Contributing\n\n```\n     __\n   <(o )___\n    ( ._> /\n     `---'  Quack! Ready to debug!\n```\n\nWe love contributions! Whether you're fixing bugs, adding features, or teaching our ducks new tricks, we'd love to have you join the flock.\n\nCheck out our [Contributing Guide](./CONTRIBUTING.md) to get started.\n\n**Quick start for contributors:**\n1. Fork the repository\n2. Create a feature branch\n3. Follow our [conventional commit guidelines](./CONTRIBUTING.md#commit-messages-duck-communication-protocol)\n4. Add tests for new functionality\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Acknowledgments\n\n- Inspired by the rubber duck debugging method\n- Built on the Model Context Protocol (MCP)\n- Uses OpenAI SDK for HTTP provider compatibility\n- Supports CLI coding agents (Claude Code, Codex, Gemini CLI, Grok, Aider)\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for a detailed history of changes and releases.\n\n## Registry & Directory\n\n- **NPM Package**: [npmjs.com/package/mcp-rubber-duck](https://www.npmjs.com/package/mcp-rubber-duck)\n- **Docker Images**: [ghcr.io/nesquikm/mcp-rubber-duck](https://github.com/nesquikm/mcp-rubber-duck/pkgs/container/mcp-rubber-duck)\n- **MCP Registry**: Official MCP server `io.github.nesquikm/rubber-duck`\n- **Glama Directory**: [glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck](https://glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck)\n- **Awesome MCP Servers**: Listed in the [community directory](https://github.com/punkpeye/awesome-mcp-servers)\n\n## Support\n\n- Report issues: https://github.com/nesquikm/mcp-rubber-duck/issues\n- Documentation: https://github.com/nesquikm/mcp-rubber-duck/wiki\n- Discussions: https://github.com/nesquikm/mcp-rubber-duck/discussions\n\n---\n\nHappy Debugging with your AI Duck Panel!\n",
  "bytes": 12644,
  "sha": "bbdf015aaa00bf67c43c24d4db0c52d6c3c30a0cb53ac347d0d0aaeb80e13a3a",
  "repo_slug": "nesquikm/mcp-rubber-duck",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nesquikm_rubber_duck_d3bf8532/readme"
}