Skip to main content
Glama
CodeRecoder MCP

CodeRecoder MCP

CodeRecoder

CodeRecoder 是一个本地优先的代码备份与可验证恢复系统,同时提供 MCP 服务和 Vue 3 + Electron 桌面控制台。它面向 Codex、Claude Code 及其他支持 MCP 的开发工具,也可以作为独立桌面小窗运行。

当前版本:3.1.0

CodeRecoder 不替代 Git。Git 负责协作、审查、分支和发布历史;CodeRecoder 负责在 AI 编程和高频修改过程中自动保留可恢复副本,并在恢复前后提供完整性证据。

核心能力

能力

当前实现

完整工程备份

每个快照都是逻辑完整、可独立恢复的文件树

存储去重

未变化的普通文件通过硬链接复用,变化文件写入新副本

完整性证据

SHA-256 清单记录路径、类型、内容、权限、大小和整棵树哈希

自动检查点

chokidar 监听、防抖合并、备份期间排队和周期性对账

安全恢复

强制预览、短期确认令牌、恢复前安全快照、恢复后校验

自动回滚

恢复失败时回到操作前状态;进程中断后可在下次初始化时恢复

并发协调

存储锁与工程锁带心跳、超时和失效锁恢复

双控制入口

stdio MCP 服务与 Vue 3/Electron 桌面控制台复用同一备份内核

多工程桌面管理

单 Electron 主进程维护隔离会话,可为工程创建独立观察窗口

Serena 自动接入

自动发现 CLI、创建/修复工程配置、启动 sidecar 并执行 MCP 握手

MCP 配置工作台

为 VS Code、Cursor、Claude Code、Codex 生成本机配置并检查依赖

Related MCP server: GenCodeDoc

架构

flowchart TB
  A[VS Code / Cursor / Claude Code / Codex] -->|stdio JSON-RPC| B[CodeRecoder MCP]
  C[Vue 3 Renderer] -->|类型化白名单 IPC| D[Electron Main]
  D --> R[ProjectSessionRegistry]
  R --> S1[ProjectSession A]
  R --> S2[ProjectSession B…]
  S1 --> F1[BackupManager + AutoCheckpointManager]
  S1 --> SE1[Serena sidecar A]
  S2 --> F2[独立备份管理器与操作队列]
  S2 --> SE2[Serena sidecar B]
  B --> F[BackupManager]
  F1 --> H[SHA-256 清单与完整快照]
  F2 --> H
  F --> H
  H --> I[工程锁 / 存储锁 / 外部备份介质]
  • BackupManager 是唯一生产备份内核,负责扫描、快照、清单、验证、保留策略、恢复和启动恢复。

  • AutoCheckpointManager 只负责监听和调度,最终仍通过 BackupManager 创建经过验证的完整快照。

  • 桌面端持久化 schema v2 工程注册表;每个工程拥有独立管理器、监听器、恢复记录、操作队列与 Serena 进程。

  • 主窗口管理全部会话;同一工程最多一个独立窗口。关闭工程窗口不停止保护,重复打开只会聚焦已有窗口。

  • 两个入口同时保护同一工程时,工程级跨进程锁会串行化写入和恢复操作。

系统要求

  • 从源码运行需要 Node.js 22.12.0 或更高版本及 npm

  • Debian 安装包已内置 Electron 与 MCP Node.js 运行时,不要求系统另装 Node.js

  • 桌面端需要可用的图形会话

  • 完整测试使用操作系统临时目录;旧版 shell 迁移测试依赖 Bash/Linux 工具

安装

Debian / Ubuntu 安装包

从 GitHub Releases 下载 .deb 与 SHA256SUMS,在下载目录执行:

sha256sum -c SHA256SUMS
sudo apt install ./CodeRecoder-3.1.0-amd64.deb
coderecoder

安装包注册应用菜单图标,提供 coderecoder、coderecoder-mcp 和 coderecoder-install-serena。可以在 GNOME 应用列表中右键 CodeRecoder,选择固定到程序栏。安装后无需保留源码目录,也无需为 CodeRecoder 单独安装 Node.js。

如果曾运行源码版快捷方式安装命令,用户级 ~/.local/share/applications/coderecoder.desktop 会优先于系统安装包;请将该文件备份移走后使用系统应用列表中的图标。工程设置与备份保留在原来的用户目录。

源码安装

git clone https://github.com/snow-wind-001/CodeRecoder.git
cd CodeRecoder
npm install
npm run lint
npm test

npm test 会构建 MCP 服务、检查桌面 TypeScript,并运行备份、恢复、并发、自动检查点、MCP 生命周期、stdio 和桌面控制器测试。

快速开始:桌面控制台

npm run desktop:start

多工程备份总览

MCP 与 Serena 配置工作台

恢复预览与安全确认

CodeRecoder 桌面控制台显示多工程会话、保护状态与快照时间线

CodeRecoder MCP 设置显示环境预检、客户端配置和临时 Serena endpoint

CodeRecoder 恢复抽屉显示恢复模式、变更统计和确认令牌

首次启动后:

  1. 选择需要保护的工程目录。

  2. 选择外部备份根目录;推荐使用独立磁盘或专用备份目录。

  3. 决定是否启用自动检查点、随应用启动及 Serena 自动配置。

  4. 点击“注册并启动保护”,等待基线备份验证和 Serena MCP 握手。

  5. 用顶部工程条切换会话;需要并排观察时,为选中工程打开独立窗口。

桌面窗口默认内容尺寸为 424×880,宽度限制为 380–560px,适合放在编辑器旁边。界面提供:

  • 自动检查点健康度和未备份变更提示;

  • 多工程运行汇总,以及备份与 Serena 相互独立的健康状态;

  • 快照时间线、变更数量、逻辑大小、新增占用和树哈希摘要;

  • 手动创建备份和重新验证完整性;

  • exact/overlay 恢复预览、受影响路径和令牌倒计时;

  • 恢复成功、恢复拒绝、自动回滚或回滚失败的明确状态。

桌面端不提供永久删除按钮;删除备份仍需通过 MCP 工具进行双 ID 确认。更多说明见 desktop/README.md。

Debian / Ubuntu 安装包

在 amd64 Debian/Ubuntu 主机上构建并验证安装包:

npm install
npm run desktop:package:deb

产物位于 release/CodeRecoder-3.1.0-amd64.deb,并附带同名 .sha256 校验文件。请使用 apt 安装,以便自动解析 GTK、NSS、音频和桌面集成库:

sudo apt install ./release/CodeRecoder-3.1.0-amd64.deb

安装后可从应用菜单启动 CodeRecoder。程序文件安装到 /opt/CodeRecoder;MCP 配置工作台会使用安装包自带的 coderecoder-mcp 运行时,因此客户端连接不依赖系统 Node.js。Serena、VS Code、Cursor、Claude Code 与 Codex 都是可选集成,不会作为 Debian 强制依赖安装。

desktop:package:deb 会在打包后自动解包校验 control 依赖、文件权限、桌面入口和动态库,并通过内置运行时完成一次 MCP initialize 与工具列表握手。也可以对已有产物单独运行 npm run desktop:verify:deb -- <deb-path>。

安装到 Ubuntu/GNOME 程序栏

npm run desktop:install-linux

该命令先检查并补齐 Electron 运行程序、完成桌面构建,再以当前用户身份安装 coderecoder.desktop,刷新应用列表并固定到 GNOME Dock,最后回读固定结果,不需要 sudo。npm install 和 npm run build 不会自动注册快捷方式,需要单独运行上述命令。

启动项会自动寻找满足要求的 Node.js(包括 NVM 安装),并从当前仓库构建、启动桌面端;因此移动或删除仓库后需要重新运行安装命令。Electron 下载会使用已有的 HTTP_PROXY / HTTPS_PROXY(也支持小写变量);启动日志保存在 ${XDG_STATE_HOME:-~/.local/state}/coderecoder/desktop-launch.log。再次点击图标会唤醒已有窗口。

桌面开发命令

npm run desktop:dev       # 构建内核并启动 Electron/Vite 热更新
npm run desktop:renderer  # 只启动浏览器渲染层,供界面开发使用
npm run desktop:typecheck # 检查 renderer、preload 和 Electron 主进程
npm run desktop:build     # 生产构建到 dist-desktop/
npm run desktop:package:deb # 构建并验证 amd64 Debian 安装包
npm run test:desktop      # 桌面控制器集成测试

多工程与多开策略

桌面端采用单 Electron 实例 + 多工程会话注册表 + 每工程独立备份管理器。第二次启动只聚焦主窗口,不会复制文件监听器或 Serena;工程窗口关闭后,后台会话继续运行。应用退出时,各会话按全局 I/O 并发上限创建最终检查点并停止 sidecar。

注册器拒绝重复工程、父子嵌套工程,以及与任一受保护工程重叠的备份根目录。同一外部备份根目录可以服务多个非嵌套工程,实际数据会写入带工程路径哈希的独立子目录。旧版单工程偏好会迁移到 schema v2,但不会在迁移后未经确认自动启动。

MCP stdio 入口仍是“一服务进程、一活动工程”;多个编辑器客户端可以启动独立进程。若桌面与 MCP 同时操作同一工程,跨进程工程锁会继续保证关键写入串行化。

内置 MCP 配置工作台

点击标题栏的设置按钮,可以:

  • 检查独立 Node.js、dist/index.js、Serena CLI、.serena/project.yml 以及四类客户端程序;

  • 在 VS Code、Cursor、Claude Code、Codex 间切换,并生成 CodeRecoder 或 Serena 配置;

  • 由主进程重新生成并复制建议,renderer 不获得通用剪贴板、文件系统或命令执行权限;

  • 查看当前 Serena HTTP endpoint。该地址只在当前 Electron 工程会话有效,长期配置应使用界面建议的 stdio 命令。

工作台不会覆盖已有客户端配置。合并 JSON/TOML 前应保留原文件,并避免把恢复、删除工具加入无条件自动批准列表。

快速开始:连接 MCP 客户端

先构建 stdio 服务:

npm run build

也可以启动桌面端,打开“MCP 连接设置”,选择客户端和服务后复制已经展开为本机绝对路径的配置。该方式会同时指出缺失组件,但仍由用户决定如何合并现有配置。

VS Code / Cursor

VS Code 使用工作区级 .vscode/mcp.json 的 servers 字段;Cursor 使用用户级 ~/.cursor/mcp.json 的 mcpServers 字段。两者字段结构不同,不要直接复制整个文件互相覆盖。

Codex CLI / IDE

codex mcp add coderecoder -- node /absolute/path/CodeRecoder/dist/index.js
codex mcp list

也可以在 ~/.codex/config.toml 中配置:

[mcp_servers.coderecoder]
command = "node"
args = ["/absolute/path/CodeRecoder/dist/index.js"]
cwd = "/absolute/path/CodeRecoder"

Claude Code

claude mcp add --scope user coderecoder -- node /absolute/path/CodeRecoder/dist/index.js
claude mcp list

其他 MCP 客户端使用等价的 stdio 配置即可。stdout 专用于 MCP JSON-RPC,所有诊断信息写入 stderr。不要在包装脚本中把普通日志输出到 stdout。

Serena

在 MCP 设置中点击“下载并安装 Serena”,或在终端执行以下一种命令:

npm run serena:install                                      # 源码版:下载固定上游版本
bash scripts/install-serena.sh --source /path/to/serena      # 使用已下载的 Serena 源码
coderecoder-install-serena                                  # Debian 安装版

安装器使用官方 uv 准备独立 Python 3.12 环境,并把 CLI 安装到 ~/.local/bin/serena,应以当前用户运行,不使用 sudo。首次安装及语言服务准备需要联网;Serena 源码固定到官方仓库提交 701e7c843f46c6a649203a488cece1bf19f1df90,Python 依赖由 uv 解析。桌面安装日志位于 Electron 用户数据目录下的 logs/serena-install.log。

C# 需要 .NET 10;可以运行 coderecoder-install-serena --with-dotnet,源码版使用 npm run serena:install -- --with-dotnet,安装器会从 Microsoft 下载 SDK 到 ~/.dotnet。TypeScript / JavaScript / Vue 语言服务还需要系统 Node.js 和 npm;这与 CodeRecoder 安装包的内置 MCP 运行时是分别配置的。

为 Codex 添加 Serena:

codex mcp add serena -- "$HOME/.local/bin/serena" start-mcp-server \
  --context codex --project-from-cwd --enable-web-dashboard false \
  --open-web-dashboard false --enable-gui-log-window false
codex mcp list

在 ~/.codex/config.toml 的 [mcp_servers.serena] 段中可设置 startup_timeout_sec = 120、tool_timeout_sec = 240,随后重启 Codex。Debian 安装版 CodeRecoder 可使用 codex mcp add coderecoder -- /usr/bin/coderecoder-mcp。安装与配置不覆盖其他 MCP 服务。

桌面工程会话启用 Serena 后会依次执行:发现可执行文件、检查工程配置、必要时运行 serena project create、以固定参数绑定 127.0.0.1 动态端口,并发送真实 MCP initialize 请求。只有握手成功才显示“已连接”。

后台创建配置时保留自动检测到的主要语言,不启用交互询问的可选语言。多语言工程可编辑 .serena/project.yml 的 language_servers,例如 [csharp, cpp, python];CodeRecoder 的 Vue 组件分析可在 typescript 后增加 vue。请排除 .venv、node_modules、构建输出等依赖目录。已有全局配置若仍使用 TIKTOKEN_GPT4O 且启动卡在分词器下载,可改为当前默认的 token_count_estimator: CHAR_COUNT。

MCP 握手表示服务已接受连接;语言功能是否可用还应通过 get_symbols_overview 等实际调用检查。Linux 下 Windows / Visual C++ 工程可能产生构建依赖诊断,不应据此宣称完整支持 Windows 构建。

若日志包含 Error loading configuration 且已开启自动配置,桌面端会先把现有 project.yml 重命名为带时间戳的 .bak,再创建新配置;重建失败时会尝试恢复原文件。Serena 失败只降低辅助工具状态,不会把正常的备份保护误报为失败。

更多配置示例和批准策略见 MCP_CONFIG_GUIDE.md。

推荐备份工作流

1. 激活工程

activate_project 会初始化存储、执行启动恢复检查、创建经过验证的基线,并默认启动自动检查点。

{
  "projectPath": "/work/my-project",
  "projectName": "my-project",
  "storageRoot": "/data/coderecoder",
  "autoCheckpoint": true,
  "debounceMs": 1500,
  "reconciliationIntervalMs": 60000,
  "maxBackups": 100,
  "excludeNames": ["vendor-generated"]
}

当 storageRoot 存在时,实际工程存储目录为:

<storageRoot>/<project-name>-<project-path-hash>/

省略 storageRoot 时,默认写入 <project>/.CodeRecoder/backups/。如果不希望向源工程写入任何元数据,应始终指定外部目录。

2. 检查保护状态

调用 get_backup_status,重点检查:

  • hasUncheckpointedChanges 是否为 false;

  • automaticCheckpoint.state 是否为 running;

  • watcherReady 是否为 true;

  • lastError 是否为空;

  • latestSnapshot 和 currentMatchesSnapshot 是否符合预期。

自动状态含义:

状态

含义

running

监听与检查点调度可用

paused

恢复或停用流程正在暂停监听

degraded

监听或检查点发生错误,应检查 lastError

stopped

自动检查点未启用或已经停止

3. 创建命名备份

重要重构、升级或批量生成前,建议额外创建显式备份:

{
  "name": "before-auth-refactor",
  "prompt": "认证模块重构前的稳定代码",
  "tags": ["stable", "auth"],
  "skipIfUnchanged": false
}

显式备份默认不会因为内容未变化而跳过,因此可以保留有业务意义的命名节点。

安全恢复

恢复必须分成预览和确认两个阶段。

第一步:生成预览

{
  "snapshotId": "目标快照 UUID",
  "mode": "exact"
}

preview_project_restore 会:

  1. 重新验证目标快照;

  2. 扫描当前工程并计算新增、修改、删除和重命名路径;

  3. 将当前树哈希、工程、目标快照和恢复模式绑定到确认令牌;

  4. 返回五分钟有效、只能使用一次的 confirmationToken。

预览会在备份存储中写入短期确认记录,因此 MCP 元数据将其标记为非只读,但它不会修改源代码。

第二步:明确确认

{
  "snapshotId": "同一个目标快照 UUID",
  "confirmationToken": "预览返回的令牌"
}

令牌过期、已使用、工程在预览后变化、工程/快照/模式不匹配时,恢复会被拒绝。不要手工构造令牌,也不要缓存后重复使用。

恢复模式

模式

行为

适用场景

exact

将受管代码同步到快照状态,并移除快照中不存在的受管路径

完整回到已知代码状态

overlay

写入快照中的路径,但保留当前工程的额外文件

只覆盖已知文件,避免删除新增内容

两种模式都不会删除默认排除项。执行恢复前,系统必须先创建带 protected 标签的恢复前安全快照;执行后必须验证文件字节、类型和权限。失败时自动回滚,只有回滚也通过验证后才会报告 rollbackState: restored。

MCP 工具参考

工具

主要参数

副作用与批准建议

activate_project

projectPath;可选存储、监听、保留和排除设置

创建基线并可能启动监听

deactivate_project

createFinalCheckpoint,默认 true

默认创建最终检查点并清理进程内状态

get_backup_status

无

只读,可用于周期健康检查

create_project_snapshot

name、prompt、tags、skipIfUnchanged

新增经过验证的备份并占用磁盘

list_project_snapshots

limit,范围 1–500,默认 50

只读,按时间倒序返回摘要

preview_project_restore

snapshotId、mode

写入短期令牌,不修改源工程

restore_project_snapshot

snapshotId、confirmationToken

destructive;必须展示预览并取得明确确认

verify_project_snapshot

snapshotId

只读;重新计算内容和清单证据

delete_project_snapshot

snapshotId、相同的 confirmSnapshotId

destructive;永久删除指定备份

恢复和删除工具不应加入客户端的无条件自动批准列表。

快照和存储模型

外部存储结构示例:

/data/coderecoder/
└── my-project-a1b2c3d4e5f6a7b8/
    ├── index.json
    ├── pending/                       # 短期恢复确认记录
    ├── restore-recovery.json          # 恢复事务日志;异常时会保留
    └── snapshots/
        └── <snapshot-uuid>/
            ├── manifest.json
            └── tree/                  # 可独立恢复的完整逻辑文件树

每个清单包含:

  • 快照 ID、名称、标签、触发来源和创建时间;

  • 父快照 ID、完整工程树哈希和 SHA-256 算法标识;

  • 文件、目录和符号链接条目;

  • 普通文件内容哈希、大小和权限;

  • 新增、修改、删除和推断重命名统计;

  • 逻辑大小、实际新增占用及硬链接去重统计;

  • 可获取时的 Git 分支和短提交证据。

快照在逻辑上彼此独立;删除任意一个普通快照不会破坏其他快照的目录结构。物理去重使用硬链接,因此直接篡改备份树中的某个共享文件可能同时影响多个快照。不要手工编辑存储目录,应使用 verify_project_snapshot 检测损坏,并把备份根目录复制到独立介质以获得真正的灾难恢复能力。

默认排除规则

默认按任意路径段排除:

.CodeRecoder  .git  .hg  .svn  node_modules  dist  build  coverage
.next  .cache  .parcel-cache  .pytest_cache  .mypy_cache  .ruff_cache
.turbo  .venv  venv  out  target  __pycache__

此外还排除:

  • 名称以 .env 开头的文件;

  • .log、.tmp、.temp 和 .pyc 文件;

  • 位于受保护工程内部的备份存储目录本身;

  • 用户通过 excludeNames 增加的目录段或文件名。

按工程选择备份范围

默认仍为 backupScope: "all",保留以上排除规则。添加工程时可选择“仅代码与文档”;已注册工程可点击工程行的“设置备份范围”。保存的新范围在下次启动该工程保护时生效,当前会话与现有快照保持原范围。

{
  "backupScope": "code-and-docs",
  "excludePaths": ["output/", "results_swarm_rescue/", "UsedCode/Models/"],
  "includeExtensions": ["svg", "png"]
}

这三个可选字段也可传给 MCP activate_project:

  • backupScope:all 或 code-and-docs。后者按已知文件名和扩展名保留源码、脚本、配置、锁文件、Markdown、TXT、LaTeX、PDF、Office 文档等;常见模型权重、CSV/二进制数据、压缩包、图片和音视频默认跳过。这是文件名规则,不分析内容,也不会自动读取 .gitignore。

  • excludePaths:最多 100 个工程根目录下的相对文件或目录路径。目录及其后代全部排除,不接受绝对路径、.. 或通配符。例如 output/ 不会排除 src/output/,后者需要单独填写;按任意层级名称排除仍可使用 MCP 的 excludeNames。

  • includeExtensions:为 code-and-docs 补充最多 100 个扩展名,可带前导点、不区分大小写。例如 svg、png 保留文档插图,csv 保留需要版本化的数据;显式排除规则优先。

生成目录中的 JSON、TXT 和代码副本仍符合文件类型规则,应通过 excludePaths 排除整个目录。备份扫描、状态对账和自动监听使用相同规则。恢复旧快照也会保留当前排除的文件;过滤配置改变后必须重新生成恢复预览。

符号链接按链接本身保存,不跟随到工程外。恢复时所有清单路径都会经过安全连接检查,拒绝绝对路径和目录穿越。

可靠性设计

  • 写入一致性:清单和索引通过临时文件、文件同步和原子重命名发布。

  • 复制期变更检测:源文件在扫描与复制期间发生变化时,本次备份失败,不登记为成功。

  • 并发锁:同一存储和同一源工程分别加锁;锁带进程信息、心跳和失效恢复。

  • 自动对账:监听事件之外,周期性重新扫描可捕获丢失或合并的文件系统事件。

  • 恢复事务:源代码发生修改前写入持久化恢复日志,并创建验证过的安全快照。

  • 启动恢复:初始化会清理未完成快照、过期令牌,修复可恢复的删除事务,并处理被中断的恢复。

  • 保留策略:超过 maxBackups 时清理最旧的普通快照;protected 恢复前快照不会被自动清理。

  • 诚实状态:监听失败会进入 degraded,不会继续显示为健康状态。

Electron 安全边界

  • contextIsolation: true

  • nodeIntegration: false

  • sandbox: true

  • renderer 不接触文件系统、环境变量、shell 或通用 ipcRenderer

  • preload 与主进程分别验证参数,只暴露备份控制所需的白名单方法

  • IPC 校验主框架和渲染来源;开发地址仅允许 HTTP 回环主机

  • 默认拒绝页面导航、新窗口和所有权限请求

  • Content Security Policy 禁止对象、表单和 frame 内容

  • 工程注册表以 schema v2、0600 权限原子保存;不保存恢复令牌或客户端密钥

  • 工程窗口在主进程绑定 projectId,不能跨会话调用备份、恢复或 Serena 操作

  • Serena 仅使用固定参数直接 spawn,不经过 shell,并只绑定 127.0.0.1

开发和验证

命令

作用

npm run dev

使用 tsx 直接运行 MCP 源码

npm run build

严格编译 TypeScript 到 dist/

npm start

启动已编译的 stdio MCP 服务

npm run lint

检查 MCP、Electron 和 Vue TypeScript

npm run test:quick

运行备份内核与自动检查点测试

npm run test:mcp

运行真实 MCP 初始化、列举和调用生命周期测试

npm run test:desktop

运行多工程隔离、偏好迁移、Serena 修复和 MCP 配置测试

npm run desktop:install-linux

为源码检出安装用户级启动项并固定到 GNOME Dock

npm run desktop:package:deb

构建并验证自包含 MCP 运行时的 amd64 Debian 包

npm test

运行当前完整自动化测试套件

当前测试覆盖二进制内容、空目录、权限、符号链接、排除规则、增删改名、精确恢复、令牌拒绝、损坏检测、保留策略、并发管理器、损坏索引重建、中断删除/恢复、监听防抖、stdio 协议纯净性、多工程停止隔离、工程窗口权限、路径重叠拒绝、偏好迁移、Serena 配置修复与 MCP initialize 握手。

测试必须使用操作系统临时目录和外部备份目录,不要对本仓库或真实工程执行恢复测试。详细测试说明见 test/README.md。

已知边界

  • CodeRecoder 不是文件系统冻结点,也不保证跨多个同时写入文件的应用级事务快照。

  • 自动检查点只在对应 MCP 或桌面进程存活且工程已激活时运行。

  • 当前提供 amd64 Debian/Ubuntu 安装包;尚未配置包签名仓库、自动更新、托盘常驻或云同步。

  • 默认排除的环境文件和密钥不会进入快照,因此需要独立的安全配置备份方案。

  • 硬链接去重降低本地占用,但不能替代离线副本、对象存储版本控制或异地备份。

  • 每个 stdio MCP 进程同时只激活一个工程;桌面端单实例可保护多个工程。

  • 每个启用的 Serena 工程会启动独立语言服务,工程较多时会增加内存占用;注册工程时可按需关闭 Serena,而不影响备份。

故障排查

  • 客户端看不到工具:运行 npm run build,确认配置使用 dist/index.js 的绝对路径,然后重启客户端。

  • JSON-RPC 解析失败:检查包装脚本,确保 stdout 没有普通日志;诊断只能写入 stderr。

  • 自动检查点降级:调用 get_backup_status,查看 automaticCheckpoint.lastError 和目录权限。

  • 恢复令牌失效:重新生成预览;工程变化、超时或令牌已使用都会使旧令牌失效。

  • 备份目录不可写:选择具有写权限的外部 storageRoot,并检查磁盘空间。

  • 桌面窗口无法启动:运行 npm run desktop:install-linux 检查 Electron 运行程序并重新构建、安装快捷方式;若 Electron 下载失败,检查网络及 HTTP_PROXY / HTTPS_PROXY。从程序栏启动的错误记录在 ${XDG_STATE_HOME:-~/.local/state}/coderecoder/desktop-launch.log。

  • Serena 显示 Error loading configuration:在工程卡片确认备份仍正常,再点击 Serena 的重新检测按钮;自动修复启用时,原配置会以 .coderecoder-invalid-<timestamp>.bak 保留。

  • Cursor Serena 无法启动:不要使用已经移除的 serena-mcp-server 入口;命令应为 serena start-mcp-server --context ide --project-from-cwd。

  • 配置建议里的 HTTP 地址变化:这是设计行为;Electron sidecar 使用动态端口,长期连接请使用 stdio 配置。

项目结构

src/
├── index.ts                    # MCP 注册、进程内激活和恢复协调
├── backupManager.ts            # 生产备份、验证、存储和恢复内核
├── autoCheckpointManager.ts    # 文件监听、防抖、队列和周期对账
└── *SnapshotManager.ts         # 保留用于迁移参考的旧实现
desktop/
├── assets/                     # 桌面图标资源
├── electron/                   # Electron main、会话注册表、安全 IPC 与集成服务
│   ├── projectSessionRegistry.ts # 多工程注册、路径隔离与退出协调
│   ├── projectSession.ts       # 每工程备份、监听、恢复状态与操作队列
│   ├── serenaManager.ts        # Serena 配置、sidecar、握手与自动修复
│   └── mcpIntegrationService.ts # 客户端预检及配置建议
├── renderer/                   # Vue 3 界面、组件与样式
├── packaging/                  # Debian 内置 MCP 启动器与安装包验证器
├── install-linux-launcher.sh   # 用户级应用菜单与 GNOME Dock 安装器
├── start-coderecoder-desktop.sh # 图形会话启动包装器
└── shared/contracts.ts         # 桌面 IPC 契约
docs/images/                    # README 桌面界面截图
test/
├── backup-system.test.js       # 内核、并发、恢复和监听测试
├── mcp-server.test.js          # MCP SDK 生命周期测试
├── stdio-smoke.test.js         # 编译后 stdio 协议测试
└── desktop-controller.test.ts  # 桌面控制器工作流测试

贡献规则见 AGENTS.md,快速操作见 QUICKSTART.md,VS Code 配置见 VSCODE_USAGE.md。

License

MIT

Available Tools

9 tools
activate_projectActivate Code BackupA

Activate one project for this MCP process, create a verified baseline, and optionally start automatic checkpoints. Use storageRoot to keep all backup data outside a protected project.

Inputs: projectPath (required), debounceMs, maxBackups, projectName, +4 more. Returns: data, error, message, success

create_project_snapshotCreate Verified Code BackupA

Create an independently restorable, SHA-256-verified backup of the active project. Unchanged files may be deduplicated in storage.

Inputs: name, tags, prompt, skipIfUnchanged. Returns: data, error, message, success

deactivate_projectDeactivate Code BackupA
Idempotent

Create a final checkpoint by default, stop automatic monitoring, and clear this process-local active project.

Inputs: createFinalCheckpoint. Returns: data, error, message, success

delete_project_snapshotDelete Code BackupA
Destructive

Permanently delete one backup. Call only after explicit user approval and repeat the exact snapshot ID in confirmSnapshotId.

Inputs: snapshotId (required), confirmSnapshotId (required). Returns: data, error, message, success

get_backup_statusGet Backup StatusA
Read-onlyIdempotent

Report active-project storage, integrity evidence, pending changes, and automatic-checkpoint health.

Inputs: no named parameters. Returns: data, error, message, success

list_project_snapshotsList Code BackupsB
Read-onlyIdempotent

List verified backups newest first, including hashes, triggers, sizes, and change counts.

Inputs: limit. Returns: data, error, message, success

preview_project_restorePreview Code RestoreA

Verify a backup and calculate the restore change set. Returns a short-lived token; present the preview to the user before requesting confirmation.

Inputs: snapshotId (required), mode. Returns: data, error, message, success

restore_project_snapshotRestore Code BackupA
Destructive

Destructively apply a previously previewed restore. Requires the matching unexpired confirmation token. A verified pre-restore safety backup and automatic rollback are mandatory.

Inputs: snapshotId (required), confirmationToken (required). Returns: data, error, message, success

verify_project_snapshotVerify Code BackupB
Read-onlyIdempotent

Re-hash the selected backup and validate entry types, paths, modes, and manifest integrity.

Inputs: snapshotId (required). Returns: data, error, message, success

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool maps to a distinct lifecycle action (activate, deactivate, create, list, delete, verify, status, preview, restore). The only mild overlap is verify_project_snapshot versus preview_project_restore, since both re-hash/verify a backup, but the preview tool's added change-set and token behavior clarifies the boundary.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern (verify/delete/create/list/restore/preview_project_snapshot, activate/deactivate_project, get_backup_status). The noun shifts to the appropriate resource (project, snapshot, backup_status) without breaking the convention.

    Tool Count5/5

    Nine tools is a well-scoped set for snapshot/backup management, with each tool earning its place across the full lifecycle without redundant operations.

    Completeness5/5

    The surface covers complete lifecycle coverage: activation/deactivation, snapshot creation, listing, verification, deletion, status inspection, and a safety-gated preview-plus-restore flow. No obvious dead ends or missing core operations for the backup domain.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server providing persistent memory for AI coding assistants by storing and searching architectural decisions, patterns, and solutions. It also includes tools for git automation and mapping codebase expertise based on project history.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Smart documentation generator and intelligent versioning system with full MCP support, enabling AI assistants like Claude and Gemini to manage project snapshots, generate docs, and control versioning via 26 MCP tools.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding agents and hosts to enforce deterministic repository boundaries via MCP, providing structured reads, supervised edits, snapshots, audits, and recovery with machine-readable evidence.
      MIT