aimcp

让 ChatGPT、Google Gemini CLI 或 Gemini 网页端 通过 MCP 协议，安全操作你电脑上的代码项目。

在日常开发对话中，你可以直接告诉 AI：

• 💬 “帮我看看当前项目是做什么的”

• 💬 “检查一下 git 状态，现在有哪些未提交改动”

• 💬 “修掉这个报错，并跑一下单元测试”

• 💬 “把这个功能实现完，然后切到 api 项目继续”

aimcp 会在你的电脑上受控地读取文件、修改代码、执行构建与测试命令，并把结果实时返回给 AI。

📌 目录

• 架构拓扑图

• 模式选择指南

• 快速开始

  • 步骤 1：全局安装

  • 步骤 2：启动管理控制台

  • 步骤 3：接入 AI 客户端

• 多项目隔离工作流

• 精简 15 工具矩阵

• 常用命令速查

• 外部能力导入 (Codex / Skills)

• 故障排查与自愈决策树

• 本地开发

• 安全说明

Related MCP server: codex-session-gateway

🗺️ 架构拓扑图

aimcp 将控制面与运行时彻底解耦。多个工程目录、多个对话窗口，统一由一个轻量级后台守护进程提供服务：

┌─────────────────────────────────────────────────────────────────────────┐
│                           🤖 AI 模型客户端                              │
│       Gemini CLI / Codex CLI              ChatGPT / Gemini 网页端       │
└────────────────────┬────────────────────────────────────┬───────────────┘
                     │ [纯本地 HTTP 直连]                  │ [安全 HTTPS 隧道]
                     ▼                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                     🌐 接入与认证层 (Ingress & Auth)                    │
│      127.0.0.1:3920/mcp (免密)              Cloudflare Tunnel + OAuth   │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    ⚙️ aimcp 后台服务 (Daemon Core)                      │
│   • Web Console 图形控制台              • 会话项目路由器 (Router)       │
│   • 运行状态诊断 (aimcp doctor)         • 15 个受控原子工具引擎         │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ 会话级严格路径锁定
             ┌───────────────────────┼───────────────────────┐
             ▼                       ▼                       ▼
      ┌─────────────┐         ┌─────────────┐         ┌─────────────┐
      │  前端工程 A  │         │  后端工程 B  │         │ 移动端工程 C │
      │ ~/code/web  │         │ ~/code/api  │         │ ~/code/app  │
      └─────────────┘         └─────────────┘         └─────────────┘
      ▲ 读写、搜索、测试命令严格限制在对应目录内，防止上下文串扰与路径越界 ▲

🧭 模式选择指南（本机模式 vs 公网模式）

无需纠结网络配置，根据你的客户端快速选择：

🚀 快速开始

步骤 1：全局安装

系统环境要求：Node.js 22 或更高版本。

npm install --global @rookiedj/aimcp
aimcp --version

步骤 2：启动管理控制台（推荐）

打开图形化 Web 控制台：

aimcp open

控制台将在本地浏览器打开（http://127.0.0.1:3921）：

1. 添加项目：选择并登记你要操作的代码工程目录。

2. 选择启动模式：根据需求点击“仅本机”或“公网接入”。

3. 获取连接：启动后，一键复制当前生成的 MCP 服务地址。

步骤 3：接入 AI 客户端

Gemini CLI 运行在同一台电脑上，直接走本地回环，速度最快、稳定性最高：

1. 在代码目录启动服务（默认端口 3920）：

   cd /path/to/your-project
   aimcp start --local

2. 注册到 Gemini CLI 配置：

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

3. 验证连接：

   gemini mcp list

   看到显示 Connected 后，重启 Gemini CLI，在会话中输入 /mcp 即可看到所有可用工具。详见 Gemini CLI MCP 官方说明。

Google Gemini 网页端（gemini.google.com）运行在云端，需要一个安全的公网 HTTPS 入口：

1. 配置公网与连接密码（首次使用配置一次即可）：

   aimcp setup

   跟随向导完成 Cloudflare 自动配置（只需已有 Cloudflare 托管域名）或填入自定义反向代理域名，并生成连接密码。

2. 以公网模式启动：

   aimcp start --public
   aimcp status   # 复制输出的公网地址，例如：https://aimcp.your-domain.com/mcp

3. 在 Gemini 网页端添加应用：

   • 打开 Gemini 网页版，进入 设置 → 个性化智能服务 → 已连接的应用。

   • 在“自定义应用”中点击添加，粘贴公网 MCP 地址。

   • 在弹出的授权页面中输入连接密码完成授权。

   • 回到对话，输入 @aimcp 即可指派 AI 读写本地项目！

Spark 的两类授权提示：

• 聊天里的 Allow 是 Gemini 对自定义 MCP 写操作的手动确认，项目绑定不等于允许后续所有修改。参见 Google 官方说明。aimcp 不能替客户端关闭确认，也不会将写操作标成只读。

• aimcp 登录页要求连接密码属于 OAuth 授权。切换项目不会撤销令牌；访问令牌有效期为 15 分钟，客户端应使用刷新令牌续期。刷新请求未带 resource 时仍严格绑定当前 MCP 地址；换地址、修改连接密码、撤销授权或刷新令牌重放会导致授权失效。反复出现 401 时，在 aimcp doctor 中查看令牌交换/续期阶段与错误类别，无需发送密码或令牌。

• 临时断网、DNS 故障、客户端元数据或公钥服务暂时不可用时，令牌端点返回可重试的 503 server_error 和 Retry-After，保留已有授权。请求在令牌交换开始前断开也不会消耗令牌。若刷新已经提交，但响应在网络中丢失，再使用旧刷新令牌仍会触发重放保护；此时可能需要重新连接，服务端不能保证客户端自动恢复。

1. 确保以公网模式运行：aimcp start --public。

2. 在 ChatGPT 账号设置中启用 Developer Mode（开发者模式）。

3. 进入 Apps → Create，填入你的公网 MCP 地址（如 https://aimcp.your-domain.com/mcp）。

4. 点击扫描工具（Scan Tools），按提示输入之前生成的连接密码完成 OAuth 验证并保存。

aimcp start --local
codex mcp add aimcp --url http://127.0.0.1:3920/mcp
codex mcp list

🗂️ 多项目隔离工作流

aimcp 支持一台电脑托管多个项目，无需为每个项目开辟新端口或新服务：

┌─────────────────────────────────────────────────────────────┐
│                  同一个 aimcp 后台服务 (Port: 3920)           │
└──────────────────────────────┬──────────────────────────────┘
                               │ 会话级严格目录隔离
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
   ┌───────────┐         ┌───────────┐         ┌───────────┐
   │ 对话会话 1 │         │ 对话会话 2 │         │ 对话会话 3 │
   │ 绑定目录:   │         │ 绑定目录:   │         │ 绑定目录:   │
   │ ~/code/web│         │ ~/code/api│         │ ~/code/app│
   └───────────┘         └───────────┘         └───────────┘

项目操作口令：

1. 登记项目：进入不同目录分别执行 aimcp start，或执行 aimcp project add /path/to/project。

2. 对话内选择：初次对话时 AI 会调用 project_control 询问要操作哪个工程，你只需说：“使用 web 项目”。

3. 中途切换：直接说：“切换到 api 项目继续”，AI 即可平滑换绑上下文。

上下文压缩与摘要恢复

Gemini CLI 原生压缩

Gemini CLI 原生支持自动上下文压缩，默认 model.compressionThreshold=0.5。在本机控制台的 系统 → 上下文与摘要 设置触发比例；保存只修改 ~/.gemini/settings.json 的该字段，保留其他配置和 JSONC 注释，重启 Gemini CLI 后加载。项目和系统设置可能覆盖用户设置，因此面板显示的是用户级阈值，不代表所有正在运行的 CLI 都已采用它。配置被外部修改时会拒绝覆盖，需重新读取。

在 Gemini CLI 聊天中可输入 /compress 手动压缩；这是 CLI 命令，不能作为 shell 或 MCP 工具执行。自动压缩由 CLI 判断真实上下文用量并调用模型完成。参见 Gemini CLI 配置。

Gemini App / ChatGPT 摘要检查点

目前未找到 Gemini App 提供的、可由 MCP 调用的上下文压缩接口。aimcp 提供客户端主动发送的任务摘要检查点，不清空 App 的上下文，也不保证客户端会遵循提醒。

1. 在 项目 → 本地会话记录 开启保存（默认关闭）。关闭时不新增摘要，MCP 也不读取已保存的检查点；重新开启不补录关闭期间内容。

2. 保留 project_control(select) 返回的 project_session。后续成功的工具结果也会附上当前项目和句柄，避免只依赖聊天最开始的绑定消息；绑定与本地聊天保存开关独立。整理上下文时保留句柄，恢复时先调用 project_control(action=current) 核对项目。连续 20 次成功的非 project_control 调用，或累计约 64 KB MCP 结果，会提醒客户端保存。统计只在内存中保留，不是模型 token 用量。

3. 客户端生成精简摘要（任务目标、约束、关键决定、改动与验证结果、下一步），调用：

   {
     "action": "checkpoint",
     "project_session": "当前会话的句柄",
     "purpose": "保存任务摘要",
     "checkpoint": {
       "id": "checkpoint-1",
       "previous_id": null,
       "summary": "已完成的工作和必须保留的任务状态",
       "next_steps": ["核对当前文件后继续未完成工作"]
     }
   }

4. 重连或上下文丢失后，携带同一会话的句柄调用 project_control(action=restore)。只读取当前会话、当前项目的最新检查点；不会自动授权、恢复绑定或读取其他聊天。更新时使用新 id 和上一份的 previous_id，防止旧请求覆盖新摘要。失效句柄需重新选择用户确认的项目，不能借用其他会话。

5. 本地会话详情可查看摘要，也可手动复制给新的聊天。摘要按历史任务数据处理，恢复后重新核对文件、权限和状态；不包含隐藏推理、系统提示、密码或密钥。

如果 Gemini 遗忘了句柄，先从当前聊天近期工具结果找回；如果句柄和稳定的聊天标识都丢失，需要用户确认项目后重新选择。新绑定可以继续操作代码，但不会自动继承旧聊天的摘要；可由用户在本地详情中查看并提供原摘要。服务端不会仅凭同一账号、只有一个项目或“最近使用”来猜测绑定，也不能保证 Gemini 的上下文压缩保留所有工具结果。

检查点与聊天记录共用 ~/.ai-mcp/conversations/ 私有文件（POSIX 权限 0600），按会话、客户端、项目隔离；每项目只保留最新摘要，最多 8,000 字符、32 KB，最多 8 条下一步。删除会话记录会同时删除摘要。内容由客户端提供，可能包含项目隐私，以明文保存；npm 包不会包含本机记录。

客户端未提供标题时，会话列表显示“客户端 · 首次使用项目 · 会话短编号”，不会从聊天内容提取名称。开启本地保存后，客户端可在 select、record 或 checkpoint 时提供简短的 title；也可在本地列表中重命名，手动名称优先保留。这不会修改 Gemini / ChatGPT 聊天窗口的标题，也不能自动读取其原始标题。

🛠️ 精简 15 工具矩阵

为避免大模型在几十上百个琐碎工具中产生调用幻觉，aimcp 精选并收敛了 15 个高内聚工具：

📋 常用命令速查

🧩 外部能力与 Skills 导入

aimcp 可以无缝复用你本地已有 AI 工具的配置与技能，无需重复拷贝：

~/.gemini/settings.json ──┐
~/.codex/ ───────────────┼──► [aimcp 自动探测与只读加载] ──► 统一供给当前对话
~/.claude/ ──────────────┤
~/.agents/skills/ ───────┘

• 只读引用安全：只读取并加载外部工具与 Skills 配置，绝不会将你的第三方 Token 与私有密钥写入公网或复制到 ~/.ai-mcp。

• 动态热更新：支持 watch 监听模式，当外部技能文件修改后，aimcp 会自动刷新能力清单。

❓ 故障排查与自愈决策树

遇到问题时，可按下面的决策树快速自愈：

遇到连接或运行异常？
        │
        ▼
   执行 aimcp doctor
        │
        ├─► 报告“组件缺失” (如 ripgrep)？
        │     └─► 运行 aimcp doctor --fix 自动下载恢复
        │
        ├─► 客户端频繁“断开连接”或网络超时？
        │     ├─► 本机客户端 (Gemini CLI) ──► 优先用 aimcp start --local 回环直连
        │     ├─► 桌面端沙盒拦截 ──► 检查是否已将项目目录加入 Connected Folders
        │     └─► 代码刚更新 ──► 运行 aimcp restart 重启后台生效
        │
        ├─► 提示“密码错误或忘记密码”？
        │     └─► 运行 aimcp auth 重新设置连接密码
        │
        └─► 仍有未知报错？
              └─► 运行 aimcp logs -f 查看实时运行日志与报错堆栈

💻 本地开发

# 1. 克隆代码仓库
git clone https://github.com/rookieDJ/aimcp.git
cd aimcp

# 2. 安装依赖并构建
npm ci
npm run typecheck
npm run build

# 3. 本机快速启动调试
npm run start:local

🔒 安全说明

📄 License

MIT