codex-mcp-server 1.0.0__tar.gz

codex_mcp_server-1.0.0/.gitignore

@@ -0,0 +1,3 @@
+tests/
+__pycache__/
+.trash/

codex_mcp_server-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 guda.studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: codex-mcp-server
+Version: 1.0.0
+Summary: MCP server for Codex CLI with tmux persistence, git worktree isolation, and async dispatch.
+Project-URL: Homepage, https://github.com/GuDaStudio/codexmcp
+Project-URL: Repository, https://github.com/GuDaStudio/codexmcp
+Author-email: "guda.studio" <gudaclaude@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,codex,fastmcp,mcp,tmux,worktree
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: mcp[cli]>=1.20.0
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# codex-mcp-server
+
+MCP server for Codex CLI — tmux persistence, git worktree isolation, async dispatch.
+
+[English](./docs/README_EN.md) | 简体中文
+
+</div>
+
+---
+
+## 特性
+
+- **tmux 持久化** — 所有任务运行在 tmux session 中，网络断开、窗口关闭后任务继续执行
+- **git worktree 隔离** — `full-access` 模式自动创建独立 worktree，并行任务互不干扰
+- **阻塞 + 异步双模式** — `codex` 同步等待结果，`codex_dispatch` 立即返回后台运行
+- **多轮对话 (resume)** — 通过 `session_id` 延续上一次 Codex 会话
+- **文件系统持久化** — 任务元数据存储在 `~/.codexmcp/tasks/`，服务重启后可恢复
+- **工作区日志** — 自动在 `<cwd>/.codex-tasks/` 创建 symlink，IDE 中直接查看日志
+
+## 工具
+
+| 工具 | 作用 | 适合场景 |
+| --- | --- | --- |
+| `codex` | 阻塞执行，等待完成后返回结果 | 代码审阅、短任务、并行模块实现 |
+| `codex_dispatch` | 后台分派，立即返回 task_id | 长任务（数十分钟到数小时） |
+| `codex_status` | 查询任务状态和进度 | 追踪后台任务、获取结果 |
+| `codex_cancel` | 取消运行中的任务 | 终止不需要的任务 |
+
+---
+
+## 前置要求
+
+- Python `3.12+`
+- `codex` CLI 已安装且在 PATH 中
+- `tmux` 已安装（所有模式必须）
+- `git` 已安装（`full-access` 模式必须）
+
+```bash
+codex --version
+tmux -V
+git --version
+```
+
+---
+
+## 安装
+
+### Claude Code
+
+```bash
+claude mcp add codex -s user --transport stdio -- \
+  uvx codex-mcp-server
+```
+
+验证：
+
+```bash
+claude mcp list
+```
+
+### Cursor / 通用 MCP 配置
+
+```json
+{
+  "command": "uvx",
+  "args": ["codex-mcp-server"]
+}
+```
+
+### 从 GitHub 源码安装（开发用）
+
+```bash
+pip install git+https://github.com/GuDaStudio/codexmcp.git
+```
+
+---
+
+## 快速上手
+
+### 1. 代码审阅（阻塞，只读）
+
+```json
+{
+  "tool": "codex",
+  "arguments": {
+    "prompt": "审阅 src/auth/ 目录的代码质量和安全性",
+    "cwd": "/workspace/my-project",
+    "topic": "review-auth",
+    "sandbox": "read-only"
+  }
+}
+```
+
+### 2. 并行模块实现（阻塞，写入）
+
+并发调用多个 `codex`，每个使用不同 `topic`：
+
+```json
+{
+  "tool": "codex",
+  "arguments": {
+    "prompt": "实现用户注册模块...",
+    "cwd": "/workspace/my-project",
+    "topic": "impl-register",
+    "sandbox": "full-access"
+  }
+}
+```
+
+每个 `full-access` 任务自动创建独立的 git worktree 和分支 `agent/<topic>`。
+
+### 3. 长任务后台分派
+
+```json
+{
+  "tool": "codex_dispatch",
+  "arguments": {
+    "prompt": "重构整个项目为异步架构...",
+    "cwd": "/workspace/my-project",
+    "topic": "refactor-async",
+    "sandbox": "full-access"
+  }
+}
+```
+
+立即返回 `task_id`。之后用 `codex_status` 查看进度。
+
+### 4. Resume 多轮对话
+
+首次执行返回 `session_id`。修改代码后继续：
+
+```json
+{
+  "tool": "codex",
+  "arguments": {
+    "prompt": "我已修改了代码，请重新审阅",
+    "cwd": "/workspace/my-project",
+    "topic": "review-auth-r2",
+    "sandbox": "read-only",
+    "session_id": "thread_abc123"
+  }
+}
+```
+
+---
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `prompt` | str | 是 | 任务指令 |
+| `cwd` | Path | 是 | 工作目录（绝对路径） |
+| `topic` | str | 是 | 任务标识。用于 tmux session 名、worktree 分支名、task_id |
+| `sandbox` | `read-only` / `full-access` | 是 | 权限模式。read-only 不建 worktree；full-access 创建 worktree 隔离 |
+| `session_id` | str | 否 | 恢复之前的 Codex 会话（多轮对话） |
+
+## 返回结构
+
+阻塞 `codex` 完成后返回：
+
+```json
+{
+  "success": true,
+  "task_id": "codex-impl-feature",
+  "session_id": "thread_abc123",
+  "result": "Codex 的最终回复文本",
+  "exit_code": 0,
+  "elapsed_seconds": 45.2,
+  "usage": {"input_tokens": 5000, "output_tokens": 1200},
+  "worktree_dir": "/workspace/project-agent-impl-feature",
+  "agent_branch": "agent/impl-feature",
+  "base_branch": "main",
+  "diff_stat": "3 files changed, 42 insertions(+), 10 deletions(-)",
+  "commits_ahead": 2
+}
+```
+
+- `session_id` 用于 resume
+- worktree 相关字段仅 `full-access` 模式返回
+
+---
+
+## 环境变量
+
+通过 MCP 服务进程环境变量配置：
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `CODEX_PROFILE` | codex 配置文件名 | `fast` |
+| `CODEX_REASONING_EFFORT` | 推理强度 | `high`、`xhigh` |
+
+---
+
+## 日志
+
+| 位置 | 路径 |
+|------|------|
+| 工作区 symlink | `<cwd>/.codex-tasks/<topic>/codex-exec.log` |
+| 主存储 | `~/.codexmcp/tasks/<task_id>/codex-exec.log` |
+| 实时查看 | `tmux attach -t codex-<topic>` |
+
+---
+
+## 开发
+
+```bash
+git clone https://github.com/GuDaStudio/codexmcp.git
+cd codexmcp
+pip install -e .
+```
+
+---
+
+## 许可证
+
+[MIT License](./LICENSE)

codex_mcp_server-1.0.0/README.md

@@ -0,0 +1,218 @@
+<div align="center">
+
+# codex-mcp-server
+
+MCP server for Codex CLI — tmux persistence, git worktree isolation, async dispatch.
+
+[English](./docs/README_EN.md) | 简体中文
+
+</div>
+
+---
+
+## 特性
+
+- **tmux 持久化** — 所有任务运行在 tmux session 中，网络断开、窗口关闭后任务继续执行
+- **git worktree 隔离** — `full-access` 模式自动创建独立 worktree，并行任务互不干扰
+- **阻塞 + 异步双模式** — `codex` 同步等待结果，`codex_dispatch` 立即返回后台运行
+- **多轮对话 (resume)** — 通过 `session_id` 延续上一次 Codex 会话
+- **文件系统持久化** — 任务元数据存储在 `~/.codexmcp/tasks/`，服务重启后可恢复
+- **工作区日志** — 自动在 `<cwd>/.codex-tasks/` 创建 symlink，IDE 中直接查看日志
+
+## 工具
+
+| 工具 | 作用 | 适合场景 |
+| --- | --- | --- |
+| `codex` | 阻塞执行，等待完成后返回结果 | 代码审阅、短任务、并行模块实现 |
+| `codex_dispatch` | 后台分派，立即返回 task_id | 长任务（数十分钟到数小时） |
+| `codex_status` | 查询任务状态和进度 | 追踪后台任务、获取结果 |
+| `codex_cancel` | 取消运行中的任务 | 终止不需要的任务 |
+
+---
+
+## 前置要求
+
+- Python `3.12+`
+- `codex` CLI 已安装且在 PATH 中
+- `tmux` 已安装（所有模式必须）
+- `git` 已安装（`full-access` 模式必须）
+
+```bash
+codex --version
+tmux -V
+git --version
+```
+
+---
+
+## 安装
+
+### Claude Code
+
+```bash
+claude mcp add codex -s user --transport stdio -- \
+  uvx codex-mcp-server
+```
+
+验证：
+
+```bash
+claude mcp list
+```
+
+### Cursor / 通用 MCP 配置
+
+```json
+{
+  "command": "uvx",
+  "args": ["codex-mcp-server"]
+}
+```
+
+### 从 GitHub 源码安装（开发用）
+
+```bash
+pip install git+https://github.com/GuDaStudio/codexmcp.git
+```
+
+---
+
+## 快速上手
+
+### 1. 代码审阅（阻塞，只读）
+
+```json
+{
+  "tool": "codex",
+  "arguments": {
+    "prompt": "审阅 src/auth/ 目录的代码质量和安全性",
+    "cwd": "/workspace/my-project",
+    "topic": "review-auth",
+    "sandbox": "read-only"
+  }
+}
+```
+
+### 2. 并行模块实现（阻塞，写入）
+
+并发调用多个 `codex`，每个使用不同 `topic`：
+
+```json
+{
+  "tool": "codex",
+  "arguments": {
+    "prompt": "实现用户注册模块...",
+    "cwd": "/workspace/my-project",
+    "topic": "impl-register",
+    "sandbox": "full-access"
+  }
+}
+```
+
+每个 `full-access` 任务自动创建独立的 git worktree 和分支 `agent/<topic>`。
+
+### 3. 长任务后台分派
+
+```json
+{
+  "tool": "codex_dispatch",
+  "arguments": {
+    "prompt": "重构整个项目为异步架构...",
+    "cwd": "/workspace/my-project",
+    "topic": "refactor-async",
+    "sandbox": "full-access"
+  }
+}
+```
+
+立即返回 `task_id`。之后用 `codex_status` 查看进度。
+
+### 4. Resume 多轮对话
+
+首次执行返回 `session_id`。修改代码后继续：
+
+```json
+{
+  "tool": "codex",
+  "arguments": {
+    "prompt": "我已修改了代码，请重新审阅",
+    "cwd": "/workspace/my-project",
+    "topic": "review-auth-r2",
+    "sandbox": "read-only",
+    "session_id": "thread_abc123"
+  }
+}
+```
+
+---
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `prompt` | str | 是 | 任务指令 |
+| `cwd` | Path | 是 | 工作目录（绝对路径） |
+| `topic` | str | 是 | 任务标识。用于 tmux session 名、worktree 分支名、task_id |
+| `sandbox` | `read-only` / `full-access` | 是 | 权限模式。read-only 不建 worktree；full-access 创建 worktree 隔离 |
+| `session_id` | str | 否 | 恢复之前的 Codex 会话（多轮对话） |
+
+## 返回结构
+
+阻塞 `codex` 完成后返回：
+
+```json
+{
+  "success": true,
+  "task_id": "codex-impl-feature",
+  "session_id": "thread_abc123",
+  "result": "Codex 的最终回复文本",
+  "exit_code": 0,
+  "elapsed_seconds": 45.2,
+  "usage": {"input_tokens": 5000, "output_tokens": 1200},
+  "worktree_dir": "/workspace/project-agent-impl-feature",
+  "agent_branch": "agent/impl-feature",
+  "base_branch": "main",
+  "diff_stat": "3 files changed, 42 insertions(+), 10 deletions(-)",
+  "commits_ahead": 2
+}
+```
+
+- `session_id` 用于 resume
+- worktree 相关字段仅 `full-access` 模式返回
+
+---
+
+## 环境变量
+
+通过 MCP 服务进程环境变量配置：
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `CODEX_PROFILE` | codex 配置文件名 | `fast` |
+| `CODEX_REASONING_EFFORT` | 推理强度 | `high`、`xhigh` |
+
+---
+
+## 日志
+
+| 位置 | 路径 |
+|------|------|
+| 工作区 symlink | `<cwd>/.codex-tasks/<topic>/codex-exec.log` |
+| 主存储 | `~/.codexmcp/tasks/<task_id>/codex-exec.log` |
+| 实时查看 | `tmux attach -t codex-<topic>` |
+
+---
+
+## 开发
+
+```bash
+git clone https://github.com/GuDaStudio/codexmcp.git
+cd codexmcp
+pip install -e .
+```
+
+---
+
+## 许可证
+
+[MIT License](./LICENSE)

codex_mcp_server-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-mcp-server"
+version = "1.0.0"
+description = "MCP server for Codex CLI with tmux persistence, git worktree isolation, and async dispatch."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp[cli]>=1.20.0",
+    "pydantic>=2.0",
+]
+authors = [
+    { name = "guda.studio", email = "gudaclaude@gmail.com" },
+]
+license = { text = "MIT" }
+keywords = ["mcp", "fastmcp", "codex", "tmux", "worktree", "ai-agent"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/GuDaStudio/codexmcp"
+Repository = "https://github.com/GuDaStudio/codexmcp"
+
+[project.scripts]
+codexmcp = "codexmcp.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codexmcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/codexmcp", "README.md", "LICENSE"]

codex_mcp_server-1.0.0/src/codexmcp/__init__.py

@@ -0,0 +1,4 @@
+"""Codex MCP server package."""
+
+__all__ = ["__version__"]
+__version__ = "1.0.0"

codex_mcp_server-1.0.0/src/codexmcp/cli.py

@@ -0,0 +1,12 @@
+"""Console entry point for the Codex MCP server."""
+
+from codexmcp.server import run
+
+
+def main() -> None:
+    """Start the Codex MCP server."""
+    run()
+
+
+if __name__ == "__main__":
+    main()

codex_mcp_server-1.0.0/src/codexmcp/command_builder.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import os
+import shutil
+
+_SANDBOX_MAP = {
+    "full-access": "danger-full-access",
+    "read-only": "read-only",
+}
+
+
+def build_codex_command(
+    cwd: str,
+    sandbox: str,
+    *,
+    session_id: str = "",
+) -> list[str]:
+    """Build the ``codex exec`` CLI command as a list of arguments.
+
+    The prompt is **not** included — it is piped via stdin from a file
+    by the caller (typically the tmux shell command).
+
+    Environment variables ``CODEX_PROFILE`` and ``CODEX_REASONING_EFFORT``
+    are read at call time and forwarded to the CLI when set.
+    """
+    codex_path = shutil.which("codex") or "codex"
+    cli_sandbox = _SANDBOX_MAP.get(sandbox, sandbox)
+    cmd = [codex_path, "exec", "--sandbox", cli_sandbox, "--cd", cwd, "--json"]
+
+    profile = os.environ.get("CODEX_PROFILE", "")
+    if profile:
+        cmd.extend(["--profile", profile])
+
+    effort = os.environ.get("CODEX_REASONING_EFFORT", "")
+    if effort:
+        cmd.extend(["--config", f'model_reasoning_effort="{effort}"'])
+
+    cmd.append("--skip-git-repo-check")
+
+    if session_id:
+        cmd.extend(["resume", session_id, "-"])
+
+    return cmd

codex_mcp_server-1.0.0/src/codexmcp/models.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class SandboxMode(str, Enum):
+    READ_ONLY = "read-only"
+    FULL_ACCESS = "full-access"
+
+
+class TaskMode(str, Enum):
+    BLOCKING = "blocking"
+    DISPATCH = "dispatch"
+
+
+class TaskStatus(str, Enum):
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class EventType(str, Enum):
+    THINKING = "thinking"
+    TEXT = "text"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    COMMAND = "command"
+    ERROR = "error"
+
+
+class TaskMeta(BaseModel):
+    """Persistent task metadata, serialised to ``~/.codexmcp/tasks/<id>/meta.json``."""
+
+    task_id: str
+    mode: TaskMode
+    prompt: str
+    cwd: str
+    sandbox: SandboxMode = SandboxMode.READ_ONLY
+    topic: str
+    tmux_session: str
+    log_file: str
+    prompt_file: str
+    start_time: str  # ISO-8601
+
+    status: TaskStatus = TaskStatus.RUNNING
+
+    # Worktree isolation (None when not used)
+    worktree_dir: Optional[str] = None
+    agent_branch: Optional[str] = None
+    base_branch: Optional[str] = None
+
+    # Codex session (populated after completion, used for resume)
+    session_id: Optional[str] = None
+
+    # Completion fields (populated after task finishes)
+    end_time: Optional[str] = None
+    exit_code: Optional[int] = None
+    result: Optional[str] = None
+
+
+@dataclass
+class TaskEvent:
+    timestamp: datetime
+    type: EventType
+    text: Optional[str] = None
+    tool_name: Optional[str] = None
+    tool_input: Optional[str] = None
+
+
+@dataclass
+class TaskUsage:
+    input_tokens: int
+    output_tokens: int
+    cached_input_tokens: Optional[int] = None