MCP Rubber Duck

🚀 MCP Rubber Duck

MCP Rubber Duck 是一个 MCP（模型上下文协议）服务器，可作为查询多个兼容 OpenAI 的大语言模型（LLM）的桥梁。就像使用橡皮鸭调试法一样，向各种 AI “鸭子” 解释你的问题，从而获得不同的观点！

🚀 快速开始

# 全局安装
npm install -g mcp-rubber-duck

# 或者在 Claude Desktop 配置中直接使用 npx
npx mcp-rubber-duck

如果使用 Claude Desktop，请跳转到 Claude Desktop 配置。

✨ 主要特性

• 🔌 通用 OpenAI 兼容性：可与任何兼容 OpenAI 的 API 端点配合使用。
• 🦆 多 “鸭子” 支持：可同时配置和查询多个 LLM 提供商。
• 💬 对话管理：跨多条消息保持上下文。
• 🏛️ 鸭子委员会：一次性从所有配置的 LLM 获得响应。
• 🗳️ 共识投票：多 “鸭子” 投票，附带推理和置信度分数。
• ⚖️ LLM 作为评判者：让 “鸭子” 评估和排名彼此的响应。
• 🔄 迭代改进：两只 “鸭子” 协作改进响应。
• 🎓 结构化辩论：支持牛津式、苏格拉底式和对抗式辩论格式。
• 💾 响应缓存：通过智能缓存避免重复的 API 调用。
• 🔁 自动故障转移：如果主提供商失败，可回退到其他提供商。
• 📊 健康监控：实时检查所有提供商的健康状况。
• 🔗 MCP 桥接：将 “鸭子” 连接到其他 MCP 服务器，以扩展功能。
• 🛡️ 细粒度安全：基于会话批准的每服务器批准控制。
• 🎨 有趣的鸭子主题：带有个性的橡皮鸭调试体验！

📦 安装指南

前提条件

• Node.js 20 或更高版本
• npm 或 yarn
• 至少一个受支持提供商的 API 密钥

安装方法

选项 1：从 NPM 安装

npm install -g mcp-rubber-duck

选项 2：从源代码安装

# 克隆仓库
git clone https://github.com/nesquikm/mcp-rubber-duck.git
cd mcp-rubber-duck

# 安装依赖
npm install

# 构建项目
npm run build

# 运行服务器
npm start

🔧 配置

方法 1：环境变量

在项目根目录创建一个 .env 文件：

# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_DEFAULT_MODEL=gpt-5.1  # 可选：默认为 gpt-5.1

# Google Gemini
GEMINI_API_KEY=...
GEMINI_DEFAULT_MODEL=gemini-2.5-flash  # 可选：默认为 gemini-2.5-flash

# Groq
GROQ_API_KEY=gsk_...
GROQ_DEFAULT_MODEL=llama-3.3-70b-versatile  # 可选：默认为 llama-3.3-70b-versatile

# Ollama (本地)
OLLAMA_BASE_URL=http://localhost:11434/v1  # 可选
OLLAMA_DEFAULT_MODEL=llama3.2  # 可选：默认为 llama3.2

# Together AI
TOGETHER_API_KEY=...

# 自定义提供商 (可添加多个)
# 格式：CUSTOM_{NAME}_*，其中 NAME 成为提供商键 (小写)

# 示例：添加提供商 "myapi"
CUSTOM_MYAPI_API_KEY=...
CUSTOM_MYAPI_BASE_URL=https://api.example.com/v1
CUSTOM_MYAPI_DEFAULT_MODEL=custom-model  # 可选
CUSTOM_MYAPI_MODELS=model1,model2        # 可选：逗号分隔的列表
CUSTOM_MYAPI_NICKNAME=My Custom Duck     # 可选：显示名称

# 示例：添加提供商 "azure" 
CUSTOM_AZURE_API_KEY=...
CUSTOM_AZURE_BASE_URL=https://mycompany.openai.azure.com/v1

# 全局设置
DEFAULT_PROVIDER=openai
DEFAULT_TEMPERATURE=0.7
LOG_LEVEL=info

# MCP 桥接设置 (可选)
MCP_BRIDGE_ENABLED=true                      # 启用 “鸭子” 访问外部 MCP 服务器
MCP_APPROVAL_MODE=trusted                    # always, trusted, or never
MCP_APPROVAL_TIMEOUT=300                     # 秒

# MCP 服务器：Context7 文档 (示例)
MCP_SERVER_CONTEXT7_TYPE=http
MCP_SERVER_CONTEXT7_URL=https://mcp.context7.com/mcp
MCP_SERVER_CONTEXT7_ENABLED=true

# 每服务器受信任的工具
MCP_TRUSTED_TOOLS_CONTEXT7=*                 # 信任所有 Context7 工具

# 可选：自定义 “鸭子” 昵称 (玩得开心！)
OPENAI_NICKNAME="DUCK-4"              # 可选：默认为 "GPT Duck"
GEMINI_NICKNAME="Duckmini"            # 可选：默认为 "Gemini Duck"
GROQ_NICKNAME="Quackers"              # 可选：默认为 "Groq Duck"
OLLAMA_NICKNAME="Local Quacker"       # 可选：默认为 "Local Duck"
CUSTOM_NICKNAME="My Special Duck"     # 可选：默认为 "Custom Duck"

注意：“鸭子” 昵称是完全可选的！如果你不设置它们，将使用迷人的默认名称（GPT Duck、Gemini Duck 等）。如果你使用 config.json 文件，这些昵称将优先于环境变量。

方法 2：配置文件

根据示例创建一个 config/config.json 文件：

cp config/config.example.json config/config.json
# 使用你的 API 密钥和偏好编辑 config/config.json

Claude Desktop 配置

这是使用 MCP Rubber Duck 与 Claude Desktop 的最常见设置方法。

步骤 1：安装

选择以下选项之一：

选项 A：NPM（推荐）

npm install -g mcp-rubber-duck

选项 B：从源代码安装（见 从源代码安装）

步骤 2：配置 Claude Desktop

编辑你的 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加 MCP 服务器配置：

如果通过 NPM 安装：

{
  "mcpServers": {
    "rubber-duck": {
      "command": "mcp-rubber-duck",
      "env": {
        "MCP_SERVER": "true",
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "GEMINI_API_KEY": "your-gemini-api-key-here",
        "DEFAULT_PROVIDER": "openai"
      }
    }
  }
}

如果从源代码安装：

{
  "mcpServers": {
    "rubber-duck": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-rubber-duck/dist/index.js"],
      "env": {
        "MCP_SERVER": "true",
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "GEMINI_API_KEY": "your-gemini-api-key-here",
        "DEFAULT_PROVIDER": "openai"
      }
    }
  }
}

重要：将占位符 API 密钥替换为你实际的密钥：

• your-openai-api-key-here → 你的 OpenAI API 密钥（以 sk- 开头）
• your-gemini-api-key-here → 你从 Google AI Studio 获取的 Gemini API 密钥

注意：MCP_SERVER: "true" 是必需的，这告诉 rubber-duck 作为任何 MCP 客户端的 MCP 服务器运行（与 MCP 桥接功能无关）。

提示：有关 LOG_LEVEL、自定义模型默认值和 “鸭子” 昵称等其他选项，请参阅 配置。

步骤 3：重启 Claude Desktop

1. 完全退出 Claude Desktop（Mac 上使用 ⌘+Q）
2. 再次启动 Claude Desktop
3. MCP 服务器应该会自动连接

步骤 4：测试集成

重启后，在 Claude 中测试以下命令：

检查 “鸭子” 健康状况

使用 list_ducks 工具，设置 check_health: true

应该显示：

• ✅ GPT Duck (openai) - 健康
• ✅ Gemini Duck (gemini) - 健康

列出可用模型

使用 list_models 工具

询问特定 “鸭子”

使用 ask_duck 工具，设置 prompt: "什么是橡皮鸭调试法？"，provider: "openai"

比较多个 “鸭子”

使用 compare_ducks 工具，设置 prompt: "解释 JavaScript 中的 async/await"

测试特定模型

使用 ask_duck 工具，设置 prompt: "你好"，provider: "openai"，model: "gpt-4"

Claude Desktop 设置故障排除

如果工具未显示

1. 检查 API 密钥：确保你的 API 密钥输入正确，没有拼写错误。
2. 验证构建：运行 ls -la dist/index.js 以确认项目构建成功。
3. 检查日志：在 Claude Desktop 的开发者控制台中查找错误。
4. 重启：在配置更改后，完全退出并重启 Claude Desktop。

连接问题

1. 配置文件路径：仔细检查你是否编辑了正确的配置文件路径。
2. JSON 语法：验证你的 JSON 语法（无尾随逗号，正确使用引号）。
3. 绝对路径：确保你使用的是 dist/index.js 的完整绝对路径。
4. 文件权限：验证 Claude Desktop 可以读取 dist 目录。

健康检查失败

如果 “鸭子” 显示为不健康：

1. API 密钥：验证密钥是否有效，并且有足够的信用额度/配额。
2. 网络：检查互联网连接和防火墙设置。
3. 速率限制：一些提供商对新账户有严格的速率限制。

MCP 桥接 - 连接到其他 MCP 服务器

MCP 桥接允许你的 “鸭子” 访问其他 MCP 服务器的工具，从而将它们的功能扩展到不仅仅是聊天。你的 “鸭子” 现在可以搜索文档、访问文件、查询 API 等等！

注意：这与上面的 MCP 服务器集成不同：

• MCP 桥接 (MCP_BRIDGE_ENABLED)：“鸭子” 作为客户端使用外部 MCP 服务器。
• MCP 服务器 (MCP_SERVER)：Rubber-duck 作为 MCP 服务器为任何 MCP 客户端服务。

快速设置

添加以下环境变量以启用 MCP 桥接：

# 基本 MCP 桥接配置
MCP_BRIDGE_ENABLED="true"                # 启用 “鸭子” 访问外部 MCP 服务器
MCP_APPROVAL_MODE="trusted"              # always, trusted, or never
MCP_APPROVAL_TIMEOUT="300"               # 5 分钟

# 示例：Context7 文档服务器
MCP_SERVER_CONTEXT7_TYPE="http"
MCP_SERVER_CONTEXT7_URL="https://mcp.context7.com/mcp"
MCP_SERVER_CONTEXT7_ENABLED="true"

# 信任所有 Context7 工具 (无需批准)
MCP_TRUSTED_TOOLS_CONTEXT7="*"

批准模式

• always：每次工具调用都需要批准（具有基于会话的记忆）
  • 首次使用工具 → 需要批准
  • 后续使用同一工具 → 自动执行（直到重启）
• trusted：只有不受信任的工具需要批准
  • 受信任列表中的工具立即执行
  • 未知工具需要批准
• never：所有工具立即执行（谨慎使用）

每服务器受信任的工具

为每个 MCP 服务器配置信任级别，以实现细粒度的安全性：

# 信任来自 Context7（文档服务器）的所有工具
MCP_TRUSTED_TOOLS_CONTEXT7="*"

# 仅信任特定的文件系统操作
MCP_TRUSTED_TOOLS_FILESYSTEM="read-file,list-directory"

# 信任特定的 GitHub 工具
MCP_TRUSTED_TOOLS_GITHUB="get-repo-info,list-issues"

# 没有特定配置的服务器的全局回退
MCP_TRUSTED_TOOLS="common-safe-tool"

MCP 服务器配置

使用环境变量配置 MCP 服务器：

HTTP 服务器

MCP_SERVER_{NAME}_TYPE="http"
MCP_SERVER_{NAME}_URL="https://api.example.com/mcp"
MCP_SERVER_{NAME}_API_KEY="your-api-key"        # 可选
MCP_SERVER_{NAME}_ENABLED="true"

STDIO 服务器

MCP_SERVER_{NAME}_TYPE="stdio"
MCP_SERVER_{NAME}_COMMAND="python"
MCP_SERVER_{NAME}_ARGS="/path/to/script.py,--arg1,--arg2"
MCP_SERVER_{NAME}_ENABLED="true"

示例：启用 Context7 文档

# 启用 MCP 桥接
MCP_BRIDGE_ENABLED="true"
MCP_APPROVAL_MODE="trusted"

# 配置 Context7 服务器
MCP_SERVER_CONTEXT7_TYPE="http"
MCP_SERVER_CONTEXT7_URL="https://mcp.context7.com/mcp"
MCP_SERVER_CONTEXT7_ENABLED="true"

# 信任所有 Context7 工具
MCP_TRUSTED_TOOLS_CONTEXT7="*"

现在你的 “鸭子” 可以从 Context7 搜索和检索文档：

询问：“你能从 Context7 找到 React 钩子文档并只返回关键概念吗？”
鸭子：*搜索 Context7 并返回聚焦的、基本的 React 钩子信息*

令牌优化优势

智能令牌管理：“鸭子” 可以从 MCP 服务器检索全面的数据，但只返回你需要的基本信息，从而在你的主机 LLM 对话中节省令牌：

• 询问特定信息：“查找 TypeScript 接口文档并只返回核心概念”
• 鸭子处理完整文档：从 Context7 访问完整的文档
• 返回精简结果：提供聚焦的、相关的信息，同时过滤掉不必要的细节
• 节省令牌：与原始文档转储相比，响应大小减少 70 - 90%

示例工作流程：

你：“从 Context7 查找 Express.js 路由概念，保持简洁”
鸭子：*检索完整的 Express 文档，处理并只返回路由要点*
结果：500 个令牌，而不是原始文档的 5000 + 个令牌

基于会话的批准

当使用 always 模式时，系统会记住你的批准：

1. 第一次：“鸭子想要使用 search-docs - 批准？✅”
2. 下一次：鸭子自动使用 search-docs（无需新的批准）
3. 不同的工具：“鸭子想要使用 get-examples - 批准？✅”
4. 重启：会话记忆清除，重新开始

这消除了批准疲劳，同时保持了安全性！

💻 使用示例

基本查询

// 询问默认 “鸭子”
await ask_duck({ 
  "prompt": "什么是橡皮鸭调试法？" 
});

对话

// 开始对话
await chat_with_duck({
  "conversation_id": "learning-session",
  "message": "你能帮我调试这段代码吗？",
  "provider": "groq"  // 可选，可以在对话中切换提供商
});

// 继续对话
await chat_with_duck({
  "conversation_id": "learning-session", 
  "message": "它与 JavaScript 有什么不同？"
});

比较响应

// 获取不同的观点
await compare_ducks({
  "prompt": "在 Node.js 中处理错误的最佳方法是什么？",
  "providers": ["openai", "groq", "ollama"]
});

鸭子委员会

// 召集委员会进行重要决策
await duck_council({
  "prompt": "我应该为我的 API 使用 REST 还是 GraphQL？"
});

多智能体投票

// 让 “鸭子” 对决策进行投票
await duck_vote({
  "question": "实时聊天应用的最佳数据库是什么？",
  "options": ["PostgreSQL", "MongoDB", "Redis", "Cassandra"]
});
// 返回：获胜者及共识级别（一致、多数、相对多数、分裂、无）

评判响应

// 首先，从委员会获取响应
const responses = await duck_council({
  "prompt": "实现一个速率限制器"
});

// 然后让一只 “鸭子” 评判它们
await duck_judge({
  "responses": responses,
  "criteria": ["正确性", "效率", "可读性"],
  "persona": "资深后端工程师"
});

迭代改进

// 两只 “鸭子” 协作改进解决方案
await duck_iterate({
  "prompt": "编写一个 TypeScript 函数来深度克隆对象",
  "providers": ["openai", "gemini"],
  "mode": "critique-improve",
  "iterations": 3
});

结构化辩论

// 关于架构的牛津式辩论
await duck_debate({
  "prompt": "初创公司的 MVP 应该使用微服务还是单体架构？",
  "format": "oxford",
  "rounds": 3
});

特定提供商设置

Ollama（本地）

# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 拉取模型
ollama pull llama3.2

# Ollama 自动在 localhost:11434/v1 提供兼容 OpenAI 的端点

LM Studio（本地）

1. 从 https://lmstudio.ai/ 下载 LM Studio。
2. 在 LM Studio 中加载模型。
3. 启动本地服务器（在 localhost:1234/v1 提供兼容 OpenAI 的端点）。

Google Gemini

1. 从 Google AI Studio 获取 API 密钥。
2. 添加到环境变量：GEMINI_API_KEY=...
3. 使用兼容 OpenAI 的端点（测试版）。

Groq

1. 从 https://console.groq.com/keys 获取 API 密钥。
2. 添加到环境变量：GROQ_API_KEY=gsk_...

Together AI

1. 从 https://api.together.xyz/ 获取 API 密钥。
2. 添加到环境变量：TOGETHER_API_KEY=...

验证 OpenAI 兼容性

要检查某个提供商是否兼容 OpenAI：

1. 在其 API 文档中查找 /v1/chat/completions 端点。
2. 检查是否支持 OpenAI SDK。
3. 使用 curl 进行测试：

curl -X POST "https://api.provider.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-name",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

开发

在开发模式下运行

npm run dev

运行测试

npm test

代码检查

npm run lint

类型检查

npm run typecheck

Docker 支持

MCP Rubber Duck 提供多平台 Docker 支持，可在 macOS（Intel 和 Apple Silicon）、Linux（x86_64 和 ARM64）、Windows（WSL2） 和 Raspberry Pi 3+ 上运行。

使用预构建镜像快速开始

最简单的开始方式是使用我们的预构建多架构镜像：

# 拉取镜像（适用于所有平台）
docker pull ghcr.io/nesquikm/mcp-rubber-duck:latest

# 创建环境文件
cp .env.template .env
# 编辑 .env 并添加你的 API 密钥

# 使用 Docker Compose 运行（推荐）
docker compose up -d

特定平台部署

桌面/服务器（macOS、Linux、Windows）

# 使用针对桌面优化的设置
./scripts/deploy.sh --platform desktop

# 或者使用更多资源和本地 AI
./scripts/deploy.sh --platform desktop --profile with-ollama

Raspberry Pi

# 使用针对 Pi 优化的设置（内存限制等）
./scripts/deploy.sh --platform pi

# 或者直接复制优化的配置
cp .env.pi.example .env
# 编辑 .env 并添加你的 API 密钥
docker compose up -d

通过 SSH 远程部署

# 部署到远程 Raspberry Pi
./scripts/deploy.sh --mode ssh --ssh-host pi@192.168.1.100

通用部署脚本

scripts/deploy.sh 脚本会自动检测你的平台并应用最佳设置：

# 自动检测平台并部署
./scripts/deploy.sh

# 选项：
./scripts/deploy.sh --help

可用选项：

• --mode：docker（默认）、local 或 ssh
• --platform：pi、desktop 或 auto（默认）
• --profile：lightweight、desktop、with-ollama
• --ssh-host：用于远程部署

特定平台配置

Raspberry Pi（内存优化）

# .env.pi.example - 针对 Pi 3+ 优化
DOCKER_CPU_LIMIT=1.5
DOCKER_MEMORY_LIMIT=512M
NODE_OPTIONS=--max-old-space-size=256

桌面/服务器（高性能）

# .env.desktop.example - 针对强大系统优化
DOCKER_CPU_LIMIT=4.0
DOCKER_MEMORY_LIMIT=2G
NODE_OPTIONS=--max-old-space-size=1024

Docker Compose 配置文件

# 默认配置文件（轻量级，适用于 Pi）
docker compose up -d

# 桌面配置文件（更高的资源限制）
docker compose --profile desktop up -d

# 带有本地 Ollama AI
docker compose --profile with-ollama up -d

构建多架构镜像

对于想要构建和发布自己的多架构镜像的开发者：

# 为 AMD64 + ARM64 构建
./scripts/build-multiarch.sh --platforms linux/amd64,linux/arm64

# 构建并推送到 GitHub 容器注册表
./scripts/gh-deploy.sh --public

带有远程 Docker 的 Claude Desktop

将 Claude Desktop 连接到在远程系统上运行的 MCP Rubber Duck：

{
  "mcpServers": {
    "rubber-duck-remote": {
      "command": "ssh",
      "args": [
        "user@remote-host",
        "docker exec -i mcp-rubber-duck node /app/dist/index.js"
      ]
    }
  }
}

平台兼容性

平台	架构	状态	注意事项
macOS Intel	AMD64	✅ 完全支持	通过 Docker Desktop
macOS Apple Silicon	ARM64	✅ 完全支持	原生 ARM64 支持
Linux x86_64	AMD64	✅ 完全支持	直接 Docker 支持
Linux ARM64	ARM64	✅ 完全支持	服务器、Pi 4+
Raspberry Pi 3+	ARM64	✅ 优化支持	内存受限配置
Windows	AMD64	✅ 完全支持	通过 Docker Desktop + WSL2

手动 Docker 命令

如果你不想使用 docker-compose：

# Raspberry Pi
docker run -d \
  --name mcp-rubber-duck \
  --memory=512m --cpus=1.5 \
  --env-file .env \
  --restart unless-stopped \
  ghcr.io/nesquikm/mcp-rubber-duck:latest

# 桌面/服务器
docker run -d \
  --name mcp-rubber-duck \
  --memory=2g --cpus=4 \
  --env-file .env \
  --restart unless-stopped \
  ghcr.io/nesquikm/mcp-rubber-duck:latest

架构

mcp-rubber-duck/
├── src/
│   ├── server.ts           # MCP 服务器实现
│   ├── config/             # 配置管理
│   ├── providers/          # OpenAI 客户端包装器
│   ├── tools/              # MCP 工具实现
│   ├── services/           # 健康、缓存、对话
│   └── utils/              # 日志记录、ASCII 艺术
├── config/                 # 配置示例
└── tests/                  # 测试套件

故障排除

提供商无法工作

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

连接问题

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

速率限制

• 启用缓存以减少 API 调用。
• 配置故障转移到备用提供商。
• 调整 max_retries 和 timeout 设置。

贡献

     __
   <(o )___
    ( ._> /
     `---'  嘎嘎！准备好调试了！

🦆 想帮助我们让鸭塘变得更好吗？

我们欢迎贡献！无论你是修复 bug、添加功能，还是教我们的 “鸭子” 新技巧，我们都希望你加入我们的团队。

查看我们的 贡献指南 以开始。我们保证这比普通的贡献指南更有趣 - 里面有鸭子！🦆

贡献者快速入门：

1. 分叉仓库
2. 创建功能分支
3. 遵循我们的 常规提交指南
4. 为新功能添加测试
5. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

致谢

• 受橡皮鸭调试法启发
• 基于模型上下文协议（MCP）构建
• 使用 OpenAI SDK 实现通用兼容性

变更日志

请参阅 CHANGELOG.md 以获取详细的变更和发布历史。

注册与目录

MCP Rubber Duck 可通过多个渠道获取：

• NPM 包：npmjs.com/package/mcp-rubber-duck
• Docker 镜像：ghcr.io/nesquikm/mcp-rubber-duck
• MCP 注册表：官方 MCP 服务器 io.github.nesquikm/rubber-duck
• Glama 目录：glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck
• 优秀 MCP 服务器：列在 社区目录 中

支持

• 报告问题：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 鸭子团队调试愉快！ 🦆