Lightweight, security-scoped filesystem MCP server for AI agents. Provides workspace introspection, file read/write/append, directory listing, creation, and...
SKILL.md

---
name: light-fs-mcp
version: "0.1.6"
description: >
  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.
tags:
  - mcp
  - filesystem
  - local
  - file-io
  - agent-tools
  - fastmcp
  - openClaw
  - hermes
transport:
  - stdio
  - streamable-http
  - sse
requires_python: ">=3.11"
license: MIT
---

## 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

```bash
openclaw skills install light-fs-mcp
```

Then add to your agent config:

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

### Hermes

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

### Claude Desktop / Claude Code (stdio)

```json
{
  "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)

```bash
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)

```bash
uv sync
uv run server.py
```

### HTTP (for remote/web agents)

```bash
MCP_TRANSPORT=http MCP_PORT=8000 uv run server.py
```

### SSE

```bash
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.

```python
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.

```python
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.

```python
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.

```python
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 `/`.

```python
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.

```python
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.

```python
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

```python
# 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

```python
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

```python
# 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)

```bash
# 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
```

```bash
# Anyone installs with:
openclaw skills install light-fs-mcp
```
Light FS MCP — Scoped Filesystem for AI Agents

SKILL.md

related skills
