diff --git a/README.md b/README.md index 384b998..16f1ed4 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,10 @@ ## 一、项目简介 -**GeminiMCP** 是一个 MCP 服务器，将 Google 的 Gemini CLI 工具封装为标准 MCP 协议接口，让 Claude Code 能够调用 Gemini 执行 AI 辅助编程任务。 +**Gemini-MCP** 是一个 MCP 服务器，将 Google 的 Gemini CLI 工具封装为标准 MCP 协议接口，让 Claude Code 能够调用 Gemini 执行 AI 辅助编程任务。 + +🍟 本项目围绕**gemini强大的前端设计**能力[提供了prompt](#2-配置claude-code提示词可选)，以丰富您的使用场景，我们十分推荐您进行配置！ -核心特性： -- **会话持久化**：通过 `SESSION_ID` 支持多轮对话 -- **流式输出**：实时获取 Gemini CLI 的响应 -- **沙箱模式**：可选的安全隔离执行环境 -- **完整追踪**：可选返回完整的推理过程和工具调用记录 --- @@ -68,9 +65,11 @@ claude mcp list 在 `~/.claude/settings.json` 的 allow 项中添加 `mcp__gemini__gemini` +![](./images/image.png) + ### 2. 配置claude code提示词（可选） -为使claude code更好完成与codex的协同工作，我们**极力推荐您在 `~/.claude/CLAUDE.md`中添加以下内容** +为使claude code更好完成与gemini的协同工作，我们**极力推荐您在 `~/.claude/CLAUDE.md`中添加以下内容**
展开查看prompt @@ -79,78 +78,34 @@ claude mcp list ``` ## Core Instruction for Gemini MCP -在任何时刻，你必须思考当前过程可以如何与codex进行协作，如何调用Codex 为你提供的MCP工具作为你客观全面分析的保障。 +在任何时刻，你必须思考当前过程可以如何与 gemini 进行协作，如何调用 gemini 为你提供的MCP工具作为你**客观全面分析**的保障。 + 其中你**务必执行**以下几个步骤： -**1** 在你对用户需求形成初步分析后，将用户需求、初始思路告知codex，并要求其完善需求分析和实施计划。 -**2** 在实施具体编码任务前，**必须向codex索要代码实现原型（要求codex仅给出unified diff patch，严禁对代码做任何真实修改）**。在获取代码原型后，你**只能以此为逻辑参考，再次对代码修改进行重写**，形成企业生产级别、可读性极高、可维护性极高的代码后，才能实施具体编程修改任务。 -**3** 无论何时，只要完成切实编码行为后，**必须立即使用codex review代码改动和对应需求完成程度**。 -**4** codex只能给出参考，你**必须有自己的思考，甚至需要对codex的回答提出置疑**。尽信书则不如无书，你与codex的最终使命都是达成统一、全面、精准的意见，所以你们必须不断争辩已找到通向真理的唯一途径。 +**1** 在你对用户需求**形成初步分析后**， +（1）首先将用户**原始需求（一字不差，严禁转述）**、以及你的初始思路告知gemini； +（2）与gemini进行**充分讨论、辩驳**，以完善需求分析和实施计划。这一步的结束标志为，**必须**确保对用户需求的透彻理解，并**生成切实可行的行动计划**。 -## Codex Tool Invocation Specification +**2** 在实施具体编码任务前，你**必须向gemini索要代码实现原型**（要求gemini仅给出unified diff patch，严禁对代码做任何真实修改）。在获取代码原型后，你**只能以此为逻辑参考，再次对代码修改进行重写**，形成企业生产级别、可读性极高、可维护性极高的代码后，才能实施具体编程修改任务。 + - **注意：** Gemini 十分擅长前端代码，并精通样式、UI组件设计。在涉及前端代码时，你必须向其索要代码原型（CSS/React/Vue/HTML等前端代码），任何时刻，你**必须以gemini的前端设计（原型代码）为最终的前端代码基点**。 + - 例如，当你识别到用户给出了前端设计需求，你的首要行为必须自动调整为，将用户需求原封不动转发给gemini，并让其出具代码示例（此阶段严禁对用户需求进行任何改动、简写等等）。即你必须从gemini获取代码基点，才可以进行接下来的各种行为。 + +## Gemini Tool Invocation Specification 1. 工具概述 - codex MCP 提供了一个工具 `codex`，用于执行 AI 辅助的编码任务。该工具**通过 MCP 协议调用**，无需使用命令行。 + gemini MCP 提供了一个工具 `gemini`，用于调用 Google Gemini 模型执行 AI 任务。该工具拥有极强的前端审美、任务规划与需求理解能力，但在**上下文长度（Effective 32k）**上有限制。 - 2. 工具参数 +2. 使用方式与规范 - **必选**参数： - - PROMPT (string): 发送给 codex 的任务指令 - - cd (Path): codex 执行任务的工作目录根路径 + **必须遵守的限制**： + - **会话管理**：捕获返回的 `SESSION_ID` 用于多轮对话。 + - **后端避让**：严禁让 Gemini 编写复杂的后端业务逻辑代码。 - 可选参数： - - sandbox (string): 沙箱策略，可选值： - - "read-only" (默认): 只读模式，最安全 - - "workspace-write": 允许在工作区写入 - - "danger-full-access": 完全访问权限 - - SESSION_ID (UUID | null): 用于继续之前的会话以与codex进行多轮交互，默认为 None（开启新会话） - - skip_git_repo_check (boolean): 是否允许在非 Git 仓库中运行，默认 False - - return_all_messages (boolean): 是否返回所有消息（包括推理、工具调用等），默认 False - - image (List[Path] | null): 附加一个或多个图片文件到初始提示词，默认为 None - - model (string | null): 指定使用的模型，默认为 None（使用用户默认配置） - - yolo (boolean | null): 无需审批运行所有命令（跳过沙箱），默认 False - - profile (string | null): 从 `~/.codex/config.toml` 加载的配置文件名称，默认为 None（使用用户默认配置） - - 返回值： - { - "success": true, - "SESSION_ID": "uuid-string", - "agent_messages": "agent回复的文本内容", - "all_messages": [] // 仅当 return_all_messages=True 时包含 - } - 或失败时： - { - "success": false, - "error": "错误信息" - } - - 3. 使用方式 - - 开启新对话： - - 不传 SESSION_ID 参数（或传 None） - - 工具会返回新的 SESSION_ID 用于后续对话 - - 继续之前的对话： - - 将之前返回的 SESSION_ID 作为参数传入 - - 同一会话的上下文会被保留 - - 4. 调用规范 - - **必须遵守**： - - 每次调用 codex 工具时，必须保存返回的 SESSION_ID，以便后续继续对话 - - cd 参数必须指向存在的目录，否则工具会静默失败 - - 严禁codex对代码进行实际修改，使用 sandbox="read-only" 以避免意外，并要求codex仅给出unified diff patch即可 - - 推荐用法： - - 如需详细追踪 codex 的推理过程和工具调用，设置 return_all_messages=True - - 对于精准定位、debug、代码原型快速编写等任务，优先使用 codex 工具 - - 5. 注意事项 - - - 会话管理：始终追踪 SESSION_ID，避免会话混乱 - - 工作目录：确保 cd 参数指向正确且存在的目录 - - 错误处理：检查返回值的 success 字段，处理可能的错误 + **擅长场景（必须优先调用 Gemini）**： + - **需求清晰化**：在任务开始阶段辅助生成引导性问题。 + - **任务规划**：生成 Step-by-step 的实施计划。 + - **前端原型**：编写 CSS、HTML、UI 组件代码，调整样式风格。 ``` @@ -161,6 +116,10 @@ claude mcp list ## 三、工具说明 +
+ +展开查看gemini 工具详情 + ### gemini 工具 | 参数 | 类型 | 必填 | 默认值 | 说明 | @@ -197,23 +156,14 @@ claude mcp list } ``` ---- -## 四、使用示例 - -### 开启新会话 -``` -调用 gemini 工具，PROMPT 设为任务描述 -``` - -### 继续对话 -``` -使用上次返回的 SESSION_ID 继续对话 -``` +
--- -## 五、FAQ + + +## 四、FAQ
Q1: 与 Gemini CLI 直接使用有什么区别？ @@ -249,3 +199,12 @@ uv sync 本项目采用 [MIT License](LICENSE) 开源协议。 Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com) + +--- +
+ +## 用 🌟 为本项目助力~ + +
+ +[![Star History Chart](https://api.star-history.com/svg?repos=GuDaStudio/geminimcp&type=date&legend=top-left)](https://www.star-history.com/#GuDaStudio/geminimcp&type=date&legend=top-left) diff --git a/docs/README_EN.md b/docs/README_EN.md new file mode 100644 index 0000000..ac85af0 --- /dev/null +++ b/docs/README_EN.md @@ -0,0 +1,210 @@ +![Banner](../images/title.png) + +
+ +**Seamless Integration Between Claude Code and Gemini CLI** + +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io) [![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=GeminiMCP:%20Seamless%20Integration%20Between%20Claude%20Code%20and%20Gemini%20https://github.com/GuDaStudio/geminimcp%20%23AI%20%23Coding%20%23MCP) [![Share](https://img.shields.io/badge/share-1877F2?logo=facebook&logoColor=white)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/GuDaStudio/geminimcp) [![Share](https://img.shields.io/badge/share-FF4500?logo=reddit&logoColor=white)](https://www.reddit.com/submit?title=GeminiMCP:%20Seamless%20Integration%20Between%20Claude%20Code%20and%20Gemini&url=https://github.com/GuDaStudio/geminimcp) [![Share](https://img.shields.io/badge/share-0088CC?logo=telegram&logoColor=white)](https://t.me/share/url?url=https://github.com/GuDaStudio/geminimcp&text=GeminiMCP:%20Seamless%20Integration%20Between%20Claude%20Code%20and%20Gemini) + +⭐ Star us on GitHub! Your support means the world to us! 🙏😊 + +English | [简体中文](../README.md) + +
+ +--- + +## 1. Overview + +**Gemini-MCP** is an MCP server that wraps Google's Gemini CLI tool as a standard MCP protocol interface, enabling Claude Code to invoke Gemini for AI-assisted programming tasks. + +🍟 This project provides [carefully crafted prompts](#2-configure-claude-code-prompts-optional) centered around **Gemini's exceptional frontend design capabilities** to enrich your use cases. We highly recommend configuring them! + + +--- + +## 2. Quick Start + +### 0. Prerequisites + +- Installed and configured [Claude Code](https://docs.claude.com/docs/claude-code) +- Installed and configured [Gemini CLI](https://github.com/google-gemini/gemini-cli) +- Installed [uv tool](https://docs.astral.sh/uv/getting-started/installation/) + +**Installing uv:** + +Windows (PowerShell): +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +Linux/macOS: +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +> **Note: Windows users are strongly recommended to run this project in WSL!** + +### 1. Installation Steps + +**1.1** Install GeminiMCP + +```bash +claude mcp add gemini -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/geminimcp.git geminimcp +``` + +**1.2** Verify Installation + +```bash +claude mcp list +``` + +> If you see `gemini: ... - ✓ Connected`, the installation was successful + +**1.3** Optional: Configure Auto-Allow + +Add `mcp__gemini__gemini` to the allow list in `~/.claude/settings.json` + +![Configuration](../images/image.png) + +### 2. Configure Claude Code Prompts (Optional) + +To enable optimal collaboration between Claude Code and Gemini, we **strongly recommend adding the following content to `~/.claude/CLAUDE.md`** + +
+Click to view prompt + + +``` +## Core Instruction for Gemini MCP + +At any point, you must consider how the current process can collaborate with Gemini and how to invoke the Gemini MCP tools as a guarantee for your **objective and comprehensive analysis**. + +You **must execute** the following steps: + +**1** After you **form an initial analysis** of the user's requirements: +(1) First, inform Gemini of the user's **original requirements (verbatim, no paraphrasing)** and your initial approach; +(2) Engage in **thorough discussion and debate** with Gemini to refine requirement analysis and implementation plans. This step concludes only when you have **ensured a thorough understanding of user requirements and generated a practical action plan**. + +**2** Before implementing specific coding tasks, you **must request a code implementation prototype from Gemini** (require Gemini to provide only unified diff patches, strictly prohibit any actual code modifications). After obtaining the code prototype, you **may only use it as a logical reference, then rewrite the code modifications** to create production-grade, highly readable, and maintainable code before implementing the actual programming modifications. + - **Note:** Gemini excels at frontend code and is proficient in styling and UI component design. When working with frontend code, you must request code prototypes from it (CSS/React/Vue/HTML and other frontend code). At all times, you **must use Gemini's frontend design (prototype code) as the foundation for final frontend code**. + - For example, when you identify that a user has provided frontend design requirements, your first action must automatically shift to forwarding the user's requirements verbatim to Gemini and having it produce code examples (strictly prohibit any modifications or abbreviations to user requirements at this stage). That is, you must obtain the code foundation from Gemini before proceeding with any subsequent actions. + +## Gemini Tool Invocation Specification + +1. Tool Overview + + Gemini MCP provides a tool called `gemini` for invoking Google Gemini models to execute AI tasks. This tool possesses exceptional frontend aesthetics, task planning, and requirement understanding capabilities, but has limitations in **context length (Effective 32k)**. + +2. Usage and Specifications + + **Mandatory Restrictions**: + - **Session Management**: Capture the returned `SESSION_ID` for multi-turn conversations. + - **Backend Avoidance**: Strictly prohibit Gemini from writing complex backend business logic code. + + **Optimal Scenarios (Must Prioritize Gemini Invocation)**: + - **Requirement Clarification**: Assist in generating guiding questions during the task initiation phase. + - **Task Planning**: Generate step-by-step implementation plans. + - **Frontend Prototypes**: Write CSS, HTML, UI component code, and adjust styling. + +``` + +
+ + +--- + +## 3. Tool Documentation + +
+ +Click to view gemini tool details + +### gemini Tool + +| Parameter | Type | Required | Default | Description | +|------|------|------|--------|------| +| `PROMPT` | `str` | ✅ | - | Task instructions sent to Gemini | +| `sandbox` | `bool` | ❌ | `False` | Enable sandbox mode | +| `SESSION_ID` | `str` | ❌ | `""` | Session ID (empty for new session) | +| `return_all_messages` | `bool` | ❌ | `False` | Return complete message history | +| `model` | `str` | ❌ | `""` | Specify model (defaults to Gemini CLI config) | + +### Return Value Structure + +**On Success:** +```json +{ + "success": true, + "SESSION_ID": "session-uuid", + "agent_messages": "Gemini's response content..." +} +``` + +**When return_all_messages is enabled, additionally includes:** +```json +{ + "all_messages": [...] +} +``` + +**On Failure:** +```json +{ + "success": false, + "error": "Error description" +} +``` + + +
+ +--- + + + +## 4. FAQ + +
+Q1: What's the difference from using Gemini CLI directly? + +GeminiMCP wraps Gemini CLI as an MCP protocol, enabling programmatic invocation by Claude Code with support for session management and structured returns. + +
+ +
+Q2: Will sessions conflict? + +No. Each session uses an independent `SESSION_ID`, ensuring complete isolation. + +
+ +--- + +## 🤝 Contributing + +```bash +# Clone repository +git clone https://github.com/GuDaStudio/geminimcp.git +cd geminimcp + +# Install dependencies +uv sync +``` + +--- + +## 📄 License + +This project is licensed under the [MIT License](../LICENSE). + +Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com) + +--- +
+ +## Power this project with a 🌟~ + +
+ +[![Star History Chart](https://api.star-history.com/svg?repos=GuDaStudio/geminimcp&type=date&legend=top-left)](https://www.star-history.com/#GuDaStudio/geminimcp&type=date&legend=top-left) diff --git a/images/image.png b/images/image.png new file mode 100644 index 0000000..4347919 Binary files /dev/null and b/images/image.png differ diff --git a/images/title.png b/images/title.png index 11b2bdb..f5e9172 100644 Binary files a/images/title.png and b/images/title.png differ