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.