Skip to main content
Glama

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 website

Docker 用户把 --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

能做什么

能力

工具组

从目录初始化项目、枚举分支

layerfs_project_*

按行读取、目录列表、元数据、grep、glob、文件差异、blame

layerfs_fs_*

文本/二进制写入、精确编辑、原子批量修改、目录、删除、复制、移动

layerfs_fs_*

从任意历史状态 fork、提交历史、差异、合并、发布

layerfs_branch_*

FUSE 工作区挂载、命令执行、状态、提交、卸载

layerfs_workspace_*

存储/文件/覆盖层诊断、历史快照、初始化进度

layerfs_operator_*

后台进程启动、列出和取消

layerfs_operator_process_*

存储格式、去重、检查点、.lww 冲突规则和合并算法都由上游 LayerFS 实现,本项目不包含模拟存储后端。完整参数与语义见 MCP API。

文档

我想…

看

5 分钟跑通并接入 Agent

快速上手

查全部工具、参数和返回结构

MCP API

用 CLI 管理镜像、项目、HTTP 和生命周期

统一 CLI

配置环境变量、项目配置和访问控制

配置

在 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 tools
layerfs_branch_diff_branchesB
Read-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_commitsA
Read-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_commitsC
Read-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_publishB
Destructive

Publish a branch (optionally a specific commit) to main as a new immutable layer.

Inputs: branch (required), commit.

layerfs_fs_applyA
Destructive

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_blameC
Read-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_filesC
Read-onlyIdempotent

Compare two saved file versions, including versions at different paths.

Inputs: leftRef (required), leftPath (required), rightRef (required), rightPath (required).

layerfs_fs_editA
Destructive

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_globC
Read-onlyIdempotent

Find saved paths using a glob pattern, with pagination.

Inputs: ref (required), pattern (required), path, pagePos, +1 more.

layerfs_fs_grepC
Read-onlyIdempotent

Search saved text using LayerFS pattern semantics, with pagination.

Inputs: ref (required), pattern (required), path, pagePos, +1 more.

layerfs_fs_listC
Read-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_mvA
Destructive

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_readA
Read-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_rmC
Destructive

Remove a saved path on a branch, then checkpoint.

Inputs: path (required), branch (required), message.

layerfs_fs_statC
Read-onlyIdempotent

Read saved file or directory metadata.

Inputs: ref (required), path (required).

layerfs_fs_writeB
Destructive

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_historyC
Read-onlyIdempotent

Page a saved file's revision diagnostics.

Inputs: ref (required), path (required), pagePos, pageSize.

layerfs_operator_files_statsC
Read-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_cancelB
Destructive

Cancel a background process by its persisted process id.

Inputs: process (required).

layerfs_operator_process_listA
Read-onlyIdempotent

List the project's background processes, including their Sandbox ids.

Inputs: no named parameters.

layerfs_operator_process_startB
Destructive

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_progressA
Read-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_commitsC
Read-onlyIdempotent

Read checkpoint records with storage diagnostics.

Inputs: branch (required), pagePos, pageSize.

layerfs_operator_store_overwrittenC
Read-onlyIdempotent

Page layers overwritten by a publication, newest first.

Inputs: layer (required), pagePos, pageSize.

layerfs_operator_store_statsB
Read-onlyIdempotent

Read physical/logical storage and deduplication statistics. Null measurements remain null.

Inputs: no named parameters.

layerfs_operator_workspace_changesC
Read-onlyIdempotent

Page pending Workspace changes.

Inputs: ws (required), pagePos, pageSize.

layerfs_operator_workspace_overlayC
Read-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_branchesB
Read-onlyIdempotent

List project branches. Follow hasMore with pagePos + items.length.

Inputs: pagePos, pageSize.

layerfs_statusA
Read-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_commitB
Destructive

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_execA
Destructive

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_statusB
Read-onlyIdempotent

Read a mounted Workspace's pending state and branch head.

Inputs: ws (required).

layerfs_workspace_unmountA
Destructive

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

    C2.8/5.0

    Scored across 41 tools

    Disambiguation2/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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
    • A
      license
      A
      quality
      B
      maintenance
      Coordination 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'
      18
      437
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      19
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
      -