/ 
Langertha-Raider-0.504
/ Langertha::Raider::FileTools

NAME

Langertha::Raider::FileTools - MCP::Server factory with local filesystem tools (list/read/write/edit/multi_edit)

VERSION

version 0.504

DESCRIPTION

The file tools of raider: an MCP::Server with list_files(path), read_file(path, offset, limit, pages), write_file(path, content), edit_file(path, old_string, new_string, replace_all) and multi_edit(path, edits), which answer as Claude Code's Read, Write, Edit and MultiEdit do (ADR 0023): the same result and error texts, the same error flag.

  • read_file returns the file in cat -n form (line number, a tab, the line), at most 2000 lines unless limit says otherwise, from line offset (1-based); a line longer than 2000 characters is cut; a result of more than 25000 tokens (a token counted as four bytes) is refused. With pages ("3", "1-5", at most 20 pages) a PDF is read as text through pdftotext (poppler) for any model; a PDF of more than 10 pages must be read that way. An image (PNG, JPEG, GIF, WebP) or a PDF comes back as image or document content when the model can take it in a tool result (sees_images for images, reads_pdf for PDFs), a Jupyter notebook as its cells with their outputs; other binary files, directories and devices are refused with a message.

  • Read before write. write_file, edit_file and multi_edit refuse to change a file that exists but was not read in this run, or that changed on disk since it was read (Langertha::Raider::FileTools::ReadState). A new file needs no read; what the tools wrote counts as read.

  • edit_file replaces old_string where it occurs exactly once, or every occurrence with replace_all; multi_edit applies several such edits one after the other to the content in memory and writes only when all of them apply.

build_file_tools_server

my $server = Langertha::Raider::FileTools::build_file_tools_server(
    root        => '/some/dir',      # optional confinement root
    extra_roots => [ '/other/dir' ], # optional: more directories allowed
    # or a CodeRef returning the list, asked on every call:
    # extra_roots => sub { [ '/other/dir' ] },
    confine     => 1,                # default; 0 (or a CodeRef) lets the gate decide
    read_state  => $state,           # optional Langertha::Raider::FileTools::ReadState
    sees_images => sub { 1 },        # optional: may images go back as content
    reads_pdf   => sub { 1 },        # optional: may PDFs go back as content
);

Returns an MCP::Server instance with the tools list_files, read_file, write_file, edit_file and multi_edit registered. Relative paths are read against root. When root is set and confine is true (the default), all path arguments are confined to that directory and the extra_roots (the additional directories of ADR 0021). Existing paths and nearest existing parents are resolved with realpath, so symlinks cannot be used to escape them. An extra root that does not exist is left out. extra_roots may be a CodeRef that returns the list (or an ArrayRef); it is called on every tool call, so the application can change the additional directories while the server is mounted (/reload).

confine may be a CodeRef, asked on every call. False means the tools reach any path: the application does so in the Claude layout, where the permission gate asks before a path outside the root and the additional directories (ADR 0023) -- never without a gate.

read_state is the record of the files read in this run; without one the server keeps its own, which is never emptied. sees_images (a value or a CodeRef asked on every call, default true) says whether an image (and a notebook's output images) may go back as content; reads_pdf (same shape, default true) says the same for a PDF. They are independent: a model can take one and not the other (the application asks the engine's tool_result_images and tool_result_pdf capabilities). What is not taken is refused with a message; a PDF read by pages is text and needs neither.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-raider/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

https://raudssus.de/