Lightweight Scoped Filesystem MCP

Lightweight, security-scoped filesystem MCP server for AI agents. Provides workspace introspection, file read/write/append, directory listing, creation, and glob search — all strictly restricted to a configurable workspace root.

When to Use

Use this skill when an agent needs to:

• Inspect the workspace before starting work (get_workspace_info)
• Read files produced by other tools or pipelines
• Write structured output (JSON, Markdown, CSV, logs) to disk
• List what files are present in a working area
• Search for files by type or name pattern across a directory tree
• Create directory structures before writing to them
• Append incrementally to log files or running reports

Do not use when:

• You need files outside the designated workspace (use a broader filesystem tool)
• You need binary file manipulation or encoding beyond UTF-8
• You need to execute code or shell commands (this tool does file I/O only)

---

Quick Start

OpenClaw

openclaw skills install light-fs-mcp

Then add to your agent config:

skills:
  - clawhub:AIsofialuz/light-fs-mcp@0.1.3

Hermes

tools:
  - type: mcp
    skill: AIsofialuz/light-fs-mcp
    version: "0.1.3"
    env:
      AGENT_WORKSPACE: /path/to/your/workspace

Claude Desktop / Claude Code (stdio)

{
  "mcpServers": {
    "light-fs-mcp": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/light-fs-mcp/server.py"],
      "env": {
        "AGENT_WORKSPACE": "/Users/you/agent-workspace"
      }
    }
  }
}

Manual (any agent, HTTP transport)

git clone https://github.com/AIsofialuz/light-fs-mcp
cd light-fs-mcp
uv sync
MCP_TRANSPORT=http MCP_PORT=8000 uv run server.py
# Endpoint: http://127.0.0.1:8000/mcp

---

How to Start the Server

stdio (default — for local agents)

uv sync
uv run server.py

HTTP (for remote/web agents)

MCP_TRANSPORT=http MCP_PORT=8000 uv run server.py

SSE

MCP_TRANSPORT=sse MCP_PORT=8001 uv run server.py

Environment variables

Variable	Default	Purpose
AGENT_WORKSPACE	~/agent-workspace	Root folder — all operations are jailed here
MCP_TRANSPORT	stdio	stdio, http, or sse
MCP_HOST	127.0.0.1	Bind address (HTTP/SSE only)
MCP_PORT	8000	Bind port (HTTP/SSE only)
LOG_LEVEL	INFO	DEBUG, INFO, WARNING, or ERROR

---

Tools Reference

All paths are relative to the workspace root. Absolute paths and ../ traversal are rejected.

---

get_workspace_info() → dict

Returns workspace root, file/folder counts, and disk usage. Call this first to orient yourself before any other operation.

get_workspace_info()
# → {
#     "root": "/home/user/agent-workspace",
#     "total_files": 12,
#     "total_dirs": 3,
#     "disk_usage_bytes": 48210,
#     "disk_usage_human": "47.1 KB"
#   }

---

read_file(path: str) → str

Read the full UTF-8 text content of a file.

read_file("notes.txt")          # → "Hello, agent!\nLine 2."
read_file("data/config.json")   # → '{"key": "value"}'

---

write_file(path: str, content: str) → str

Write (or overwrite) a file. Parent directories are created automatically.

write_file("output/summary.md", "# Summary\n\nAll done.")
# → "✓ Written 22 bytes → output/summary.md  [/home/user/agent-workspace/output/summary.md]"

⚠️ Overwrites without confirmation. Use append_to_file to add without erasing.

---

append_to_file(path: str, content: str) → str

Append text to a file. Creates the file if it doesn't exist. No automatic newline — include \n yourself.

append_to_file("run.log", "\n2026-01-01 task completed in 4.2s")
# → "✓ Appended 36 bytes → run.log  [/home/user/agent-workspace/run.log]"

---

list_dir(path: str = ".") → list[str]

List the immediate contents of a directory. Directories have a trailing /.

list_dir(".")       # → ["data/", "log.txt", "output/", "report.md"]
list_dir("data")    # → ["prices.csv", "users.json"]

---

create_directory(path: str) → str

Create a directory tree. Safe to call if it already exists.

create_directory("projects/alpha/v2")
# → "✓ Directory ready: projects/alpha/v2  [...]"

---

search_files(glob_pattern: str) → list[str]

Glob-search across the entire workspace. Returns relative paths, capped at 200.

search_files("**/*.py")        # → ["scripts/run.py", "src/agent.py"]
search_files("reports/*.md")   # → ["reports/jan.md", "reports/feb.md"]
search_files("**/*")           # → every file in the workspace

---

Common Agent Workflows

Start a new task

# 1. Orient yourself
info = get_workspace_info()

# 2. Check what's already there
files = list_dir(".")

# 3. Set up structure
create_directory("outputs/run-01")

# 4. Do work, write results
write_file("outputs/run-01/result.json", json_data)

Incremental logging

append_to_file("agent.log", f"\n[{timestamp}] Started task: {task_name}")
# ... do work ...
append_to_file("agent.log", f"\n[{timestamp}] Completed in {elapsed}s")

Find and process files

# Find all CSVs, read each one
csv_files = search_files("**/*.csv")
for path in csv_files:
    content = read_file(path)
    # process...
    write_file(path.replace(".csv", "_processed.csv"), result)

---

Safety Notes

1. Path traversal is blocked — every path is resolved against WORKSPACE; anything outside raises ValueError.
2. Empty/None paths map safely to the workspace root (useful for directory tools).
3. No shell execution — pure Python file I/O, no subprocess, no os.system.
4. No network access — operates on local disk only.
5. Workspace is isolated — use a unique AGENT_WORKSPACE per agent to avoid conflicts.
6. UTF-8 only — use for text-based formats (JSON, Markdown, CSV, plain text).

---

Best Practices

• Always call get_workspace_info() first — it tells you the root path and what's already there.
• Use append_to_file for logs and incremental output to avoid accidental overwrites.
• Use search_files("**/*") to audit the workspace before a multi-step task.
• In HTTP/SSE mode, keep MCP_HOST=127.0.0.1 (default) unless you have network-level access controls.
• Set LOG_LEVEL=DEBUG during development to see every operation in stderr.
• For multi-agent setups, give each agent its own AGENT_WORKSPACE path.

---

Installation & Publishing (ClawHub)

# Install CLI
npm install -g clawhub

# Login
clawhub login --token YOUR_TOKEN --no-browser

# Publish
clawhub skill publish . --slug light-fs-mcp --version 0.1.3

# Anyone installs with:
openclaw skills install light-fs-mcp