Revolver Orchestrator MCP

🚀 AI規劃系統（適用於Claude Code）

這是一個全面的AI規劃系統，它將谷歌的Gemini CLI作為規劃後端與Claude Code集成以實現具體功能。該系統具備自動規劃 - 執行工作流、持久上下文管理以及無縫的MCP集成等特性。

🚀 快速開始

前提條件

• Node.js 18+
• Go 1.19+（用於Gemini CLI）
• 已安裝Claude Code
• 從 Google AI Studio 獲取的Gemini API密鑰

安裝步驟

1. 克隆並設置系統：

   git clone <repository-url>
   cd revolver-orchestrator-mcp/
   ./scripts/setup-gemini-cli.sh
   

2. 創建並配置環境文件： cp .env.example .env 在 .env 文件中添加你的Gemini API密鑰 - GEMINI_API_KEY

3. 安裝依賴並構建：

   ./scripts/install-dependencies.sh
   

4. 設置Claude集成：

   ./scripts/setup-claude-integration.sh
   

   此腳本將：

   • 檢測你的Claude安裝（命令或別名）
   • 使用 claude mcp add-json 註冊Gemini規劃MCP服務器
   • 必要時回退到直接配置文件方法
   • 使用適當的依賴構建MCP服務器

5. 測試系統：

   ./scripts/test-system.sh
   

✨ 主要特性

• 🤖 Gemini 2.5 Pro集成：使用谷歌最新的Gemini CLI進行高級規劃
• 🔄 上下文管理：在規劃和執行會話中保持持久上下文
• 🔁 規劃 - 執行工作流：自動生成規劃，然後逐步執行
• 🛠️ Claude Code集成：通過模型上下文協議（MCP）實現無縫集成
• 📊 進度監控：即時監控規劃和執行進度
• 🎯 基於環境的配置：無硬編碼默認值，可通過 .env 文件完全配置
• 🧩 基於提示的庫自動解析：用自然語言描述你的技術棧或傳遞結構化的庫規範

💻 使用示例

規劃 - 執行工作流（推薦）

使用此模式進行自動規劃和實現：

構建一個滿足以下要求的React待辦事項應用程序：
- 添加、編輯、刪除待辦事項
- 將待辦事項標記為已完成
- 本地存儲持久化
- 簡潔、現代的用戶界面

工作流：
1. 為此任務創建項目上下文
2. 使用Gemini生成詳細的實現計劃
3. 逐步執行計劃

請自動遵循此工作流。

手動逐步流程

1. 創建項目上下文：

   為一個具有React前端和Node.js後端的即時聊天應用程序創建項目上下文
   

2. 生成詳細計劃：

   使用Gemini MCP為聊天應用程序上下文生成全面的實現計劃
   

3. 執行計劃：

   現在逐步執行計劃，創建所有必要的文件和組件
   

經驗法則

一般來說，如果你想激活工具調用，只需在提示中包含 "使用Gemini進行規劃"。

快速示例

# 具有自動規劃的簡單Web應用
構建一個具有本地存儲的React待辦事項應用。首先創建項目上下文，使用Gemini生成計劃，然後實現它。

# 帶有規劃的API開發
創建一個具有JWT認證的任務管理REST API。使用Gemini MCP規劃架構，然後逐步實現它。

# 全棧應用程序
構建一個具有React前端和Node.js後端的即時聊天應用。首先使用Gemini進行規劃，然後執行實現。

📚 詳細文檔

架構

┌─────────────────────┐    ┌─────────────────────┐
│    Claude Code      │    │   Gemini CLI        │
│   (Execution)       │────│   (Planning)        │
└─────────────────────┘    └─────────────────────┘
         │                           │
         └─────────┬─────────────────┘
                   │
   ┌─────────────────────────────────────┐
   │        MCP Integration              │
   │  - Context Management              │
   │  - Feedback Processing             │
   │  - Session Coordination            │
   └─────────────────────────────────────┘

配置

環境配置

所有配置都通過 .env 文件完成（無硬編碼默認值）：

# Gemini配置
GEMINI_API_KEY=you_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-pro
GEMINI_TEMPERATURE=0.3
GEMINI_MAX_TOKENS=4000
GEMINI_CLI_PATH=gemini

# Context7 MCP URL
CONTEXT7_URL=https://mcp.context7.com/mcp

# 系統配置
LOG_LEVEL=info
CONTEXT_STORAGE_PATH=./contexts

可用模型

注意：Gemini模型的使用是免費的，但對於Gemini CLI有使用限制。通常，這對於日常規劃任務來說已經足夠。

• gemini-2.5-pro - 最新且功能最強大的模型（推薦）
• gemini-2.5-flash - 通用型，性能均衡
• gemini-2.5-flash-lite - 2.5系列中最輕量級的模型

配置說明

• GEMINI_API_KEY 是必需的 - 從 Google AI Studio 獲取
• GEMINI_MODEL 決定用於規劃的模型
• GEMINI_TEMPERATURE 控制響應的創造性（0.1 - 0.9）
• 現代Gemini CLI可能不會直接使用 GEMINI_TEMPERATURE 和 GEMINI_MAX_TOKENS
• 系統完全依賴環境變量進行配置

工具和實用程序

上下文監控

# 查看特定上下文
node tools/context-viewer.js <context-id>

# 監控所有上下文
./tools/monitor-contexts.sh

系統測試

# 測試Gemini CLI連接
./scripts/test-system.sh

# 測試MCP服務器
cd gemini-cli-mcp-server && npm test

項目結構

ai-planning-system/
├── gemini-cli-mcp-server/     # Gemini CLI MCP包裝器
│   ├── src/
│   │   ├── services/          # 規劃服務
│   │   ├── gemini-cli-wrapper.ts  # Gemini CLI集成
│   │   └── index.ts          # MCP服務器入口點
│   ├── tsconfig.json         # TypeScript配置
│   └── package.json
├── shared-context/            # 上下文管理
│   ├── types.ts              # TypeScript定義
│   └── context-store.ts      # 上下文存儲
├── contexts/                 # 存儲的項目上下文
├── examples/                 # 使用示例和工作流
│   └── plan-then-execute-workflow.md
├── tools/                    # 實用工具
├── scripts/                  # 設置和實用腳本
│   ├── setup-gemini-cli.sh   # Gemini CLI安裝
│   ├── setup-claude-integration.sh  # Claude Code設置
│   ├── install-dependencies.sh  # 依賴安裝
│   └── test-system.sh        # 系統測試
├── .env                      # 環境配置
├── CLAUDE.md                 # Claude Code集成指南
└── README.md

API參考

MCP工具

create_project_context

為項目創建新的規劃上下文。 參數：

• projectName：項目名稱
• requirements：項目要求和規範
• constraints：任何約束或限制

generate_plan_with_gemini

使用Gemini CLI生成詳細的實現計劃。 參數：

• contextId (字符串)：項目上下文ID（可選）
• projectName (字符串)：如果未提供 contextId，則為必需項
• requirements (字符串)：如果未提供 contextId，則為必需項
• constraints (字符串，可選)
• libraries (數組，可選)：用於從Context7獲取文檔的結構化庫規範
  • name (字符串)：規範的包或倉庫名稱，例如 react、next.js、supabase/supabase、tanstack/query
  • topic (字符串，可選)：縮小關注範圍，例如 routing、auth、storage
  • tokens (數字，可選)：文檔的近似令牌預算
• librariesPrompt (字符串，可選)：所需技術棧的自然語言描述；如果提供且未提供 libraries，系統將自動解析庫

libraries 或 librariesPrompt 至少提供一個。如果兩者都提供，libraries 優先。

test_gemini_connection

測試與Gemini CLI的連接。

test_context7_connection

測試與Context7 MCP的連接並列出可用工具。

render_plan_checklist

將存儲的計劃渲染為便於在終端查看的清單。 參數：

• contextId (必需)
• planIndex (可選，默認為最新)

示例輸出：

概述：使用Astro和Tailwind的個人網站

依賴項：
  - astro@^5.0.0 — 核心框架
  - tailwindcss@^4.0.0 — CSS實用框架

文件結構：
  - src
  - src/components
  - src/sections
  - src/layouts
  - src/pages
  - src/content
  - src/styles
  - src/utils

實現步驟：
  安裝：
  - [ ] 步驟1：初始化Astro項目
    - 創建package.json
    - 創建astro.config.mjs

示例

Web應用程序開發

// 創建上下文並進行規劃
const context = await createProjectContext(
  "電子商務平臺",
  "React前端、Node.js API、PostgreSQL數據庫、用戶認證、產品目錄、購物車"
);

const plan = await generatePlanWithGemini(context.id);
// 計劃包括：架構、實現步驟、文件結構、依賴項

API開發

基於提示的庫解析

結構化輸入示例：

{
  "projectName": "Next.js + Supabase SaaS",
  "requirements": "具有認證、行級安全（RLS）和Stripe集成的訂閱應用程序",
  "constraints": "服務器組件、應用路由器",
  "libraries": [
    { "name": "next.js", "topic": "路由" },
    { "name": "supabase/supabase", "topic": "認證" },
    { "name": "tanstack/query" }
  ]
}

基於提示的示例：

{
  "projectName": "即時筆記",
  "requirements": "具有即時筆記、認證、樂觀UI的Next.js應用程序",
  "librariesPrompt": "使用Next.js（應用路由器）、Supabase進行認證和存儲，以及TanStack Query進行數據獲取"
}

const apiContext = await createProjectContext(
  "任務管理API",
  "具有認證、CRUD操作、通過WebSocket進行即時更新的RESTful API"
);

const apiPlan = await generatePlanWithGemini(apiContext.id);
// 詳細的API設計，包括端點、模型、中間件、測試策略

故障排除

常見問題

1. 未找到Gemini CLI：

   # 將Go二進制文件路徑添加到PATH
   export PATH=$PATH:$(go env GOPATH)/bin
   # 或者重新安裝Gemini CLI
   go install github.com/google-gemini/gemini-cli/cmd/gemini@latest
   

2. API密鑰問題：

   # 使用正確的現代CLI語法進行測試
   GEMINI_API_KEY="your-key" gemini --model gemini-2.5-pro --prompt "Say hello"
   

3. MCP服務器構建錯誤：

   cd gemini-cli-mcp-server
   npm install
   npm run build
   

4. 設置後MCP服務器未顯示：

   # MCP服務器需要重啟Claude才能加載
   # 1. 關閉所有Claude會話
   # 2. 等待幾秒鐘
   # 3. 啟動新的Claude會話
   # 4. 檢查MCP服務器狀態
   claude mcp list
   

5. Claude集成問題：

   # 重新運行設置腳本
   ./scripts/setup-claude-integration.sh
   # 設置後重啟Claude
   # 測試MCP連接
   claude --message "Test the Gemini planning MCP connection"
   

6. 環境變量問題：

   # 驗證.env文件存在且值正確
   cat .env
   # 端到端測試系統
   ./scripts/test-system.sh
   

性能提示

1. 為獲得更快的響應：

   • 在 .env 文件中使用 gemini-1.5-flash 模型
   • 提供更聚焦的需求
   • 將大型項目拆分為較小的上下文

2. 為獲得更好的計劃質量：

   • 使用 gemini-2.5-pro 模型（推薦）
   • 提供詳細的需求和約束
   • 包括特定的技術偏好

調試命令

# 直接測試Gemini CLI
GEMINI_API_KEY="your-key" gemini --model gemini-2.5-pro --prompt "Test message"

# 檢查MCP服務器日誌
cd gemini-cli-mcp-server && node build/index.js

# 驗證所有環境變量是否已設置
env | grep GEMINI

🔧 技術細節

該系統通過將Gemini CLI作為規劃後端，與Claude Code集成，實現了高效的AI規劃和執行。在規劃階段，Gemini CLI根據用戶提供的項目上下文和需求生成詳細的實現計劃。在執行階段，Claude Code根據生成的計劃逐步實現項目。MCP協議的使用確保了兩者之間的無縫集成和上下文的持久化。系統通過環境變量進行配置，避免了硬編碼，提高了靈活性和可維護性。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

額外資源

• CLAUDE.md - Claude Code集成的詳細指南
• examples/plan-then-execute-workflow.md - 全面的工作流示例
• scripts/setup-claude-integration.sh - 自動化設置腳本

支持

問題和疑問處理

1. 查看上述故障排除部分
2. 查看 examples/plan-then-execute-workflow.md 中的示例
3. 測試系統健康狀況：./scripts/test-system.sh
4. 檢查MCP服務器狀態：claude mcp list
5. 測試MCP集成：claude --message "Test the Gemini planning MCP connection"
6. 檢查環境變量：env | grep GEMINI
7. 打開一個包含詳細錯誤信息和日誌的問題報告

獲取幫助

• 設置問題：再次運行 ./scripts/setup-claude-integration.sh
• 規劃問題：檢查Gemini CLI是否正常工作：GEMINI_API_KEY="your-key" gemini --model gemini-2.5-pro --prompt "Hello"
• MCP問題：驗證 ~/.config/claude/mcp_settings.json 是否存在且路徑正確
• 構建問題：運行 cd gemini-cli-mcp-server && npm install && npm run build

為AI開發社區精心打造 ❤️