Lightweight Scoped Filesystem MCP — Lightweight Scoped File系统 MCP

When to Use

Use this 技能 when an 代理 needs to:

Inspect the workspace before 启动ing work (获取_workspace_信息) Read files produced by other 工具s or 流水线s Write structured 输出 (JSON, Markdown, CSV, 记录s) to disk 列出 what files are present in a working area 搜索 for files by type or name pattern across a directory tree 创建 directory structures before writing to them 应用end incrementally to 记录 files or 运行ning 报告s

Do not use when:

You need to read files outside a de签名ated workspace (use a broader file系统 工具) You need binary file manipulation or encoding beyond UTF-8 You need to 执行 code or shell commands (this 工具 does file I/O only) How to 启动 the Server Prerequisites

安装 uv:

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

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

安装 and 运行 cd light-fs-mcp uv 同步 # 安装 dependencies (fastmcp) uv 运行 server.py # 启动 in stdio mode (default)

HTTP mode (for remote/网页 代理s) MCP_TRANSPORT=http MCP_PORT=8000 uv 运行 server.py # 端点: http://127.0.0.1:8000/mcp

SSE mode MCP_TRANSPORT=sse MCP_PORT=8001 uv 运行 server.py

环境 variables Variable Default Purpose 代理_WORKSPACE ~/代理-workspace Root folder — all operations are jAIled here MCP_TRANSPORT stdio stdio, http, or sse MCP_HOST 127.0.0.1 Bind 添加ress (HTTP/SSE only) MCP_PORT 8000 Bind port (HTTP/SSE only) 记录_LEVEL 信息 调试, 信息, 警告, or ERROR How to Use

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

获取_workspace_信息() → dict

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

获取_workspace_信息() # → { # "root": "/home/user/代理-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, 代理!\nLine 2."

read_file("data/报告.md") # → "# 报告\n..."

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

Write (or overwrite) a file. Parent directories are 创建d automatically.

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

⚠️ Overwrites without confirmation. Use 应用end_to_file to 添加 without erasing.

应用end_to_file(path: str, content: str) → str

应用end text to a file. 创建s the file if it doesn't exist. No automatic newline.

应用end_to_file("记录.txt", "\n2024-06-01 task completed") # → "✓ 应用ended 26 bytes → 记录.txt [/home/user/代理-workspace/记录.txt]"

列出_dir(path: str = ".") → 列出[str]

列出 the immediate contents of a directory. Directories have a trAIling /.

列出_dir(".") # → ["data/", "记录.txt", "输出/", "报告.md"]

列出_dir("data") # → ["prices.csv", "users.json"]

创建_directory(path: str) → str

创建 a directory tree. Safe to call if it already exists.

创建_directory("projects/alpha/v2") # → "✓ Directory ready: projects/alpha/v2 [/home/user/代理-workspace/projects/alpha/v2]"

搜索_files(glob_pattern: str) → 列出[str]

Glob-搜索 across the entire workspace. Returns relative paths.

搜索_files("*/.py") # → ["scripts/运行.py", "src/代理.py"]

搜索_files("报告s/.md") # → ["报告s/jan.md", "报告s/feb.md"]

C应用ed at 200 结果s to 预防 响应 overload.

Safety Notes Path traversal is blocked — every path is resolved agAInst WORKSPACE; anything outside rAIses ValueError. Empty/None paths are handled gracefully — they map to the workspace root (safe for directory 工具s). No shell execution — pure Python file I/O, no subprocess, no os.系统. No network 访问 — operates on local disk only. Workspace is isolated — 创建 a dedicated folder per 代理 or per project using 代理_WORKSPACE. UTF-8 only — binary files are not supported; use for text-based 格式化s. Best Practices Call 获取_workspace_信息() at the 启动 of a 会话 to know what you're working with. Use 搜索_files("/") to 审计 what's in the workspace before 启动ing a multi-step task. Use 应用end_to_file for 记录s and incremental 输出 to avoid accidental overwrites. Keep the workspace path short and descriptive — it 应用ears in every error message. For multi-代理 设置ups, 设置 代理_WORKSPACE to a unique path per 代理 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 访问 controls in place. 设置 记录_LEVEL=调试 during development to see every operation 记录ged to stderr. MCP Config Snippet (Claude Code / Claude 桌面) { "mcpServers": { "light-fs-mcp": { "command": "uv", "args": ["运行", "/absolute/path/to/light-fs-mcp/server.py"], "env": { "代理_WORKSPACE": "/Users/you/代理-workspace" } } } }

安装ation & Publishing (ClawHub) Submit to ClawHub

ClawHub expects a 技能.md wi