diff --git a/README.md b/README.md
index e69de29..384b998 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,251 @@
+
+
+
+
+**让 Claude Code 与 Gemini CLI 无缝协作**
+
+[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io) [](https://x.com/intent/tweet?text=GeminiMCP：让%20Claude%20Code%20与%20Gemini%20无缝协作%20https://github.com/GuDaStudio/geminimcp%20%23AI%20%23Coding%20%23MCP) [](https://www.facebook.com/sharer/sharer.php?u=https://github.com/GuDaStudio/geminimcp) [](https://www.reddit.com/submit?title=GeminiMCP：让%20Claude%20Code%20与%20Gemini%20无缝协作&url=https://github.com/GuDaStudio/geminimcp) [](https://t.me/share/url?url=https://github.com/GuDaStudio/geminimcp&text=GeminiMCP：让%20Claude%20Code%20与%20Gemini%20无缝协作)
+
+⭐ 在GitHub上给我们点星~您的支持对我们意义重大！ 🙏😊
+
+[English](./docs/README_EN.md) | 简体中文
+
+
+
+---
+
+## 一、项目简介
+
+**GeminiMCP** 是一个 MCP 服务器，将 Google 的 Gemini CLI 工具封装为标准 MCP 协议接口，让 Claude Code 能够调用 Gemini 执行 AI 辅助编程任务。
+
+核心特性：
+- **会话持久化**：通过 `SESSION_ID` 支持多轮对话
+- **流式输出**：实时获取 Gemini CLI 的响应
+- **沙箱模式**：可选的安全隔离执行环境
+- **完整追踪**：可选返回完整的推理过程和工具调用记录
+
+---
+
+## 二、快速开始
+
+### 0. 前置要求
+
+- 已安装并配置 [Claude Code](https://docs.claude.com/docs/claude-code)
+- 已安装并配置 [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+- 已安装 [uv 工具](https://docs.astral.sh/uv/getting-started/installation/)
+
+**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
+```
+
+> **注意：强烈推荐 Windows 用户在 WSL 中运行本项目！**
+
+### 1. 安装步骤
+
+**1.1** 安装 GeminiMCP
+
+```bash
+claude mcp add gemini -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/geminimcp.git geminimcp
+```
+
+**1.2** 验证安装
+
+```bash
+claude mcp list
+```
+
+> 看到 `gemini: ... - ✓ Connected` 说明安装成功
+
+**1.3** 可选：配置自动允许
+
+在 `~/.claude/settings.json` 的 allow 项中添加 `mcp__gemini__gemini`
+
+### 2. 配置claude code提示词（可选）
+
+为使claude code更好完成与codex的协同工作，我们**极力推荐您在 `~/.claude/CLAUDE.md`中添加以下内容**
+
+
+展开查看prompt
+
+
+```
+## Core Instruction for Gemini MCP
+
+在任何时刻，你必须思考当前过程可以如何与codex进行协作，如何调用Codex 为你提供的MCP工具作为你客观全面分析的保障。
+其中你**务必执行**以下几个步骤：
+**1** 在你对用户需求形成初步分析后，将用户需求、初始思路告知codex，并要求其完善需求分析和实施计划。
+**2** 在实施具体编码任务前，**必须向codex索要代码实现原型（要求codex仅给出unified diff patch，严禁对代码做任何真实修改）**。在获取代码原型后，你**只能以此为逻辑参考，再次对代码修改进行重写**，形成企业生产级别、可读性极高、可维护性极高的代码后，才能实施具体编程修改任务。
+**3** 无论何时，只要完成切实编码行为后，**必须立即使用codex review代码改动和对应需求完成程度**。
+**4** codex只能给出参考，你**必须有自己的思考，甚至需要对codex的回答提出置疑**。尽信书则不如无书，你与codex的最终使命都是达成统一、全面、精准的意见，所以你们必须不断争辩已找到通向真理的唯一途径。
+
+
+## Codex Tool Invocation Specification
+
+ 1. 工具概述
+
+ codex MCP 提供了一个工具 `codex`，用于执行 AI 辅助的编码任务。该工具**通过 MCP 协议调用**，无需使用命令行。
+
+ 2. 工具参数
+
+ **必选**参数：
+ - PROMPT (string): 发送给 codex 的任务指令
+ - cd (Path): codex 执行任务的工作目录根路径
+
+ 可选参数：
+ - 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 工具
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `PROMPT` | `str` | ✅ | - | 发送给 Gemini 的任务指令 |
+| `sandbox` | `bool` | ❌ | `False` | 是否启用沙箱模式 |
+| `SESSION_ID` | `str` | ❌ | `""` | 会话 ID（空则开启新会话） |
+| `return_all_messages` | `bool` | ❌ | `False` | 是否返回完整消息记录 |
+| `model` | `str` | ❌ | `""` | 指定模型（默认使用 Gemini CLI 配置） |
+
+### 返回值结构
+
+**成功时：**
+```json
+{
+ "success": true,
+ "SESSION_ID": "session-uuid",
+ "agent_messages": "Gemini 的回复内容..."
+}
+```
+
+**启用 return_all_messages 时额外包含：**
+```json
+{
+ "all_messages": [...]
+}
+```
+
+**失败时：**
+```json
+{
+ "success": false,
+ "error": "错误信息描述"
+}
+```
+
+---
+
+## 四、使用示例
+
+### 开启新会话
+```
+调用 gemini 工具，PROMPT 设为任务描述
+```
+
+### 继续对话
+```
+使用上次返回的 SESSION_ID 继续对话
+```
+
+---
+
+## 五、FAQ
+
+
+Q1: 与 Gemini CLI 直接使用有什么区别？
+
+GeminiMCP 将 Gemini CLI 封装为 MCP 协议，使 Claude Code 可以程序化调用，支持会话管理和结构化返回。
+
+
+
+
+Q2: 会话会冲突吗？
+
+不会。每个会话使用独立的 `SESSION_ID`，完全隔离。
+
+
+
+---
+
+## 🤝 贡献指南
+
+```bash
+# 克隆仓库
+git clone https://github.com/GuDaStudio/geminimcp.git
+cd geminimcp
+
+# 安装依赖
+uv sync
+```
+
+---
+
+## 📄 许可证
+
+本项目采用 [MIT License](LICENSE) 开源协议。
+
+Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com)
diff --git a/images/title.png b/images/title.png
new file mode 100644
index 0000000..11b2bdb
Binary files /dev/null and b/images/title.png differ
diff --git a/pyproject.toml b/pyproject.toml
index 5935736..2a3e274 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,3 +7,9 @@ requires-python = ">=3.12"
dependencies = [
"mcp[cli]>=1.21.2",
]
+
+[project.scripts]
+geminimcp = "geminimcp.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/geminimcp"]
\ No newline at end of file
diff --git a/src/geminimcp/server.py b/src/geminimcp/server.py
index c321830..1737bd4 100644
--- a/src/geminimcp/server.py
+++ b/src/geminimcp/server.py
@@ -110,20 +110,20 @@ def windows_escape(prompt):
@mcp.tool(
name="gemini",
description="""
- Executes a non-interactive gemini session via CLI to perform AI-assisted coding tasks in a secure workspace.
- This tool wraps the `gemini exec` command, enabling model-driven code generation, debugging, or automation based on natural language prompts.
- It supports resuming ongoing sessions for continuity and enforces sandbox policies to prevent unsafe operations. Ideal for integrating gemini into MCP servers for agentic workflows, such as code reviews or repo modifications.
+ Invokes the Gemini CLI to execute AI-driven tasks, returning structured JSON events and a session identifier for conversation continuity.
+
+ **Return structure:**
+ - `success`: boolean indicating execution status
+ - `SESSION_ID`: unique identifier for resuming this conversation in future calls
+ - `agent_messages`: concatenated assistant response text
+ - `all_messages`: (optional) complete array of JSON events when `return_all_messages=True`
+ - `error`: error description when `success=False`
- **Key Features:**
- - **Prompt-Driven Execution:** Send task instructions to gemini for step-by-step code handling.
- - **Workspace Isolation:** Operate within a specified directory, with optional Git repo skipping.
- - **Security Controls:** Three sandbox levels balance functionality and safety.
- - **Session Persistence:** Resume prior conversations via `SESSION_ID` for iterative tasks.
-
- **Edge Cases & Best Practices:**
- - Ensure `cd` exists and is accessible; tool fails silently on invalid paths.
- - For most repos, prefer "read-only" to avoid accidental changes.
- - If needed, set `return_all_messages` to `True` to parse "all_messages" for detailed tracing (e.g., reasoning, tool calls, etc.).
+ **Best practices:**
+ - Always capture and reuse `SESSION_ID` for multi-turn interactions
+ - Enable `sandbox` mode when file modifications should be isolated
+ - Use `return_all_messages` only when detailed execution traces are necessary (increases payload size)
+ - Only pass `model` when the user has explicitly requested a specific model
""",
meta={"version": "0.0.0", "author": "guda.studio"},
)
@@ -153,7 +153,7 @@ async def gemini(
else:
PROMPT = PROMPT
- cmd = ["gemini", PROMPT, "-o", "stream-json"]
+ cmd = ["gemini", "--prompt", PROMPT, "-o", "stream-json"]
if sandbox:
cmd.extend(["--sandbox"])
@@ -177,6 +177,11 @@ async def gemini(
item_type = line_dict.get("type", "")
item_role = line_dict.get("role", "")
if item_type == "message" and item_role == "assistant":
+ if (
+ "The --prompt (-p) flag has been deprecated and will be removed in a future version. Please use a positional argument for your prompt. See gemini --help for more information.\n"
+ in line_dict.get("content", "")
+ ):
+ continue
agent_messages = agent_messages + line_dict.get("content", "")
if line_dict.get("session_id") is not None:
thread_id = line_dict.get("session_id")