# Local Agent MCP

[English](README_EN.md) · [权限说明](docs/permissions.md) · [架构说明](docs/architecture.md)

## 让 ChatGPT Pro 直接在你的本地电脑上干活

你在 ChatGPT 里交代任务，它就能调用本机 MCP 工具：读取项目、修改文件、运行测试、检查 Git Diff、创建 Commit。

复杂任务可以交给本地 Codex。ChatGPT 继续负责拆分步骤、查看进度、补充要求和最终检查。

```text
ChatGPT Pro
→ Local Agent MCP
→ 本地文件 / 测试 / Git / Codex
```

不需要反复复制代码，也不需要让每个任务都绕到 Codex。

> 这是非官方社区项目。它不是 OpenAI 产品，也不代表 OpenAI。

## 快速开始

### 前提条件

准备好以下内容：

- macOS 或 Linux
- Python 3.11 及以上
- Git
- [`uv`](https://docs.astral.sh/uv/)
- OpenAI 官方 [`tunnel-client`](https://github.com/openai/tunnel-client)
- 支持自定义 MCP App 的 ChatGPT 环境
- 一个 Tunnel ID
- 一个对应的 Tunnel Runtime Key

macOS 可以先安装基础工具：

```bash
brew install uv tmux
brew install openai/tools/tunnel-client
```

### 一句话交给 AI

把这句话发给一个能操作本机终端的 AI：

> 把 https://github.com/ezra-y/local-agent-mcp 安装到我的电脑上，并按照 README 完成配置、启动和验证。

手动安装见：[安装到 ChatGPT](#安装到-chatgpt)。

## 亮点

| 亮点 | 说明 |
|---|---|
| ChatGPT 直接操作本地项目 | 常见文件、测试和 Git 操作由 ChatGPT 直接调用本机工具完成。 |
| ChatGPT 负责总指挥 | 简单任务直接完成，复杂任务可以交给本地 Codex。 |
| Agent 可以继续扩展 | Codex 是第一个 Adapter；后续 Agent 放进同一套控制层。 |
| 任务状态可查询 | Workflow、Step、Job 保存到本地 SQLite，重启后仍可查看。 |
| 防止重复执行 | 相同的 `workflow_id + step_id + attempt` 会返回原 Job。 |
| Git 过程清楚 | 先查看状态和 Diff，再提交明确列出的文件；不会自动 Push。 |
| 权限透明 | Tool 和 Resource 都可以返回当前权限资料。 |

## 28 个工具

| 类别 | 工具 | 用途 |
|---|---|---|
| 权限 | `get_permissions` | 查看当前根目录、硬限制和高权限入口。 |
| 文件 | `list_files`、`read_file`、`write_file`、`apply_patch` | 列出、读取、创建、覆盖或局部修改文本文件。 |
| 命令与测试 | `run_command`、`run_tests`、`get_job`、`cancel_job` | 运行命令或测试，并查看或停止后台 Job。 |
| Git | `git_status`、`git_diff`、`git_commit` | 查看状态、查看 Diff、提交明确列出的文件；安全 Commit 会关闭 Hook 和签名，并拒绝 Git Filter。 |
| 工作流程 | `create_workflow`、`create_step`、`start_step`、`get_workflow` | 建立 Workflow、创建 Step、启动 Job、查询整体状态。 |
| 一次性只读 Codex | `ask_codex`、`start_codex_job`、`get_codex_job`、`cancel_codex_job` | 让本地 Codex 做一次只读检查。 |
| Codex 线程 / 回合 | `list_codex_threads`、`read_codex_thread`、`resume_codex_thread`、`start_codex_turn`、`steer_codex_turn`、`interrupt_codex_turn`、`get_codex_turn_status` | 读取旧 Thread，启动、继续、补充、停止和检查 Codex Turn。 |
| 健康检查 | `ping` | 查看服务状态、活动 Job 数和 Artifact 容量警告。 |

直接的 `delete_file` Tool 没有暴露。`apply_patch` 也拒绝删除整个文件。

`git_commit` 默认关闭仓库 Hook 和提交签名。检测到 `clean` / `process` Git Filter 时会拒绝提交，避免结构化 Commit 隐式运行仓库程序。`git_diff` 同时关闭外部 Diff 和 `textconv`。

## 权限 Resource

除了 `get_permissions` Tool，服务还提供：

```text
local-agent://permissions
```

内容包括：

```text
当前允许访问哪里
哪些目录和文件被禁止
读写是否开启
有没有直接删除工具
高权限入口有哪些
```

`get_permissions` 会继续保留，方便尚未展示 MCP Resources 的客户端使用。

## 权限与减权

### 默认范围

结构化文件和 Git 工具默认可以访问当前用户的 Home：

```text
$HOME
```

通常包括 Desktop、Downloads、Documents 和个人目录下的其他项目。

### 代码强制禁止的内容

结构化文件工具会拒绝：

```text
.ssh
.aws
.azure
.codex
.docker
.gnupg
.kube
.Trash
Library
.env 和 .env.*
常见凭据文件
.pem / .key / .p12 / .pfx 私钥文件
符号链接路径
```

同时：

- 没有直接文件删除 Tool。
- `apply_patch` 不能删除整个文件。
- 没有 Git Push Tool。
- `git_commit` 只提交明确列出的路径。

### 缩小结构化范围

启动前设置：

```bash
export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"
```

旧配置名 `CODEX_MCP_ROOT` 仍然兼容。

之后这些工具只能访问 `$HOME/Projects`：

```text
list_files
read_file
write_file
apply_patch
git_status
git_diff
git_commit
```

前台启动示例：

```bash
export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"
./scripts/run_tunnel.sh
```

### 高权限入口

| 能力 | 实际范围 |
|---|---|
| `run_tests` | 会执行项目代码。测试代码可以创建、修改或删除文件。 |
| `run_command` | 被调用的本机程序可能访问结构化根目录之外的位置。 |
| 完整 Codex Turn | 可以读写、运行命令和联网，也可能访问结构化根目录之外的位置。 |

`LOCAL_AGENT_MCP_ROOT` 是结构化文件与 Git 工具的硬边界，不是整个进程的系统沙箱。

需要仓库 Hook、Git LFS 或其他 Filter 时，请手动提交，或在明确检查仓库配置后使用高权限的 `run_command`。

v0.5.1 暂时没有按单个 Tool 隐藏或关闭的配置。需要更强隔离时，可以使用独立系统用户、虚拟机、容器，或维护删减 Tool 的版本。

完整说明见 [docs/permissions.md](docs/permissions.md)。

## 安装到 ChatGPT

### 1. 下载并测试

```bash
git clone https://github.com/ezra-y/local-agent-mcp.git
cd local-agent-mcp
uv sync --locked --all-groups
uv run pytest -q
```

本地 Codex 的查找顺序：

1. `CODEX_BIN` 指定的路径。
2. `PATH` 中的 `codex`。
3. macOS ChatGPT App 内置的 Codex。

### 2. 保存 Runtime Key

macOS：

```bash
./scripts/save_tunnel_key.sh
```

Linux：

```bash
export CONTROL_PLANE_API_KEY="<你的 Runtime Key>"
```

### 3. 生成 Tunnel 配置

```bash
export CONTROL_PLANE_TUNNEL_ID="tunnel_<32位小写十六进制>"
./scripts/configure_tunnel.sh
```

本地配置保存在：

```text
.runtime/profiles/
```

### 4. 启动 Tunnel

前台：

```bash
./scripts/run_tunnel.sh
```

后台：

```bash
tmux new-session -d \
  -s local-agent-mcp-tunnel \
  -c "$PWD" \
  ./scripts/run_tunnel.sh
```

等待服务就绪：

```bash
for i in {1..30}; do
  curl -fsS http://127.0.0.1:8741/readyz && break
  sleep 1
done
```

成功时返回：

```text
ready
```

本地状态页：

```text
http://127.0.0.1:8741/ui
```

### 5. 在 ChatGPT 中连接

1. 打开 **Settings → Apps**。
2. 开启 **Developer Mode**。
3. 创建或连接对应的自定义 MCP App。
4. Tunnel 启动后，点击 **Refresh / Scan tools**。
5. 新开聊天并选择 `@Local Agent`。

### 6. 验证

在新聊天发送：

```text
@Local Agent

调用 get_permissions。
报告当前工具总数、版本和 allowed_root。
```

v0.5.1 的预期结果：

```text
工具总数：28
版本：0.5.1
allowed_root：你的 Home，或你设置的 LOCAL_AGENT_MCP_ROOT
```

客户端支持 Resources 时，再尝试读取：

```text
local-agent://permissions
```

## 只运行本地 stdio MCP

不使用 ChatGPT Tunnel 时：

```bash
./scripts/run_mcp.sh
```

也可以安装成全局命令：

```bash
uv tool install .
local-agent-mcp
```

旧命令 `local-codex-mcp` 仍然可用。

## 日常使用

工具中的 `project` 参数通常填写相对 `$HOME` 的路径：

```text
Documents/Codex/local-agent-mcp
Downloads/my-project
Desktop/example-project
```

Home 内的绝对路径也支持。`project="."` 代表整个结构化根目录；默认设置下就是整个 Home。

### 一个常用任务

```text
@Local Agent

在 Downloads/my-project 修复登录失败问题。
检查相关代码和 Git 状态，完成修改、测试、Diff 和 Commit。
```

常见流程：

```text
get_permissions
→ git_status / list_files / read_file
→ write_file / apply_patch
→ run_tests
→ git_diff
→ git_commit
```

复杂任务可以再加入显式 Workflow 或本地 Codex。

## Workflow 怎么运行

### 五个概念

| 概念 | 含义 |
|---|---|
| Workflow | 用户交代的整件事。 |
| Step | Workflow 中一个稳定、明确的动作。 |
| Job | 某个 Step 的一次实际执行。 |
| Codex Thread | Codex 保存的聊天和工作上下文。 |
| Codex Turn | Thread 中的一轮工作。 |

### 执行顺序

```text
create_workflow
→ create_step
→ start_step
→ get_job / get_workflow
```

`create_step` 当前支持四种执行类型：

| `executor_kind` | 用途 |
|---|---|
| `tests` | 运行测试。 |
| `command` | 运行参数数组形式的本机命令。 |
| `codex_exec_readonly` | 让 Codex 做一次只读检查。 |
| `codex_turn` | 启动一个持续工作的 Codex Turn。 |

文件读取和修改仍由 `read_file`、`write_file`、`apply_patch` 直接完成。

### 示例：创建测试 Step

```text
create_workflow(
  project="Downloads/my-project",
  title="验证登录修复"
)
→ workflow_id
```

```text
create_step(
  workflow_id=workflow_id,
  position=1,
  name="运行测试",
  executor_kind="tests",
  spec={
    "argv": ["uv", "run", "pytest", "-q"],
    "cwd": ".",
    "timeout_seconds": 900
  },
  write_scope="worktree"
)
→ step_id
```

```text
start_step(
  workflow_id=workflow_id,
  step_id=step_id,
  attempt=1
)
→ job_id
```

```text
get_job(job_id)
get_workflow(workflow_id)
```

执行身份是：

```text
workflow_id + step_id + attempt
```

相同编号再次启动，会返回原 Job，不会重复执行。明确重跑时使用新的 attempt，例如 `attempt=2`。

### 并行规则

```text
同一个 Codex Thread：同一时间一个活动 Turn
同一个 Worktree：同一时间一个写入者
同一个仓库：不同 Worktree 可以并行
```

活动 Turn 需要补充要求时使用 `steer_codex_turn`，需要停止时使用 `interrupt_codex_turn`。

## 本地状态和日志

源码运行时：

```text
.runtime/state.sqlite3
.runtime/artifacts/<job_id>/
```

安装后的命令默认使用：

```text
$HOME/.local/state/local-agent-mcp/state.sqlite3
```

自定义位置：

```bash
export LOCAL_AGENT_MCP_STATE_PATH="/自定义位置/state.sqlite3"
```

旧配置名 `CODEX_WORKFLOW_STATE_PATH` 仍然兼容。已有旧状态库也会继续读取。

长日志放在 Artifact 文件中。SQLite 保存路径、大小和 SHA-256。

Artifact 不会自动删除。记录总量超过 1 GiB 时，`ping` 会返回警告。

## 更新

```bash
git pull
uv sync --locked --all-groups
uv run pytest -q
```

然后重启 Tunnel，并在 ChatGPT 中点击 Refresh / Scan tools。

## 项目结构

```text
src/local_agent_mcp/
├── server.py                 MCP 入口与公共 Tool / Resource
├── adapters/                 本地 Agent Adapter；当前包含 Codex
├── workflow_*.py             Workflow、Step、Job、锁和 SQLite
├── command_jobs.py           后台命令与测试
├── workspace_tools.py        文件读写与 Patch
└── git_tools.py              Git 状态、Diff 和 Commit

tests/                        单元测试与集成测试
docs/                         权限和架构说明
scripts/                      MCP 与 Tunnel 启动脚本
```

测试文件会保留在仓库中。它们用于验证权限边界、跨平台运行、打包和兼容性；安装后的 wheel 只包含运行代码。

## 开发检查

```bash
uv run pytest -q
uv run python scripts/check_public_release.py
zsh -n scripts/*.sh
uv build
```

主 MCP 入口是 `src/local_agent_mcp/server.py`。`src/codex_bridge.py` 作为旧导入和旧启动方式的兼容别名保留。

## 卸载和本地数据

卸载程序不会自动删除 SQLite、Artifact、Tunnel profile 或源码目录。请先检查并决定哪些数据需要保留。

## License

MIT，见 [LICENSE](LICENSE)。

> ⚠️ 默认配置会开放较大的本地权限：ChatGPT 可读写当前用户 Home 下的大多数项目，并可运行测试、命令和本地 Agent；请只在你信任的电脑、账号和项目中使用。