LiveFolders MCP Server

🗂️ LiveFoldersFS

Chain tools into one call. Declare a pipeline in folder.yaml, the agent triggers the whole thing with a single echo / cat — no per-step JSON, no per-step model turn.

# tools/weather/folder.yaml
files:
  - name: report
    type: write_invoke
    pipe: [fetch_data, translate, format]   # 3 steps, 1 endpoint

echo "London" > .livefolders/tools/weather/report
cat  .livefolders/tools/weather/report
# → fetch → translate → format, all in one round trip

Why a folder beats JSON tool-calling

• 1 round trip per workflow, not N. A 5-step chain is one model turn, not five. The agent writes once and reads once; the kernel runs the pipeline.
• No schema chatter between stages. Stages hand bytes to each other on stdin/stdout — no re-serializing through the model, no per-call validation overhead.
• Lazy discovery. ls, cat index.md, cat how_to.md. Tool docs load only when the agent needs them, instead of every schema squatting in the context window.
• Shell composition for free. Agents already know |, xargs, tee. Composing tools doesn't require a new protocol.

---

Install

curl -fsSL https://raw.githubusercontent.com/natanloterio/LiveFolders/master/install.sh | bash

Prerequisites

• Linux: sudo apt-get install fuse3
• macOS: install macFUSE

<details> <summary>Manual install / from source</summary>

# Linux x86_64
curl -L https://github.com/natanloterio/LiveFolders/releases/latest/download/livefolders-linux-x86_64 -o livefolders
chmod +x livefolders && sudo mv livefolders /usr/local/bin/

# From source
cargo install --git https://github.com/natanloterio/LiveFolders

</details>

---

Quick start

# 1. Create a config file
livefolders init

# 2. Install a tool from the registry
livefolders install github.com/natanloterio/LiveFolders/tree/master/examples/users

# 3. Mount (runs in background, returns to prompt immediately)
livefolders mount

# 4. Use it
cat .livefolders/tools/users/list      # fetches users from the API

echo "hello world" > .livefolders/tools/demo/shout
cat .livefolders/tools/demo/shout      # → HELLO WORLD

# 5. Stop
livefolders stop

---

Giving tools to Claude Code

Add this to your project's CLAUDE.md:

## Tools

LiveFolders is mounted at `.livefolders/tools/`. Before using any tool:
1. `cat .livefolders/tools/index.md` to see what's available
2. `cat .livefolders/tools/<name>/how_to.md` to read usage instructions
3. Write input with `echo "..." > .livefolders/tools/<name>/<endpoint>`
4. Read output with `cat .livefolders/tools/<name>/<endpoint>`

Or register LiveFolders as an MCP server so Claude Code picks it up automatically:

livefolders mcp register

---

How it works

Every tool is a directory under /tools/<name>/. Each file inside is an endpoint:

• Write to an endpoint → sends input to the tool
• Read from an endpoint → gets the result

.livefolders/tools/
├── index.md            ← all tools and descriptions
├── demo/
│   ├── how_to.md       ← LLM reads this to understand the tool
│   ├── schema.json     ← machine-readable endpoint schemas (auto-generated)
│   ├── shout           ← write text, read it back uppercased
│   ├── shout.log       ← last invocation: duration_ms + stderr
│   └── status          ← read to get current status
└── users/
    ├── how_to.md
    ├── schema.json
    └── list            ← read to fetch users from the API

The write call blocks until the tool finishes — by the time cat runs, the result is ready.

---

Using with an LLM

Once mounted, give the agent a single instruction:

"Tools are mounted at .livefolders/tools/. Read index.md to discover what's available, then read how_to.md inside any tool directory before using it."

The agent then follows this natural sequence on its own:

1. Discover available tools

cat .livefolders/tools/index.md
# → weather  — Get the weather forecast for any city.
# → users    — Fetch users from the REST API.

2. Read the instructions for a tool

cat .livefolders/tools/weather/how_to.md

3. Invoke the tool

echo "London" > .livefolders/tools/weather/forecast
cat .livefolders/tools/weather/forecast
# → Weather report for London, United Kingdom:
# →    \☁️   Overcast
# →   15 °C

4. Handle errors

echo "" > .livefolders/tools/weather/forecast
cat .livefolders/tools/weather/forecast
# → [ERROR:INVALID_INPUT] input too short: minimum 1 characters required

---

Mount and stop

livefolders mount               # mount in background (default)
livefolders mount --foreground  # stay in foreground (useful for debugging)
livefolders stop                # stop the background daemon

Logs go to ~/.local/share/livefolders/livefolders.log.

If something looks wrong, run livefolders doctor — it checks FUSE, your config, and every installed tool's folder.yaml and prints actionable fixes.

---

Installing tools

# From the registry (short form)
livefolders install owner/name
livefolders install owner/name@v1.2.0   # pin to a version

# From GitHub directly
livefolders install github.com/owner/repo
livefolders install github.com/owner/repo/tree/main/mytool

If a tool requires secrets, you'll be prompted for them on install.

---

Tool registry

The LiveFolders registry is a public index of tools.

livefolders search weather        # search for tools
livefolders info owner/name       # show details for a tool
livefolders publish               # publish this repo to the registry

---

MCP server

LiveFolders can act as an MCP server, exposing all mounted tools to any MCP-aware client (Claude Desktop, Claude Code, etc.).

livefolders mcp                              # start MCP server over stdio
livefolders mcp register                     # register with Claude Code (~/.claude.json)
livefolders mcp register /path/to/livefolders.yaml  # register a named project

Each endpoint becomes an MCP tool named <tool>__<endpoint> (e.g. weather__forecast).

---

Example tools

Tool	Install	What it does
demo	livefolders install github.com/natanloterio/LiveFolders/tree/master/examples/demo	Demonstrates all file types and input schema validation
users	livefolders install github.com/natanloterio/LiveFolders/tree/master/examples/users	Fetches users from a REST API via GET

---

Going further

• Building tools — folder.yaml reference, file types, input validation, pipelines, stateful tools, secrets, hot-reload
• Security — sandbox model, Landlock/seccomp, network access, strict mode

---

License

Apache 2.0 — see LICENSE.