Skip to main content
Glama

agy-codex-mcp · SideDesk 副席 (v0.1.0)

基于 Google Antigravity 原生 MCP App (aux_pane) 规范构建的轻量级右侧 1v1 副工位插件。支持接入本机官方 OpenAI Codex CLI 或任意标准 OpenAI 兼容 HTTP API(DeepSeek / OpenRouter / SiliconFlow / 本地 Ollama 等),默认在物理隔离的影子副本中执行文件修改,经红绿 Unified Diff 审阅确认后再安全写回原目录。


写在前面(怨念动机与叠甲声明)

  1. 最核心的动手动力——纯粹是被 GPT / Codex 折磨出来的怨念: 说实话,做这玩意最大的动力就是被原生 GPT / Codex 客户端气笑了:

    • 日常只是随口聊一句讨论思路,它非得犯“工科助手病”先把项目目录扫个底朝天、列一串 1-2-3 计划才肯说话;

    • 聊过五六轮之后注意力就开始飘,之前千叮咛万嘱咐的规矩和语气忘得一干二净;

    • 后台塞一堆默认杂项导致冷启动慢半拍,高思考档憋半天黑盒不吐字(分不清是在思考还是卡死了),放进真工程目录里又怕它抽风乱改代码拆家没地方吃后悔药;

    • 偏偏它的后端挑刺和写码硬实力又确实弃之可惜,弃用吧亏了订阅费,硬用吧血压高。于是干脆自己动手给它修了个**「默认关在影子副本小黑屋干活 + 验完红绿 Diff 才准落盘 + 定期强刷设定防失忆 + 随时两连点急停断电」**的带笼子副工位。

  2. 关于思路参考与为什么要从零走原生重构(防封号求生欲): 作者本人只是平时折腾 AI 辅助写码的业余小白(非科班大牛),早期也用过并参考过社区里一些多角色工作台、侧边面板与本地 MCP 桥接工具的交互设计。但因为在外部第三方壳子里反代、抓包或套壳拉起编辑器的内置 CLI / 订阅登录态极易违反平台服务条款(ToS)导致封号(而且多开群聊纯属白烧额度),实在害怕折腾外部 CLI 套壳把号搞没了,干脆在 AI 辅助下,100% 遵循 Antigravity 官方文档公开的原生 MCP App 规范,从头手搓重构了这个只保留 1v1 侧边单聊 + 影子隔离验收 的极简自用版。

  3. 版本说明(v0.1.0 早期自用版): 本项目目前仅为个人泄愤(划掉)学习与日常自用的早期探索版本(v0.1.0),代码全部基于 Node.js 与 @modelcontextprotocol/ext-apps 独立编写,肯定还有很多粗糙和不完善之处,放出来纯粹给同样被折腾得够呛的同好做个参考,大佬轻喷。


Related MCP server: agy-mcp

核心功能

  • 双引擎驱动(零反代、零套壳)

    • 本机 Codex CLI:自动检测系统已安装的官方 codex(含 Windows 微软商店版或全局 CLI),直接复用本机官方客户端登录态,支持动态读取模型推理档位(low ~ ultra)、service_tier="fast" 加速开关与 --ignore-user-config 纯净启动。

    • 通用 OpenAI 兼容 API:支持自定义 Base URL、API Key 与模型名(内置常用平台快捷填充),兼容流式输出与 reasoning_content 思考链折叠,并内置锁死在工作区内的轻量文件读写工具循环。

  • 影子副本隔离与一键后悔药

    • 默认在 ${PLUGIN_DATA}/shadows/ 独立副本内执行修改(超 5,000 文件或 200 MB 自动熔断保护,自动跳过 .git / node_modules / .venv 等重目录)。

    • 在「待验收」页逐文件查看红绿 Unified Diff,支持冲突检测、自动快照备份写回、一键字节级撤销上次应用 与丢弃副本。

  • 三组直观权限胶囊 & 可选 Turbo 直通档

    • 提供「文件范围(只读 / 影子隔离 / 原目录不限)」「执行命令(自动 / 禁止)」「联网(允许 / 禁止)」分段开关;处理超大目录或需直接调用本机完整依赖跑测试时可手动切至 Turbo 直通,并配有两段式防误触全局急停开关。

  • 清爽 1v1 独立单聊工位

    • 支持多张自定义角色卡、长期记忆开关、长对话定期设定同步(防多轮后遗忘设定)、图片附件发送、话题改名/导出 Markdown/压缩摘要继承开新话题,以及浅色羊皮纸 / 深色暖炭双主题切换。

    • 零额外请求开销读取本地会话日志中的配额剩余百分比与当前话题上下文窗口水位提示。


安装与使用

环境要求

  • Google Antigravity(支持 MCP Apps aux_pane)

  • Node.js >= 20

  • Git(用于影子副本内部生成标准 Unified Diff)

  • (可选)若使用 Codex CLI 模式,需先在本机安装并完成一次官方 codex 登录。

1. 克隆到 Antigravity 插件目录

Windows (PowerShell):

git clone https://github.com/Yuansamas3/agy-codex-mcp.git "$HOME\.gemini\config\plugins\agy-codex-mcp"
cd "$HOME\.gemini\config\plugins\agy-codex-mcp"
npm install

macOS / Linux:

git clone https://github.com/Yuansamas3/agy-codex-mcp.git ~/.gemini/config/plugins/agy-codex-mcp
cd ~/.gemini/config/plugins/agy-codex-mcp
chmod +x bin/launch.sh
npm install

macOS / Linux 启动配置提示:仓库默认 mcp_config.json 配置了 Windows 启动脚本 cmd /d /c ${PLUGIN_ROOT}/bin/launch.cmd。在 macOS / Linux 下只需将 mcp_config.json 改为:

{
  "mcpServers": {
    "sidedesk": {
      "command": "/bin/sh",
      "args": ["${PLUGIN_ROOT}/bin/launch.sh", "--data_dir=${PLUGIN_DATA}"]
    }
  }
}

2. 打开面板

安装依赖后,在 Antigravity 的 MCP Servers 设置中刷新/重启 agy-codex-mcp_sidedesk,或直接在主对话中输入:

打开 SideDesk 副席面板

即可在对话右侧辅助栏呼出工位面板。

(小贴士:如果不希望影子副本占用系统盘空间,可将插件目录与 ~/.gemini/antigravity/plugin_data/agy-codex-mcp 通过系统目录联接 Junction / 软链接指向其他大容量磁盘分区。)


开发与自检脚本

# 重新打包单文件前端 (app/dist/app.html)
npm run build:app

# 运行后端与安全边界端到端测试
npm run test:e2e

# 运行无头浏览器 360px 窄栏布局与严格 CSP 校验
npm run verify:app

安全与合规免责声明 (Disclaimer)

  1. 合规边界:本插件仅在 Antigravity 官方公开的本地 MCP App 扩展机制内运行,绝不反代、截获、提取或包装 Antigravity (agy) 或任何第三方客户端的私有 OAuth 凭据与登录令牌。

  2. 数据与密钥安全:所有会话状态、影子副本与用户自行填写的第三方 API Key 均仅保存在用户本机 ${PLUGIN_DATA} 目录中(无任何外部遥测或上传);API Key 对主对话侧模型(Model Tools)完全隔离不可见,前端界面亦仅回显脱敏掩码。

  3. 风险自担:开启「原目录不限(Turbo 直通)」模式后,底层引擎将直接在目标真实目录执行读写与命令而不再经过影子副本隔离,请务必在版本控制(Git)保护或充分确认风险的前提下谨慎使用。本项目按 MIT 协议“原样(AS IS)”提供,作者不对使用过程中产生的任何代码改动、配额消耗或数据损失承担责任。


License

MIT

Available Tools

30 tools
app_abort_jobUI 中止任务B

UI 专用:强杀运行中的 Codex 进程树或中断 API 流式请求。

Inputs: jobId (required), reason.

app_apply_shadow应用影子副本到原目录B

UI 专用:冲突预检 → 自动快照备份原文件 → 应用改动到原工程目录。

Inputs: shadowId (required), force.

app_boss_send副席工位直聊发送C

UI 专用:用户在副席直接给当前人物卡发消息(<50ms 瞬时异步启动,支持三组权限胶囊与图片附件)。

Inputs: prompt (required), sourceDir (required), model, title, +7 more.

app_clear_inherited_summary解绑当前话题继承摘要A

UI 专用:移除当前话题的 inheritedSummary,后续轮次不再注入前序摘要。

Inputs: sessionId (required).

app_clear_session清空话题消息B

UI 专用:清空指定话题的对话记录并重置线程。

Inputs: sessionId (required).

app_compress_session原地压缩话题上下文B

UI 专用:将指定话题压缩为摘要、重置底层长线程并将摘要挂载到当前话题顶部继续。

Inputs: sessionId (required), summarizerPersonaId.

app_delete_persona删除人物卡B

UI 专用:删除指定人物卡。

Inputs: id (required).

app_delete_session删除话题A

UI 专用:永久删除指定归档或当前话题记录。

Inputs: sessionId (required).

app_discard_shadow丢弃影子副本B

UI 专用:删除影子副本及其未应用的改动,不触碰原目录。

Inputs: shadowId (required).

app_emergency_trip全局急停熔断开关A

UI 专用:一次性强杀所有会话运行中的 Codex 进程树与在途 API 请求(绝不重发),并将在途全局 Turbo 直通安全降级回影子隔离。

Inputs: reason.

app_export_session导出话题为 MarkdownA

UI 专用:导出指定话题完整记录为 .md 文件并返回内容与保存路径。

Inputs: sessionId (required).

app_get_diff获取影子副本红绿 DiffB

UI 专用:按需计算并拉取指定影子副本的完整文件变更与红绿 Unified Diff。

Inputs: shadowId (required).

app_get_state获取副席面板状态B

UI 专用:拉取脱敏后的人物卡、会话、实时任务流、待验收影子副本与可撤销备份。

Inputs: personaId, sessionId.

app_new_session开启新副席话题B

UI 专用:为指定人物卡与工程目录开启全新话题(旧话题保留归档),可选继承压缩上下文摘要(已有新鲜摘要时零额度复用)。

Inputs: personaId (required), sourceDir (required), title, inheritSummary, +2 more.

app_paste_clipboard_image从系统剪贴板粘贴图片A

UI 专用:读取系统剪贴板中的位图截图或复制的图片文件,供头像裁剪或聊天附图使用。

Inputs: mode.

app_refresh_quota刷新本地 Codex 配额与上下文快照B

UI 专用:零网络开销重新扫描本机 ~/.codex/sessions 最新 token_count 快照,并同步当前话题上下文水位。

Inputs: sessionId.

app_rename_session重命名话题B

UI 专用:修改指定话题的标题。

Inputs: title (required), sessionId (required).

app_save_default_permissions保存全局默认权限B

UI 专用:保存三组全局默认权限胶囊(fileScope / commandPolicy / networkPolicy)。

Inputs: fileScope, commandPolicy, networkPolicy.

app_save_draft保存未发送草稿B

UI 专用:实时把输入框草稿与目标路径持久化到后端,防收起面板丢失。

Inputs: key, text, sourceDir.

app_save_persona保存人物卡B

UI 专用:新增或编辑人物卡(支持 Codex CLI 与 OpenAI 兼容 API,返回脱敏结构)。

Inputs: name (required), id, role, model, +16 more.

app_save_user_profile保存用户个人资料A

UI 专用:保存用户的称呼、头像与外观主题偏好到插件持久化目录;自定义称呼将自动注入双引擎指令。

Inputs: userName, themeMode, userAvatar.

app_set_theme切换外观主题A

UI 专用:轻量持久化外观主题模式(auto 跟随宿主 / light 浅色羊皮纸 / dark 深色暖炭),防关面板丢失。

Inputs: themeMode (required).

app_test_provider测试引擎连接或重新检测 CodexB

UI 专用:provider=codex-cli 时异步重新探测本机 codex.exe;provider=openai-compatible 时向 Base URL 发最小化探测请求返回延迟或错误。

Inputs: model, apiKey, baseUrl, provider, +3 more.

app_undo_last_apply撤销上次应用B

UI 专用:按备份快照精确还原修改/删除的原文件,并清理该轮新增文件。

Inputs: backupId, sourceDir.

app_update_inherited_summary更新当前话题继承摘要文本C

UI 专用:允许用户直接微调当前话题顶部的继承摘要内容。

Inputs: summary (required), sessionId (required).

sidedesk_abort_job中止运行中的副席任务A

立即中止运行中的 Codex 进程树或 OpenAI API 流式请求,并将任务标记为 aborted(绝不自动重发)。

Inputs: jobId (required), reason.

sidedesk_dispatch向 SideDesk 人物卡派单A

将后端分析、审计或编码任务派发给 SideDesk 副席中的指定人物卡(自动按人物卡驱动路由至本机 Codex CLI 或 OpenAI 兼容 API)。默认必须在隔离影子副本中执行(read-only / workspace-write),原工程目录零修改;仅当用户明确要求 Turbo / 直接改原目录,或目标人物卡默认权限为 turbo-direct 时,才允许使用 turbo-direct(跳过影子副本与容量熔断,直接在原目录无沙箱执行)。

Inputs: prompt (required), sourceDir (required), model, title, +6 more.

sidedesk_job_status查询副席任务进度与结果A

查询指定 jobId 的运行状态、实时进度、影子副本改动摘要、源目录完整性校验与最终回复。可配合 waitSeconds 优雅等待。

Inputs: jobId (required), waitSeconds.

sidedesk_list_personas列出副席人物卡A

列出 SideDesk 中配置的所有人物卡(含驱动引擎类型、模型与权限),绝不返回任何密钥。

Inputs: no named parameters.

sidedesk_openSideDesk · 副席A

打开或刷新右侧 SideDesk · 副席面板,查看双引擎人物卡、运行中任务与待验收的影子副本 Diff。支持空参数调用。

Inputs: sessionId.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 30 tools

    Disambiguation3/5

    The tool set is split into an agent-facing sidedesk_* group and a UI-facing app_* group, and the descriptions do a reasonable job explaining that separation. But several pairs overlap in practice: sidedesk_abort_job vs app_abort_job, sidedesk_dispatch vs app_boss_send, sidedesk_job_status vs app_get_state, and app_undo_last_apply vs app_discard_shadow. An agent must read the descriptions carefully to avoid picking the UI-only twin of an operation it needs.

    Naming Consistency3/5

    Names are snake_case and carry clear sidedesk_/app_ prefixes, but they mix verb_noun forms (app_get_diff, app_save_persona) with noun_verb and imperative outliers (app_boss_send, app_emergency_trip, app_apply_shadow, sidedesk_dispatch). It's readable, but there's no single predictable pattern to infer a tool's name.

    Tool Count2/5

    30 tools is too heavy for this surface, and about 25 of them are single-purpose UI micro-operations (theme, draft, inherited summary edits). Many could be folded into coarser actions without losing capability.

    Completeness4/5

    Coverage of the domain is strong: persona CRUD and test, session lifecycle (new/rename/compress/clear/delete/export), shadow diff/apply/discard/undo with backups, permission defaults, quota, drafts, and profile. Gaps are minor, such as no single-persona-get or job-history listing, but nothing blocks core workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables a local Codex chat to ask a second opinion, review staged, unstaged, or revision-based diffs, and delegate coding tasks to the Antigravity CLI running in isolated or disposable workspaces. Supports starting, polling, retrieving, and cancelling tasks with returned answers, diffs, changed-file lists, exit codes, and time/output limits, while never auto-applying returned patches.
      8
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Antigravity IDE to delegate coding, debugging, and architecture work to an already logged-in Gemini, Claude, ChatGPT, or DeepSeek web session, then applies the returned changes directly to workspace files over a local WebSocket bridge.
      9
      GPL 3.0