LayerFS-MCP
LayerFS-MCP lets an MCP agent manage a versioned LayerFS project, including file operations, branching/merging, isolated workspaces, command execution, and diagnostics.
Check server status/config and initialize a project from a host directory.
Read, list, stat, grep, glob, diff, and blame saved files at branches/commits/layers.
Write text or binary files, make exact edits, apply atomic batches, and create/remove/copy/move paths with checkpoints.
Fork branches, list commit history, diff commits/branches, merge branches, and publish to
main.Mount branches as isolated FUSE workspaces, run commands, inspect/commit changes, and unmount or discard dirty state.
Inspect storage/file/workspace diagnostics, history snapshots, sandboxes, and project initialization progress.
Start, list, and cancel supervised background processes inside workspaces.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@LayerFS-MCP create a branch off main, edit README, commit, and merge it back"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
LayerFS-MCP
English · 中文
让支持 MCP 的 Agent 通过标准工具使用 LayerFS:共享历史、隔离工作区、自动检查点、分支、合并、发布与去重存储。
一个服务实例绑定一个项目,默认暴露 41 个工具(27 个 LayerFS 公开方法、13 个 operator 方法、1 个状态工具)、3 个资源与 1 个工作流提示词,同时支持 stdio 与 Streamable HTTP。
快速开始
要求:Node.js 22+,以及一个容器引擎——macOS 用 Apple Container,其他平台用 Docker Engine / Docker Desktop。
# 首次:指定导入源启动,运行环境自动准备,不需要手动 setup
npx -y layerfs-mcp@0.1.0 serve --backend apple-container --project website --source /absolute/path/website
# 另开一个终端:显式导入项目(serve 不会自动导入文件)
npx -y layerfs-mcp@0.1.0 init --project website
# 之后配置已保存,直接启动
npx -y layerfs-mcp@0.1.0 serve --project websiteDocker 用户把 --backend apple-container 换成 --backend docker。
serve 会立即完成 MCP 握手并列出工具。首次构建镜像期间 layerfs_status 返回 preparing,变为 ready 后即可调用 LayerFS 方法。完整的安装方式、导入和验证步骤见 快速上手。
接入 Agent
把下面这段加进客户端的 MCP 配置(也可直接用 examples/mcp-unified-stdio.json):
{
"mcpServers": {
"layerfs": {
"command": "layerfs-mcp",
"args": ["serve", "--backend", "apple-container", "--project", "website"]
}
}
}未全局安装时把 command 换成 npx,args 从 -y, layerfs-mcp@0.1.0 开始(见 examples/mcp-npx.json)。需要远程或共享接入时用 Streamable HTTP:
layerfs-mcp serve --project website --transport http --host 127.0.0.1 --port 8787
# 端点 http://127.0.0.1:8787/mcp,请求头 Authorization: Bearer <LAYERFS_MCP_TOKEN>Related MCP server: Foremerge
能做什么
能力 | 工具组 |
从目录初始化项目、枚举分支 |
|
按行读取、目录列表、元数据、grep、glob、文件差异、blame |
|
文本/二进制写入、精确编辑、原子批量修改、目录、删除、复制、移动 |
|
从任意历史状态 fork、提交历史、差异、合并、发布 |
|
FUSE 工作区挂载、命令执行、状态、提交、卸载 |
|
存储/文件/覆盖层诊断、历史快照、初始化进度 |
|
后台进程启动、列出和取消 |
|
存储格式、去重、检查点、.lww 冲突规则和合并算法都由上游 LayerFS 实现,本项目不包含模拟存储后端。完整参数与语义见 MCP API。
文档
我想… | 看 |
5 分钟跑通并接入 Agent | |
查全部工具、参数和返回结构 | |
用 CLI 管理镜像、项目、HTTP 和生命周期 | |
配置环境变量、项目配置和访问控制 | |
在 Apple、Docker、原生 Linux 之间选后端 | |
了解检查点、分支、合并和并发约定 | |
跑测试、看已验证的范围 | |
排查启动失败、导入冲突、连不上 | |
发布到 npm |
中文文档在 docs/,英文文档在 docs/en/,两边页面一一对应。
边界
默认完整模式具备目录导入、命令执行和 Docker 权限,只连接可信 Agent。分支与 Workspace 提供工作隔离,不构成租户权限边界。
服务不自动重试。超时或断线不表示操作没有发生,应先检查进程、工作区和提交历史。
上游 Disposable Store 没有崩溃/断电持久性保证,重要数据请保留可重建的原始副本。MCP 层不改变这一性质。
一个实例一个项目。要跑另一个项目,请使用不同的项目名、home、Store 卷、容器前缀和端口。
开发
npm ci
npm run build
npm run check # tsc --noEmit
npm test # 协议、schema、参数转换、分页、错误保留、stdio 与 HTTP需要真实 Store / FUSE / 容器引擎的测试见 测试与验证。
许可证 MIT;上游与依赖声明见 THIRD_PARTY_NOTICES.md。
Available Tools
41 toolslayerfs_branch_diff_branchesBRead-onlyIdempotent
Page changed paths between two saved refs. Pass nextCursor as cursor for continuation; hunks=false omits line hunks.
Inputs: to (required), from (required), hunks, cursor, +2 more.
layerfs_branch_diff_commitsARead-onlyIdempotent
Page changed paths between two saved refs. Pass nextCursor as cursor for continuation; hunks=false omits line hunks.
Inputs: to (required), from (required), hunks, cursor, +2 more.
layerfs_branch_forkB
Fork a writable branch from main, any branch, commit or layer. Forking an earlier ref provides rewind without rewriting history.
Inputs: name (required), fromRef.
layerfs_branch_list_commitsCRead-onlyIdempotent
Page a branch's checkpoint history, newest first along first parents.
Inputs: branch (required), pagePos, pageSize.
layerfs_branch_mergeC
Merge two branches into a new named branch. Preserve Conflict.detail and truncation flags. Optional merge units group related path patterns; .lww rules are handled by LayerFS.
Inputs: a (required), b (required), name (required), units, +1 more.
layerfs_branch_publishBDestructive
Publish a branch (optionally a specific commit) to main as a new immutable layer.
Inputs: branch (required), commit.
layerfs_fs_applyADestructive
Apply ordered write/edit/mkdir/rm/cp/mv changes atomically as one checkpoint. Refusals retain detail.index. Binary writes use encoding=base64.
Inputs: branch (required), changes (required), message.
layerfs_fs_blameCRead-onlyIdempotent
Read line attribution from a saved file. Inspect comparisonCoarse and continuation fields.
Inputs: ref (required), path (required), fromLine.
layerfs_fs_cpB
Copy a path on a branch and checkpoint. Destination is exact and must not exist.
Inputs: to (required), from (required), branch (required), message.
layerfs_fs_diff_filesCRead-onlyIdempotent
Compare two saved file versions, including versions at different paths.
Inputs: leftRef (required), leftPath (required), rightRef (required), rightPath (required).
layerfs_fs_editADestructive
Replace exactly one occurrence on a branch and checkpoint. Zero or multiple matches are refused.
Inputs: path (required), branch (required), newText (required), oldText (required), +1 more.
layerfs_fs_globCRead-onlyIdempotent
Find saved paths using a glob pattern, with pagination.
Inputs: ref (required), pattern (required), path, pagePos, +1 more.
layerfs_fs_grepCRead-onlyIdempotent
Search saved text using LayerFS pattern semantics, with pagination.
Inputs: ref (required), pattern (required), path, pagePos, +1 more.
layerfs_fs_listCRead-onlyIdempotent
List a saved directory, with pagination.
Inputs: ref (required), path, pagePos, pageSize.
layerfs_fs_mkdirA
Create a directory and its parents on a branch, then checkpoint. An existing directory is a no-op.
Inputs: path (required), branch (required), message.
layerfs_fs_mvADestructive
Move a path on a branch and checkpoint. Destination is exact and must not exist.
Inputs: to (required), from (required), branch (required), message.
layerfs_fs_readARead-onlyIdempotent
Read UTF-8 lines from a branch, commit or layer. Lines are 1-based and inclusive. Follow nextLine and inspect truncated/lineTruncated; binary files are refused.
Inputs: ref (required), path (required), endLine, startLine.
layerfs_fs_rmCDestructive
Remove a saved path on a branch, then checkpoint.
Inputs: path (required), branch (required), message.
layerfs_fs_statCRead-onlyIdempotent
Read saved file or directory metadata.
Inputs: ref (required), path (required).
layerfs_fs_writeBDestructive
Write UTF-8 or base64-decoded binary content on a writable branch, creating a deduplicated checkpoint. main changes only through publish.
Inputs: path (required), branch (required), content (required), message, +1 more.
layerfs_operator_files_historyCRead-onlyIdempotent
Page a saved file's revision diagnostics.
Inputs: ref (required), path (required), pagePos, pageSize.
layerfs_operator_files_statsCRead-onlyIdempotent
Read file storage diagnostics; physical attribution can be null.
Inputs: ref (required), path (required).
layerfs_operator_inspect_snapshotC
Read project history and all live Workspaces. Pass the previous version as since to receive kind=unchanged when applicable. Upstream discovery may reclaim stopped Sandbox records.
Inputs: since.
layerfs_operator_process_cancelBDestructive
Cancel a background process by its persisted process id.
Inputs: process (required).
layerfs_operator_process_listARead-onlyIdempotent
List the project's background processes, including their Sandbox ids.
Inputs: no named parameters.
layerfs_operator_process_startBDestructive
Start a supervised background command in a Workspace. Keep the returned process id; commit filesystem changes explicitly.
Inputs: ws (required), command (required).
layerfs_operator_project_progressARead-onlyIdempotent
Read same-process project initialization progress, or null if no Init is running. Counts are progress, not totals.
Inputs: no named parameters.
layerfs_operator_sandbox_listA
Discover the project's Sandboxes and their images. Upstream may reclaim stopped Sandbox records during discovery.
Inputs: no named parameters.
layerfs_operator_store_commitsCRead-onlyIdempotent
Read checkpoint records with storage diagnostics.
Inputs: branch (required), pagePos, pageSize.
layerfs_operator_store_overwrittenCRead-onlyIdempotent
Page layers overwritten by a publication, newest first.
Inputs: layer (required), pagePos, pageSize.
layerfs_operator_store_statsBRead-onlyIdempotent
Read physical/logical storage and deduplication statistics. Null measurements remain null.
Inputs: no named parameters.
layerfs_operator_workspace_changesCRead-onlyIdempotent
Page pending Workspace changes.
Inputs: ws (required), pagePos, pageSize.
layerfs_operator_workspace_overlayCRead-onlyIdempotent
Read a mounted Workspace's overlay statistics.
Inputs: ws (required).
layerfs_project_initA
Initialize this server's project from a host directory. Explicit, one-time import; requires Linux and an installed native addon. Never called automatically.
Inputs: sourcePath (required).
layerfs_project_list_branchesBRead-onlyIdempotent
List project branches. Follow hasMore with pagePos + items.length.
Inputs: pagePos, pageSize.
layerfs_statusARead-onlyIdempotent
Check configuration, automatic runtime preparation progress, pinned upstream revision and exposed methods. This read does not initialize project data or trigger another preparation attempt.
Inputs: no named parameters.
layerfs_workspace_commitBDestructive
Checkpoint Workspace changes and merge against its current branch head once. Conflicts preserve the Workspace for inspection. force is passed unchanged to LayerFS.
Inputs: ws (required), force, message.
layerfs_workspace_execADestructive
Run a command in a mounted Workspace; returns complete stdout/stderr and exitCode. Does not checkpoint: call workspace.commit afterward, including after a failing command. A client timeout does not establish that the command stopped; inspect before retrying.
Inputs: ws (required), command (required), message.
layerfs_workspace_mountA
Mount a branch as an isolated writable FUSE Workspace. LayerFS chooses or creates its Sandbox. Save the returned {sandbox,path} handle; optional image is a local immutable sha256 digest.
Inputs: branch (required), image.
layerfs_workspace_statusBRead-onlyIdempotent
Read a mounted Workspace's pending state and branch head.
Inputs: ws (required).
layerfs_workspace_unmountADestructive
End a Workspace. Dirty state is refused unless discard=true. History is retained; idle Sandboxes are reclaimed by LayerFS.
Inputs: ws (required), discard.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Several tools have very close boundaries: branch_diff_commits and branch_diff_branches have essentially identical descriptions, fs_apply overlaps with the individual fs_write/edit/rm/mkdir/cp/mv tools, and command execution is split between workspace_exec and process_start. The many operator diagnostic/read tools also blur together despite prefix grouping.
Names use consistent snake_case and useful domain prefixes (fs_, workspace_, branch_, operator_), but action ordering is mixed: operator_sandbox_list and operator_process_start use noun-verb, while operator_inspect_snapshot uses verb-noun and others are noun-noun. The patterns remain readable but are not fully uniform.
At 41 tools this surface is heavy for a single server, even one covering filesystem, branches, workspaces, processes, and diagnostics. Many tools could likely be consolidated, especially the diff, diagnostic, and fs mutation families.
The server covers a broad lifecycle: file read/write/edit/remove/copy/move, branch fork/merge/publish, workspace mount/unmount/commit/exec, process control, and extensive diagnostics. Minor gaps remain, such as branch deletion/rename or filesystem permission/symlink operations.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
A MCP server built for developers enabling Git based project management with project and personal…
Project management shared by people and AI agents, with persistent project state through MCP.
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA minimal, security-focused MCP server that provides structured read/write access to exactly one local workspace, with built-in local Git checkpoints and rollback.Apache 2.0
- AlicenseAqualityBmaintenanceCoordination protocol for parallel coding agents, built above Git. The MCP server exposes the full 17-tool lifecycle over stdio: register agents, publish intents with semantic scopes and declared operations, claim work, check for conflicts before code is written, publish ChangeSets, run trusted named verification checks, and record accepted work. Deterministic rules raise findings when two agents'18437Apache 2.0
- AlicenseAqualityBmaintenanceEnables MCP clients to safely read, write, edit, search, and optionally run commands within one or more named project workspaces, while maintaining a work journal and tracking changes.19MIT
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to manage files in an isolated workspace and perform lightweight Git operations through a protected Streamable HTTP endpoint, including listing, reading, writing, searching, replacing, and deleting files plus checking status and diffs.1-