Filesystem Tools

MCP tools for multi-project filesystem operations — read, write, search, and navigate files across multiple project directories from a single MCP server.

Installation

- name: dependency.repl
  kind: ns.dependency
  component: butschster/fs-tools
  version: ">=0.1.0"

Tools

Project Management

Tool	Description
projects_list	List all registered projects with paths and descriptions

File Operations

Tool	Description
file_read	Read one or more files (supports line ranges and batch reads)
file_write	Write content to a file, optionally creating parent directories
file_search	Search for text/regex patterns with context lines
file_replace_content	Replace a unique text occurrence in a file
file_insert_content	Insert content at specific line numbers
file_delete_content	Delete lines or line ranges from a file

Directory Operations

Tool	Description
directory_list	List files/directories with glob patterns, depth control, and tree view

All file tools accept an optional project parameter to target a specific project. Without it, the default project is used.

Adding Projects

Projects are fs.directory entries in _index.yaml with mcp.project metadata:

- name: project.myapp
  kind: fs.directory
  directory: /path/to/myapp
  meta:
    mcp.project: true
    mcp.project.name: "myapp"
    mcp.project.description: "My Application"

Set mcp.project.default: true on exactly one project to make it the default.

Architecture

fs_tools/
├── _index.yaml            Project volumes + tool entries
├── wippy.yaml             Module metadata
├── projects.lua           Shared library: project resolution via registry
├── projects_list.lua      Tool: list projects
├── file_read.lua          Tool: read files
├── file_write.lua         Tool: write files
├── file_search.lua        Tool: search in files
├── file_replace_content.lua   Tool: replace text
├── file_insert_content.lua    Tool: insert at line
├── file_delete_content.lua    Tool: delete lines
├── directory_list.lua     Tool: list directory contents
└── README.md

All tools import fs_tools:projects_lib which handles project resolution from the registry. The library uses fs and registry modules to locate fs.directory entries with mcp.project metadata.