LayerFS-MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| LAYERFS_HOME | No | Upstream private discovery directory, owned by the current user with 0700 permissions. | |
| LAYERFS_IMAGE | No | Immutable sha256:... image ID already present in the local Docker Engine. | |
| LAYERFS_TRACE | No | Upstream call tracing configuration, passed through as-is. | |
| LAYERFS_DAEMON | No | Linux daemon file readable by the MCP process; the SDK passes it to the Sandbox. | |
| LAYERFS_DOCKER | No | Local Docker socket. | /var/run/docker.sock |
| LAYERFS_ENGINE | No | Default docker; the Apple runtime automatically sets podman and configures a compatible socket in the VM. | docker |
| LAYERFS_NATIVE | No | Optional native addon path, default selected by the upstream SDK. | |
| LAYERFS_VOLUME | No | Existing local named volume shared by Sandbox and MCP. | |
| LAYERFS_MCP_EXEC | No | Set to 0 to hide command execution and background process control tools. | |
| LAYERFS_MCP_HOST | No | HTTP host. | 127.0.0.1 |
| LAYERFS_MCP_PORT | No | HTTP port. | 8787 |
| LAYERFS_SDK_PATH | No | Path to the pinned LayerFS checkout or its sdk/js directory; already set in the Docker image. | |
| LAYERFS_MCP_TOKEN | No | HTTP Bearer token; required when binding to a non-loopback address. | |
| LAYERFS_STORE_PATH | No | Linux local Store path; in containers it is /layerfs-store/global/store.sqlite. | |
| LAYERFS_TRACE_STEP | No | Upstream call tracing configuration, passed through as-is. | |
| LAYERFS_DAEMON_HOST | No | Daemon port access address; use 127.0.0.1 for Linux host network or host.docker.internal for Docker Desktop containers. | |
| LAYERFS_MCP_BACKEND | No | Backend to use: apple, docker, or native. Prefer explicit CLI selection. | |
| LAYERFS_MCP_PROJECT | No | Current project name. | default |
| LAYERFS_TRACE_START | No | Upstream call tracing configuration, passed through as-is. | |
| LAYERFS_MCP_OPERATOR | No | Set to 0 to hide all operator tools. | |
| LAYERFS_MCP_READ_ONLY | No | Set to 1 to register only tools with read semantics. | |
| LAYERFS_MCP_TRANSPORT | No | Transport mode: stdio (default) or http. | stdio |
| LAYERFS_MCP_BODY_LIMIT | No | HTTP JSON request limit; stdio is still limited by the client. | 64mb |
| LAYERFS_MCP_CONFIG_DIR | No | Managed project configuration directory. | ~/.config/layerfs-mcp |
| LAYERFS_CONTAINER_PREFIX | No | Container name prefix to distinguish deployments on the same Engine. | |
| LAYERFS_MCP_STORE_POLICY | No | Optional JSON: smallFileThreshold, wholeFileDepth, chunkDepth, metadataDepth; only written to Store at Init. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| layerfs_statusA | Check configuration, automatic runtime preparation progress, pinned upstream revision and exposed methods. This read does not initialize project data or trigger another preparation attempt. |
| 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. |
| layerfs_project_list_branchesB | List project branches. Follow hasMore with pagePos + items.length. |
| layerfs_fs_readA | 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. |
| layerfs_fs_listC | List a saved directory, with pagination. |
| layerfs_fs_statC | Read saved file or directory metadata. |
| layerfs_fs_grepC | Search saved text using LayerFS pattern semantics, with pagination. |
| layerfs_fs_globC | Find saved paths using a glob pattern, with pagination. |
| layerfs_fs_diff_filesC | Compare two saved file versions, including versions at different paths. |
| layerfs_fs_blameC | Read line attribution from a saved file. Inspect comparisonCoarse and continuation fields. |
| layerfs_fs_writeB | Write UTF-8 or base64-decoded binary content on a writable branch, creating a deduplicated checkpoint. main changes only through publish. |
| layerfs_fs_editA | Replace exactly one occurrence on a branch and checkpoint. Zero or multiple matches are refused. |
| layerfs_fs_applyA | Apply ordered write/edit/mkdir/rm/cp/mv changes atomically as one checkpoint. Refusals retain detail.index. Binary writes use encoding=base64. |
| layerfs_fs_mkdirA | Create a directory and its parents on a branch, then checkpoint. An existing directory is a no-op. |
| layerfs_fs_rmC | Remove a saved path on a branch, then checkpoint. |
| layerfs_fs_cpB | Copy a path on a branch and checkpoint. Destination is exact and must not exist. |
| layerfs_fs_mvA | Move a path on a branch and checkpoint. Destination is exact and must not exist. |
| layerfs_branch_forkB | Fork a writable branch from main, any branch, commit or layer. Forking an earlier ref provides rewind without rewriting history. |
| layerfs_branch_list_commitsC | Page a branch's checkpoint history, newest first along first parents. |
| layerfs_branch_diff_commitsA | Page changed paths between two saved refs. Pass nextCursor as cursor for continuation; hunks=false omits line hunks. |
| layerfs_branch_diff_branchesB | Page changed paths between two saved refs. Pass nextCursor as cursor for continuation; hunks=false omits line hunks. |
| 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. |
| layerfs_branch_publishB | Publish a branch (optionally a specific commit) to main as a new immutable layer. |
| 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. |
| layerfs_workspace_execA | 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. |
| layerfs_workspace_statusB | Read a mounted Workspace's pending state and branch head. |
| layerfs_workspace_commitB | Checkpoint Workspace changes and merge against its current branch head once. Conflicts preserve the Workspace for inspection. force is passed unchanged to LayerFS. |
| layerfs_workspace_unmountA | End a Workspace. Dirty state is refused unless discard=true. History is retained; idle Sandboxes are reclaimed by LayerFS. |
| layerfs_operator_store_statsB | Read physical/logical storage and deduplication statistics. Null measurements remain null. |
| layerfs_operator_store_commitsC | Read checkpoint records with storage diagnostics. |
| layerfs_operator_store_overwrittenC | Page layers overwritten by a publication, newest first. |
| layerfs_operator_files_statsC | Read file storage diagnostics; physical attribution can be null. |
| layerfs_operator_files_historyC | Page a saved file's revision diagnostics. |
| layerfs_operator_workspace_overlayC | Read a mounted Workspace's overlay statistics. |
| layerfs_operator_workspace_changesC | Page pending Workspace changes. |
| 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. |
| layerfs_operator_sandbox_listA | Discover the project's Sandboxes and their images. Upstream may reclaim stopped Sandbox records during discovery. |
| layerfs_operator_project_progressA | Read same-process project initialization progress, or null if no Init is running. Counts are progress, not totals. |
| layerfs_operator_process_startB | Start a supervised background command in a Workspace. Keep the returned process id; commit filesystem changes explicitly. |
| layerfs_operator_process_listA | List the project's background processes, including their Sandbox ids. |
| layerfs_operator_process_cancelB | Cancel a background process by its persisted process id. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| layerfs_workflow | Plan isolated agent work with checkpoints, merge and publication |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| guide | LayerFS workflow and error semantics |
| capabilities | Exact SDK-to-tool mapping enabled on this server |
| branches | First page of project branches; use the list tool for continuation |
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.