# aimcp

让 Gemini CLI 或 ChatGPT 通过 MCP 操作你电脑上的代码项目。

安装并连接后，你可以在 Gemini CLI 或 ChatGPT 里直接说：

- “先看看这个项目是做什么的”
- “检查一下现在有哪些改动”
- “修掉这个报错”
- “跑一下测试”
- “把这个功能实现完”
- “切到另一个项目继续”

aimcp 会在你的电脑上读取文件、修改代码、执行命令、查看 Git，并把结果返回给 MCP 客户端。

为了减少模型选择工具时的歧义，多项目 daemon 只公开 15 个顶层工具：`project_control` 加上 `read`、`read_image`、`apply_patch`、`ls`、`grep`、`glob`、`code_explore`、`exec_command`、`write_stdin`、`skills_list`、`skill_read`、`mcp_tools`、`mcp_call`、`summary`。Git 和包管理等操作统一通过 `exec_command` 完成。

> aimcp 面向个人开发环境使用。它拥有很强的本机操作能力，请只连接你信任的 MCP 客户端和项目。

---

## 它是怎么工作的？

aimcp 把本机控制面和真正处理 MCP 请求的 Runtime 分开：

```text
Web Console / CLI
       │
       ▼
本机 Controller ─── 项目、配置、日志、诊断、更新
       │
       ▼
MCP Runtime ─────── 工具执行、OAuth、项目运行态
       │
       ▼
Cloudflare Tunnel 或你自己的 HTTPS 入口
       │
       ▼
ChatGPT 或 Gemini CLI
```

Controller 只监听本机，负责管理状态；Runtime 可以启动或停止。`aimcp stop` 只停止 Runtime，所以 Web Console 仍然能打开并用于修复配置；`aimcp shutdown` 才会把两者都关闭。

所有注册项目共享 **一个 MCP Runtime**。`aimcp project add` 只注册项目，不会隐式启动 Runtime；`aimcp start` 会先注册当前项目，再按保存的运行模式启动 Runtime。

每个 MCP 会话只会绑定一个项目。这样你可以在不同会话里分别处理不同项目，也可以明确切换当前会话使用的项目。ChatGPT 会提供稳定的对话级 session 标识；Gemini CLI 等 MCP 客户端通过独立的 MCP session 隔离绑定。

---

## 你需要准备什么？

### 必需

- **Node.js 22 或更高版本**

### 推荐

- **Git**：用于查看状态、提交历史和差异

### 如果要从 ChatGPT 连接

你需要一个可以通过 HTTPS 访问到本机 aimcp 的公网地址。

最简单的方式是：

- 一个 **Cloudflare 账号**
- 一个已经接入 Cloudflare 的 **域名**

aimcp 可以自动创建和管理 Cloudflare Tunnel。

如果你已经有自己的反向代理、服务器或其他 HTTPS 入口，也可以不让 aimcp 管理 Cloudflare。

### 可选

如果电脑上已经安装了这些工具，aimcp 还可以读取它们已有的能力：

- Codex
- Claude Code
- Agent Skills

没有这些也不影响 aimcp 的核心功能。

---

# 快速开始

## 1. 安装

安装全局 `aimcp` 命令：

```bash
npm install --global @rookiedj/aimcp
```

检查安装：

```bash
aimcp --version
```

如果终端提示找不到 `aimcp`，请确认 npm 的全局可执行目录在 `PATH` 中；可用 `npm config get prefix` 查看全局安装前缀，然后重新打开终端。

从源码运行时，在仓库根目录执行 `npm install`、`npm run build`，再运行 `npm run start:local`。

---

## 2. 打开 Web Console（推荐）

运行：

```bash
aimcp open
```

这只会启动本机 Controller 并打开 Web Console，**不会启动 MCP Runtime，也不会自动修改公网配置**。

推荐按这个顺序使用：

1. 在“项目”里添加 MCP 客户端可以操作的目录
2. 如果要从远程 MCP 客户端连接，在“连接”里按“公网地址 → 连接密码 → 检查连接”三步完成配置
3. 回到“概览”，明确选择“启动公网服务”或“仅本机启动”
4. Codex / Claude / Skills、诊断、日志和更新统一放在“系统”里

如果你更喜欢终端，也可以完全不用 Web：

```bash
aimcp project add /path/to/project
aimcp setup        # 只有需要远程 MCP 连接时才需要
aimcp start
```

### 公网连接

默认情况下，aimcp 会询问是否自动配置 Cloudflare Tunnel。

选择自动配置后，它会：

1. 准备 `cloudflared`
2. 打开浏览器登录 Cloudflare
3. 读取账号中的域名
4. 让你选择一个域名
5. 创建或复用当前电脑对应的 Tunnel
6. candidate 准备完成前保持现有后台服务在线；只有实际切换时才短暂停止
7. 启动 candidate connector，确认它已经连接 Cloudflare
8. 保存原 DNS 记录，再把域名切换到 candidate Tunnel
9. 在默认最多 5 分钟的兜底窗口内验证公网随机探针确实回到这台电脑；可随时 Ctrl+C 安全取消
10. 验证成功后才原子提交本机配置；失败会恢复 DNS，并保留上一次可用配置

例如最终得到：

```text
https://aimcp.example.com/mcp
```

如果你的 Cloudflare 账号里没有已经接入 Cloudflare 的域名，自动 Tunnel 模式无法完成配置。

> Cloudflare Tunnel 生成的 `<UUID>.cfargotunnel.com` 是 DNS CNAME 目标，不是直接给 MCP 客户端使用的地址。

### 使用自己的 HTTPS 入口

如果你不想让 aimcp 管理 Cloudflare，可以在 setup 中选择自己提供公网入口，然后填写你的域名。

此时需要你自己保证：

```text
https://你的域名/mcp
```

能够安全地转发到本机 aimcp 服务。

### 连接密码

公网验证完成后，aimcp 会先生成远程 MCP 连接密码。

**请保存这个密码。**

电脑上只保存密码哈希，不保存明文密码。忘记以后不能找回，只能重新设置。

重新设置密码：

```bash
aimcp auth
```

### 外部能力（可选）

核心公网连接和连接密码完成后，setup 还会检测当前环境是否存在：

- Codex
- Claude Code
- Agent Skills

你可以选择：

- 使用检测到的全部能力
- 自定义启用哪些 MCP / Skills
- 全部关闭

默认推荐自动同步。这样这些工具的配置发生变化后，aimcp 可以自动刷新。当前目录没有检测到某个能力源，不会再把用户之前为其它项目启用的同类能力全局关闭；取消这一步也不会破坏已经完成的公网连接和连接密码。

---

## 3. 用 CLI 启动项目

进入项目目录：

```bash
cd /path/to/your-project
aimcp start
```

`start` 的顺序是：先注册当前项目，再启动/复用 Controller，最后启动 Runtime。这样即使公网配置有问题，项目注册也不会丢，CLI 会给出 Web Console 地址供你继续修复。

如果还没有配置公网连接，裸 `aimcp start` 默认使用**本机模式**。显式运行 `aimcp start --local` 也会把本机模式保存为以后默认；公网模式同样会保存，下次裸 `start` 会复用实际运行模式。

同一个项目以后再次运行不会创建第二套服务器，只会刷新项目状态并确保共享 Runtime 可用。

你也可以从其他目录指定项目：

```bash
aimcp start --root /path/to/your-project
```

查看当前状态：

```bash
aimcp status
```

你会看到：

- Controller 是否运行、Web Console 地址
- MCP Runtime 是否运行，以及当前/默认运行模式
- 本机 MCP 地址
- 公网 MCP 地址
- Cloudflare Tunnel 是否在线
- 当前 CLI 版本和正在运行的 daemon 版本
- 两者版本不一致时的 `aimcp restart` 提示
- 已注册项目
- 每个项目当前有多少会话绑定

---

## 4. 连接 ChatGPT

ChatGPT 的 MCP App 入口和可用套餐可能会变化，请以你当前账号的 Apps 设置为准。

当前常见流程是：

1. 在 ChatGPT 中启用 **Developer Mode**
2. 打开 **Apps → Create**
3. 填入 aimcp 的 MCP 地址
4. 扫描工具（Scan Tools）
5. 按提示完成 OAuth / 密码验证
6. 创建并启用这个 App

MCP 地址就是 setup 最后显示的公网地址，例如：

```text
https://aimcp.example.com/mcp
```

授权时使用 `aimcp setup` 生成的连接密码。

连接完成后，就可以直接让 ChatGPT 操作本机项目。

> 完整 MCP 写入能力是否可用取决于 ChatGPT 当前的套餐、工作区权限和产品开放状态。如果你的设置里没有 Developer Mode 或创建自定义 MCP App 的入口，请先确认当前 ChatGPT 账号是否支持。

## 5. 连接 Gemini CLI

Gemini CLI 支持通过 HTTP 连接 MCP 服务。

在项目目录中启动本机服务：

```bash
npm run start:local
```

然后把本机 MCP 服务注册到 Gemini CLI 的用户配置：

```bash
gemini mcp add --scope user --transport http aimcp http://127.0.0.1:3920/mcp
gemini mcp list
```

确认显示 `Connected` 后，重启 Gemini CLI；进入会话后运行 `/mcp` 查看工具。本机模式只允许同一台电脑上的客户端访问，不需要连接密码。端口 `3920` 是默认值；如果修改过服务端口，注册时同步替换地址。使用公网地址时，把地址换成 `https://你的域名/mcp` 并以公网模式启动；Gemini CLI 会按 OAuth 流程提示授权，连接密码可通过 `aimcp setup` 创建或用 `aimcp auth` 修改。

更多配置选项见 [Gemini CLI MCP 文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)。

---

## 6. 连接 Gemini 应用（网页版）

Gemini 网页应用可以通过“已连接的应用”连接 aimcp 的自定义 MCP。这个流程与 Gemini CLI 的 `gemini mcp add` 不同。

### 准备公网 MCP 地址

Gemini 应用需要访问公网 HTTPS 地址；`127.0.0.1` 只对本机有效，不能填入 Gemini 应用。

```bash
cd /path/to/your-project
aimcp setup           # 尚未配置公网入口时运行
aimcp start --public
aimcp status          # 复制“公网地址”，例如 https://aimcp.example.com/mcp
```

如果已经配置好公网入口，只需确保 Runtime 以公网模式运行，再从 `aimcp status` 复制地址。setup 会显示连接密码；忘记密码时可运行 `aimcp auth` 重新设置。

### 在 Gemini 应用中添加

1. 在电脑上打开 [Gemini 网页应用](https://gemini.google.com/)，进入 **设置 → 个性化智能服务 → 已连接的应用**。
2. 在“自定义应用”中选择添加应用，并粘贴 `aimcp status` 显示的公网 MCP 地址。
3. 按页面提示继续；在 aimcp 授权页输入连接密码并确认授权。
4. 回到 Gemini 对话，输入 `@` 并选择 aimcp，然后提出请求。需要时先说“切换到 `<项目名>` 项目”。

自定义应用需从 Gemini 网页版添加；连接后可在网页版和手机应用中使用。Google 当前列出的条件包括：年满 18 岁、位于美国、使用个人 Google 账号、开启“活动记录”，且界面目前仅支持英文。若看不到“已连接的应用”或“自定义应用”，请查看 [Google 官方说明及可用条件](https://support.google.com/gemini/answer/17209137?hl=en)。

> aimcp 可读取和修改已注册项目中的文件并执行命令。只注册你信任并希望交给 Gemini 操作的项目；公网连接密码不要分享给他人。

---

# 多项目怎么用？

这是当前版本最重要的使用方式。

先区分两个概念：

- **注册项目（Registered Project）**：通过 Web Console、`aimcp project add` 或 `aimcp start` 注册的项目。一个 MCP 会话同一时间只绑定一个注册项目。
- **会话绑定（Conversation Binding）**：MCP 会话当前选择的注册项目；文件和命令工具只能在这个项目目录内运行。

项目注册由本机 Controller/CLI 完成；模型只通过 `project_control` 选择已经注册的项目，不会自行注册项目或扩大路径边界。

## 注册多个项目

假设电脑上有三个项目：

```text
~/code/api
~/code/web
~/code/mobile
```

分别进入目录运行：

```bash
cd ~/code/api
aimcp start

cd ~/code/web
aimcp start

cd ~/code/mobile
aimcp start
```

它们会全部注册到同一个 aimcp 后台服务。

不会创建三个端口，也不会创建三个 Tunnel。

查看所有项目：

```bash
aimcp project list
```

也可以显式注册指定目录：

```bash
aimcp project add /path/to/project
```

查看单个项目详情：

```bash
aimcp project info <项目 ID、项目名或目录>
```

---

## MCP 会话会绑定一个项目

一个 MCP 会话只操作一个项目。

例如你可以说：

> 使用 web 项目，看看首页现在有什么问题。

MCP 客户端会通过 `project_control` 选择对应项目，然后后面的文件读取、代码修改、命令执行和 Git 操作都会以这个项目为上下文。

另一个独立的 MCP 会话可以同时绑定 `api` 项目，互不影响。

如果要在当前对话切换项目，可以直接说：

> 切换到 api 项目。

切换已有绑定时需要明确确认，不会静默跳到另一个项目。

如果某些旧会话不再需要保留项目绑定，可以在 Web Console 的“项目”页面逐个或全部清除，也可以在终端运行：

```bash
aimcp bindings clean [项目]
```

终端会列出该项目的会话编号；只会清理你显式选中的绑定。清理不会删除客户端会话或项目文件，这些会话下次使用项目工具时需要重新选择项目。

---

## 停止一个项目

推荐使用：

```bash
aimcp project remove <项目 ID、项目名或目录>
```

如果当前终端就在项目目录，也可以省略目标：

```bash
aimcp project remove
```

这只会停用目标项目；后台服务、Cloudflare Tunnel 和其他项目仍然继续运行。重新启用时，再运行 `aimcp start` 或 `aimcp project add <目录>`。

---

## 停止或重启后台服务

停止：

```bash
aimcp stop
```

重启：

```bash
aimcp restart
```

`stop` 只关闭 MCP Runtime、项目运行态和 Cloudflare Tunnel，**Controller / Web Console 继续运行**，项目注册状态也会保留。`restart` 只重启当前 Runtime，并保持当前运行模式。

如果要把 aimcp 的 Controller 和 Runtime 都完全关闭：

```bash
aimcp shutdown
```

---

# MCP 客户端可以做什么？

连接项目以后，MCP 客户端可以通过 aimcp：

### 读取和搜索代码

- 读取单个或多个文件
- 搜索字符串和正则表达式
- 按文件模式查找文件
- 浏览目录
- 查找代码关系

### 修改代码

- 使用事务式 `apply_patch` 精确替换已有代码
- 批量创建、覆盖或删除文件
- 提交失败时自动回滚本次批量改动

### 执行命令

- 运行构建
- 运行测试
- 安装依赖
- 启动开发服务器
- 管理长时间运行的进程

### Git

- 通过 `exec_command` 使用项目现有的 Git CLI

### 项目切换

当你说：

> 继续这个项目。

或者：

> 先看看这个项目现在是什么情况。

客户端会先用 `project_control` 查看并绑定一个已注册项目，再通过精简工具集读取代码、Skills 和命令结果。一个 MCP 会话同一时间只绑定一个项目。

---

# 项目路径边界

所有文件工具和命令工作目录都限制在当前绑定项目的主目录内。

## 当前项目

运行：

```bash
cd ~/code/my-project
aimcp start
```

那么：

```text
~/code/my-project
```

就是这个项目的主工作区。

相对路径默认都从这里开始。

---

## 访问其他目录

需要处理另一个目录时，把它注册成独立项目：

```bash
aimcp project add /path/to/other-project
```

然后让 MCP 客户端使用 `project_control` 明确切换。工具不会通过绝对路径绕过当前项目边界。

> 路径限制不是完整的操作系统沙箱。项目内启动的 shell 命令仍然拥有当前系统用户本身拥有的系统权限。

---

# 使用 Codex、Claude Code 和 Skills

aimcp 可以直接读取已有 AI 开发工具的配置，而不是复制一份。

支持：

| 来源 | MCP | Skills |
|---|---:|---:|
| Codex | ✅ | ✅ |
| Claude Code | ✅ | ✅ |
| Agent Skills | — | ✅ |

常见位置包括：

```text
~/.codex/
~/.claude/
~/.agents/skills/
```

Claude Code 项目内的 `.claude/skills` 也可以按项目读取。

这些能力默认只是**读取和引用原配置**，不会把第三方 Token、MCP 配置和 Skill 文件复制到 `~/.codex-mcp`。

重新管理这些设置：

```bash
aimcp setup
```

然后选择：

```text
管理外部能力
```

支持两种同步方式：

- `watch`：配置发生变化后自动刷新，推荐
- `startup`：只在 aimcp 启动时读取一次

---

# 常用命令

| 命令 | 作用 |
|---|---|
| `aimcp` | 显示帮助，不隐式启动服务 |
| `aimcp open` | 启动/复用本机 Controller 并打开 Web Console；不启动 Runtime |
| `aimcp start` | 先注册当前项目，再按保存的模式启动/复用 MCP Runtime |
| `aimcp status` | 查看 Controller、MCP Runtime、默认运行模式、Tunnel 和所有项目 |
| `aimcp status --json` | 输出稳定的机器可读状态，其中包含本机 Web Console 地址 |
| `http://127.0.0.1:<Controller端口>/` | 打开完整本机 Web Console；可执行 CLI 的用户级操作 |
| `aimcp restart` | 重启 MCP Runtime，保留 Controller 和项目注册状态 |
| `aimcp stop` | 停止 MCP Runtime 和 Tunnel；Controller / Web Console 保持在线 |
| `aimcp shutdown` | 完全关闭 MCP Runtime 和 Controller / Web Console |
| `aimcp project list` | 查看已注册项目 |
| `aimcp project add [目录]` | 只注册项目，默认当前目录；不会启动 Runtime |
| `aimcp project remove [项目]` | 停用项目，默认当前目录 |
| `aimcp project info [项目]` | 查看项目详情 |
| `aimcp bindings clean [项目]` | 交互清理指定项目的旧会话绑定，默认当前项目 |
| `aimcp logs [--lines N]` | 查看最近运行日志 |
| `aimcp logs -f` | 持续跟随运行日志 |
| `aimcp setup` | 首次设置或管理现有配置 |
| `aimcp doctor` | 只读检查安装、配置和依赖 |
| `aimcp doctor --fix` | 恢复缺失的文件搜索组件、创建本机目录、清理失效 daemon 状态等安全修复 |
| `aimcp auth` | 修改远程 MCP 连接密码 |
| `aimcp update` | 更新到最新版本 |
| `aimcp start --root <目录>` | 注册指定目录，而不是当前目录 |
| `aimcp start --local` | 显式切换并保存为本机模式，不开放公网 |
| `aimcp start --public` | 显式切换并保存为公网模式；需要先配置公网连接和密码 |
| `aimcp start --no-tunnel` | 公网模式下不自动启动 Cloudflare Tunnel |
| `aimcp start --tunnel-logs` | 把 Tunnel 日志同时输出到运行日志 |
| `aimcp --version` | 查看版本 |
| `aimcp help` | 查看帮助 |

---

# 再次运行 setup 会发生什么？

已经完成首次配置后，再运行：

```bash
aimcp setup
```

不会重新走一遍所有步骤。

你可以选择：

- 检查当前配置
- 修改公网连接
- 重新登录 / 切换 Cloudflare 账号
- 修改连接密码
- 管理 Codex / Claude Code / Agent Skills
- 退出，不做修改

“检查当前配置”会真实验证公网地址是否能够连接回当前电脑，而不只是检查配置文件是否存在。
这个检查只读取已提交配置和运行状态，不会登录 Cloudflare、修改 DNS 或重写 Tunnel 配置。

修改公网连接时，如果后台服务正在运行，setup 会先保留它的完整运行参数和所有项目注册，安全停止后完成切换，再按原参数恢复。多项目和会话绑定文件不会被重置。

---

# 配置保存在哪里？

aimcp 的用户数据默认保存在：

目录名沿用旧版，以便现有项目、连接密码和 Tunnel 配置在升级后继续使用。

```text
~/.codex-mcp/
```

主要文件包括：

```text
~/.codex-mcp/config.json
~/.codex-mcp/controller.json
~/.codex-mcp/daemon.json
~/.codex-mcp/projects.json
~/.codex-mcp/session-bindings.json
~/.codex-mcp/logs/
```

其中：

- `config.json`：监听地址、公网连接、外部能力、客户端工具策略和 UI 设置
- `controller.json`：仅本机 Controller 的 PID、loopback 端口和随机控制凭据；Web Console 由它提供
- `daemon.json`：当前 MCP Runtime 状态；执行 `stop` 后会移除，而 Controller 继续运行
- `projects.json`：注册过的项目
- `session-bindings.json`：MCP 会话和项目的绑定关系

Cloudflare 的登录和 Tunnel 凭据由 aimcp 放在自己的配置目录中管理，不依赖系统级 `~/.cloudflared` 作为长期运行状态。

---

# 日志

运行日志位于：

```text
~/.codex-mcp/logs/
```

结构化日志文件类似：

```text
codex-mcp.2026-08-12.0.jsonl
```

Cloudflare Tunnel 原始日志：

```text
~/.codex-mcp/logs/tunnel.log
```

正常的工具日志不会记录：

- 原始命令内容
- 文件内容
- 工具返回的完整内容
- OAuth 凭据

它主要记录工具名、耗时、结果状态等运行信息。

如果遇到启动、Tunnel 或 MCP 连接问题，首先查看这里。

---

# 检查问题

运行：

```bash
aimcp doctor
```

它会检查：

- Node.js 版本
- Git
- 文件搜索组件
- aimcp 配置
- 连接密码
- 公网地址
- cloudflared
- Cloudflare 登录
- Tunnel 凭据
- Tunnel 配置文件
- 外部能力设置

这是排查问题时最先应该运行的命令。

如果文件搜索组件缺失，可以直接运行：

```bash
aimcp doctor --fix
```

它会下载项目固定版本的受管 ripgrep，校验 SHA-256，并在安装后重新验证版本；不需要重新执行整套安装脚本。

---

# 常见问题

## `aimcp` 命令找不到

重新打开终端后再试。

如果仍然找不到，重新运行安装脚本。

---

## ChatGPT 连接不上

先运行：

```bash
aimcp status
aimcp doctor
```

确认：

- 后台服务正在运行
- 公网连接已启动
- 公网地址正确
- Tunnel 没有报错

再查看：

```text
~/.codex-mcp/logs/
```

---

## 忘记连接密码

密码明文无法找回。

重新设置：

```bash
aimcp auth
```

---

## Cloudflare 登录错了账号

运行：

```bash
aimcp setup
```

选择：

```text
重新登录 / 切换 Cloudflare 账号
```

aimcp 会在临时目录完成新登录并验证凭据，然后才替换自己管理的登录；取消或登录失败时旧凭据保持不变。它不会修改系统级 `~/.cloudflared`。

---

## Cloudflare 上有旧 Tunnel，配置对不上

重新运行：

```bash
aimcp setup
```

aimcp 会检查本机 Tunnel 凭据和 Cloudflare 上的 Tunnel 是否匹配。

如果发现同名 Tunnel 但本机没有可用凭据，不会删除远端 Tunnel，而是创建带唯一后缀的 candidate。只有本次新建、配置尚未提交且没有被 DNS 引用的 candidate 才会自动清理。

---

## Tunnel 一直连接不上

查看：

```text
~/.codex-mcp/logs/tunnel.log
```

某些网络或防火墙会阻止 Cloudflare Tunnel 使用的 TCP 7844 连接。

当前版本会优先使用 IPv4，并在连接超时时给出更具体的错误提示。

---

## ChatGPT 看不到新的精简工具列表

先在 ChatGPT 的 MCP / App 设置中执行 Refresh，或者重新发布 / 重新连接当前 MCP App。

工具 ABI 已精简为固定的 15 个入口。旧的 ChatGPT action snapshot 不再兼容已删除的工具，因此升级后必须让 ChatGPT 重新扫描工具。

---

## 我需要每个项目启动一个 aimcp 吗？

不需要。

每个项目只需要运行一次：

```bash
aimcp start
```

用来把它注册到同一个后台服务。

真正运行的 MCP server 和 Cloudflare Tunnel 都只有一套。

---

## 关闭终端以后 aimcp 会停吗？

默认不会。

正常的 `aimcp start` 会启动后台守护进程，终端命令完成后服务继续运行。

查看：

```bash
aimcp status
```

停止后台服务：

```bash
aimcp stop
```

---

# 更新

## 1.0 干净基线

1.0 是一次 breaking release，不读取旧版命令、旧版配置字段或旧 OAuth 状态。升级前请用已安装的旧版 CLI 停止服务，备份 `~/.codex-mcp`，再移走其中的 `config.json`、`oauth-state.json`、`daemon.json`、`projects.json` 和 `session-bindings.json`，然后重新运行：

```bash
aimcp setup
```

请保留托管组件、连接密码和 Cloudflare 凭据。重新 setup 会选择新的已提交配置；旧 OAuth 会话与项目绑定不会恢复，项目需要重新注册。不要删除整个 `~/.codex-mcp`，其中保存 aimcp 的本机配置和连接数据。

旧的 `tunnel`、`exit` 和 `serve --foreground` 入口已删除；分别使用 `setup`、`stop` / `project remove` 和后台 `start`。

```bash
aimcp update
```

1.0 之后的常规更新会保留配置和连接密码；从旧版首次升级仍须完成上面的基线重置。

更新后运行：

```bash
aimcp restart
```

这样可以确保正在运行的 daemon 使用当前 CLI 版本。`aimcp status` 会同时显示 CLI 和 daemon 版本；如果两者不一致，会直接提示重启。

---

# 卸载

如果是通过本项目的 `npm link` 安装的：

```bash
npm unlink -g @rookiedj/aimcp
```

此操作只移除全局命令，不会删除用户配置和连接密码。

如果你确定不再使用，并希望彻底删除所有状态，可以再手动删除：

```text
~/.codex-mcp
```

---

# 安全说明

aimcp 的目标不是做一个强隔离沙箱，而是让受信任的 MCP 客户端可以在个人开发环境中完成开发工作。

因此请注意：

1. **不要把自己的 aimcp 实例分享给其他人。**
2. **不要把连接密码公开。**
3. **只注册你信任的项目目录。**
4. **执行 shell 命令时，命令仍拥有当前系统用户本身的权限。**
5. **如果电脑上保存了生产环境密钥、SSH Key 或其他敏感文件，请按照正常本机开发安全标准管理它们。**

公网 MCP 入口需要连接密码认证，但它不能替代操作系统级隔离。

---

# 高级说明：ChatGPT 工具列表兼容

正常情况下你不需要关心这一节。

ChatGPT 有时会缓存已经批准过的 MCP action 列表。当前工具 ABI 是固定的 15 个入口，升级后请在 ChatGPT 中 Refresh MCP App 或重新发布连接，让旧的 action snapshot 被完整替换。项目选择统一使用 `project_control`，其他已删除工具没有兼容别名。

---

# 本地开发

克隆项目后：

```bash
npm ci
npm run typecheck
npm run build
```

开发模式：

```bash
npm run dev
```

只在本机调试：

```bash
npm run dev:once -- --local
```

发布版本要求 Node.js 22。日常 CI 和发版验收都会在 Linux、macOS、Windows 上运行类型检查、完整测试和真实 tarball 隔离安装 smoke；发布流程只分发已经通过 smoke 的同一个 tarball artifact。

---

# License

[MIT](LICENSE)