Mcp Rubber Duck

MCP Rubber Duck

一个 MCP（Model Context Protocol）服务，可作为桥梁查询多个大模型，包括兼容 OpenAI 的 HTTP API 和 CLI 编码 Agent。就像橡皮鸭调试法一样，向不同的 AI「鸭子」解释问题，获取不同的观点！

为什么要直接集成提供商？ MCP 的 sampling 原语——由服务借用主机的大模型——已在 2026-07-28 规范候选版本中弃用，转而支持服务直接集成大模型提供商 API。Rubber Duck 一直采用这种方式（自带鸭子），因此符合协议的发展方向，无需迁移。

功能

• 通用 OpenAI 兼容性 —— 适用于任何兼容 OpenAI 的 API 端点
• CLI Agent 支持 —— 使用 CLI 编码 Agent（Claude Code、Codex、Gemini CLI、Grok、Aider）作为鸭子
• 多只鸭子 —— 同时配置和查询多个大模型提供商
• 对话管理 —— 在多条消息间保留上下文
• 鸭子议会 —— 一次获取所有已配置大模型的回复
• 共识投票 —— 多鸭投票，并提供推理过程和置信度分数
• LLM 评审 —— 让鸭子评估并排列彼此的回复
• 迭代优化 —— 两只鸭子协作改进回复
• 结构化辩论 —— 牛津式、苏格拉底式和对抗式辩论格式
• MCP 提示词 —— 用于多大模型工作流的 8 个可复用提示词模板
• 视觉输入 —— 发送图片及提示词给支持视觉的模型（文档）
• 自动故障转移 —— 首选提供商失败时自动切换到其他提供商
• 健康监控 —— 实时检查所有提供商的运行状况
• 用量跟踪 —— 按提供商跟踪请求、令牌和预估费用
• MCP 桥接 —— 将鸭子连接到其他 MCP 服务以扩展功能（文档）
• 防护机制 —— 可插拔安全层，支持速率限制、令牌限制、模式拦截和 PII 脱敏（文档）
• 细粒度安全控制 —— 按服务设置审批控制，并支持基于会话的审批
• 交互式界面 —— 为比较、投票、辩论和用量工具提供丰富的 HTML 面板（通过 MCP Apps）
• 工具注解 —— 符合 MCP 规范的工具行为提示（只读、破坏性等）
• 结构化输出 —— 为返回结构化 JSON 的工具设置 outputSchema，以便客户端验证（Cursor、VS Code/Copilot）
• 设计上符合规范 —— 直接连接提供商 API；由于服务端 sampling 已弃用，这也是 MCP 2026-07-28 规范目前推荐的方式（SEP-2577）

支持的提供商

HTTP 提供商（兼容 OpenAI 的 API）

任何提供兼容 OpenAI 的 API 端点的提供商，包括：

• OpenAI
• Google Gemini
• Anthropic（通过兼容 OpenAI 的端点）
• Groq（为开放权重模型提供快速推理）
• Together AI（提供丰富的开放权重模型目录）
• Perplexity（支持联网搜索的在线模型）
• Anyscale、Azure OpenAI、Ollama、LM Studio、自定义

CLI 提供方（编码 Agent）

作为本地进程运行的命令行编码 Agent：

• Claude Code（claude）-- Codex（codex）-- Gemini CLI（gemini）-- Grok CLI（grok）-- Aider（aider）-- 自定义

完整的设置和配置说明，请参阅 CLI 提供方。

快速开始

# Install globally
npm install -g mcp-rubber-duck

# Or use npx directly in Claude Desktop config
npx mcp-rubber-duck

使用 Claude Desktop？ 请跳转至 Claude Desktop 配置。 使用 Cursor、VS Code、Windsurf 或其他工具？ 请参阅设置指南。

安装

前提条件

• Node.js 20 或更高版本
• npm 或 yarn
• 至少一个 HTTP 提供方的 API 密钥，或在本地安装的命令行编码 Agent

从 NPM 安装

npm install -g mcp-rubber-duck

从源代码安装

git clone https://github.com/nesquikm/mcp-rubber-duck.git
cd mcp-rubber-duck
npm install
npm run build
npm start

配置

创建 .env 文件或 config/config.json。关键环境变量：

变量	说明
OPENAI_API_KEY	OpenAI API 密钥
GEMINI_API_KEY	Google Gemini API 密钥
GROQ_API_KEY	Groq API 密钥
DEFAULT_PROVIDER	默认提供方（例如，openai）
DEFAULT_TEMPERATURE	默认温度（例如，0.7）
LOG_LEVEL	debug、info、warn、error
MCP_SERVER	设置为 true 以启用 MCP 服务模式
MCP_BRIDGE_ENABLED	启用 MCP Bridge（让 duck 访问外部 MCP 服务）
CUSTOM_{NAME}_*	自定义 HTTP 提供方
CLI_{AGENT}_ENABLED	启用 CLI Agent（CLAUDE、CODEX、GEMINI、GROK、AIDER）

完整参考：配置文档

交互式 UI（MCP Apps）

四个工具——compare_ducks、duck_vote、duck_debate 和 get_usage_stats——可通过 MCP Apps 在受支持的 MCP 客户端中呈现丰富的交互式 HTML 面板。在支持 MCP Apps 的客户端中配置好此 MCP 服务后，UI 将自动显示，无需额外设置。不支持 MCP Apps 的客户端仍会收到相同的纯文本输出（不会损失任何功能）。受支持客户端的最新列表请参阅 MCP Apps 仓库。

比较鸭子

并排比较多个模型的响应，并显示延迟指示器、Token 数量、模型徽章和错误状态。

鸭子投票

让多个鸭子对选项进行投票，并以可视化投票统计的形式展示，包括条形图、共识徽章、获胜者卡片、置信度条和可折叠的推理过程。

鸭子辩论

鸭子之间进行结构化的多轮辩论，并以逐轮视图展示，包括格式徽章、参与者列表、可折叠的轮次和综合总结部分。

使用统计

使用情况分析，包括摘要卡片、可展开行的提供方细分、Token 分布条和预估费用。

## 可用工具

工具	描述
ask_duck	向指定的大模型提供商提问一次
chat_with_duck	在多条消息间保留上下文的对话
clear_conversations	清除所有对话历史记录
list_ducks	列出已配置的提供商及其健康状态
list_models	列出各提供商可用的模型
compare_ducks	同时向多个提供商提问同一个问题
duck_council	获取所有已配置的 duck 的回复
get_usage_stats	使用统计和预估费用
duck_vote	多个 duck 进行投票，并提供推理过程和置信度
duck_judge	让一个 duck 评估并排列其他 duck 的回复
duck_iterate	在两个 duck 之间迭代优化回复
duck_debate	由多个 duck 进行结构化、多轮辩论
mcp_status	MCP Bridge 状态及已连接的服务
get_pending_approvals	待处理的 MCP 工具审批请求
approve_mcp_request	批准或拒绝 duck 的 MCP 工具请求

包含输入架构的完整参考文档：工具文档

可用提示词

提示词	用途	必需参数
perspectives	通过分配不同视角进行多角度分析	problem、perspectives
assumptions	揭示计划中的隐含假设	plan
blindspots	寻找被忽略的风险和缺漏	proposal
tradeoffs	结构化比较选项	options、criteria
red_team	从多个角度进行安全／风险分析	target
reframe	从不同层面重新审视问题	problem
architecture	从多个方面进行设计评审	design、workloads、priorities
diverge_converge	先发散探索，再收敛得出结论	challenge

包含示例的完整参考文档：提示词文档

开发

npm run dev        # Development with watch mode
npm test           # Run all tests
npm run lint       # ESLint
npm run typecheck  # Type check without emit

文档

主题	链接
设置指南（所有工具）	docs/setup.md
完整配置参考	docs/configuration.md
Claude Desktop 设置	docs/claude-desktop.md
所有工具及其架构	docs/tools.md
提示词模板	docs/prompts.md
CLI 编码 Agent	docs/cli-providers.md
MCP Bridge	docs/mcp-bridge.md
防护措施	docs/guardrails.md
Docker 部署	docs/docker.md
提供商专属设置	docs/provider-setup.md
使用示例	docs/usage-examples.md
架构	docs/architecture.md
路线图	docs/roadmap.md

故障排除

提供商无法正常工作

1. 检查 API 密钥是否设置正确
2. 确认端点 URL 是否正确
3. 运行健康检查：list_ducks({ check_health: true })
4. 查看日志中的详细错误消息

连接问题

• 对于本地提供商（Ollama、LM Studio），请确保其正在运行
• 检查本地端点的防火墙设置
• 确认与云提供商的网络连接正常

速率限制

• 配置故障转移至其他提供商
• 调整 max_retries 和 timeout 设置
• 请参阅防护措施，了解速率限制配置

贡献

     __
   <(o )___
    ( ._> /
     `---'  Quack! Ready to debug!

我们欢迎大家贡献！无论你是在修复错误、添加功能，还是教我们的鸭子新把戏，都欢迎加入我们的鸭群。

请查看贡献指南，开始参与。

贡献者快速入门：

1. Fork 此仓库
2. 创建一个功能分支
3. 遵循我们的约定式提交指南
4. 为新功能添加测试
5. 提交 Pull Request

许可证

MIT License - 详情请参阅 LICENSE 文件

致谢

• 灵感来自橡皮鸭调试法
• 基于 Model Context Protocol（MCP）构建
• 使用 OpenAI SDK 以兼容 HTTP 提供方
• 支持 CLI 编码 Agent（Claude Code、Codex、Gemini CLI、Grok、Aider）

更新日志

详细的更改和发布历史请参阅 CHANGELOG.md。

注册表与目录

• NPM Package：npmjs.com/package/mcp-rubber-duck
• Docker Images：ghcr.io/nesquikm/mcp-rubber-duck
• MCP Registry：官方 MCP 服务 io.github.nesquikm/rubber-duck
• Glama Directory：glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck
• Awesome MCP Servers：收录于社区目录

支持

• 报告问题：https://github.com/nesquikm/mcp-rubber-duck/issues
• 文档：https://github.com/nesquikm/mcp-rubber-duck/wiki
• 讨论：https://github.com/nesquikm/mcp-rubber-duck/discussions

---

祝你和 AI 鸭子面板调试愉快！