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开发社区精心打造 ❤️