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 to read files outside a 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)

---

How to Start the Server

Prerequisites

Install uv:

# macOS / Linux
curl -Lsf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Install and run

cd light-fs-mcp
uv sync          # install dependencies (fastmcp)
uv run server.py # start in stdio mode (default)

HTTP mode (for remote/web agents)

MCP_TRANSPORT=http MCP_PORT=8000 uv run server.py
# Endpoint: http://127.0.0.1:8000/mcp

SSE mode

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

---

How to Use

All paths passed to tools are relative to the workspace root.
Absolute paths and ../ traversal are rejected with a clear error.

---

get_workspace_info() → dict

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

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 text content of a file.

read_file("notes.txt")
# → "Hello, agent!\nLine 2."

read_file("data/report.md")
# → "# Report\n..."

---

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.

append_to_file("log.txt", "\n2024-06-01 task completed")
# → "✓ Appended 26 bytes → log.txt  [/home/user/agent-workspace/log.txt]"

---

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  [/home/user/agent-workspace/projects/alpha/v2]"

---

search_files(glob_pattern: str) → list[str]

Glob-search across the entire workspace. Returns relative paths.

search_files("**/*.py")
# → ["scripts/run.py", "src/agent.py"]

search_files("reports/*.md")
# → ["reports/jan.md", "reports/feb.md"]

Capped at 200 results to prevent response overload.

---

Safety Notes

1. Path traversal is blocked — every path is resolved against WORKSPACE; anything outside raises ValueError.
2. Empty/None paths are handled gracefully — they map to the workspace root (safe 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 — create a dedicated folder per agent or per project using AGENT_WORKSPACE.
6. UTF-8 only — binary files are not supported; use for text-based formats.

---

Best Practices

• Call get_workspace_info() at the start of a session to know what you're working with.
• Use search_files("**/*") to audit what's in the workspace before starting a multi-step task.
• Use append_to_file for logs and incremental output to avoid accidental overwrites.
• Keep the workspace path short and descriptive — it appears in every error message.
• For multi-agent setups, set AGENT_WORKSPACE to a unique path per agent to avoid conflicts.
• In HTTP/SSE mode, bind to 127.0.0.1 (default) rather than 0.0.0.0 unless you have network-level access controls in place.
• Set LOG_LEVEL=DEBUG during development to see every operation logged to stderr.

---

MCP Config Snippet (Claude Code / Claude Desktop)

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

---

Installation & Publishing (ClawHub)

Submit to ClawHub

ClawHub expects a SKILL.md with valid YAML frontmatter at the repo root.
This file already meets that spec. Steps to publish:

1. Push to GitHub — ClawHub indexes public repos directly.

   git init && git add . && git commit -m "feat: initial release v0.1.1"
   git remote add origin https://github.com/YOUR_USERNAME/light-fs-mcp.git
   git push -u origin main
   

2. Register on ClawHub — Go to clawhub.io, sign in, and click
   Submit Skill → From GitHub Repo. Paste your repo URL.

3. ClawHub validates SKILL.md frontmatter (name, version, tags, description).
   All required fields are already present in this file.

4. Versioning — bump version in both SKILL.md and pyproject.toml on each release,
   then push a matching git tag:

   git tag v0.1.1 && git push origin v0.1.1
   

Install from ClawHub (agent side)

Once published, agents can reference this skill by its ClawHub slug:

skills:
  - clawhub:YOUR_USERNAME/light-fs-mcp@0.1.1