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"
      ]
    }
  }
}

平臺兼容性

手動 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 鴨子團隊調試愉快！ 🦆