Filesystem MCP server with read-before-write enforcement. More...

#include <entropic/mcp/servers/filesystem.h>

Inheritance diagram for entropic::FilesystemServer:

Collaboration diagram for entropic::FilesystemServer:

[legend]

Public Member Functions
	FilesystemServer (const std::filesystem::path &root_dir, const FilesystemConfig &config, const std::string &data_dir, int model_context_bytes=0)
	Construct with root directory, config, and data dir.

	~FilesystemServer () override
	Destructor (default, unique_ptr cleanup).

bool	skip_duplicate_check (const std::string &tool_name) const override
	read_file must always execute (updates FileAccessTracker).

bool	set_working_dir (const std::string &path) override
	Set working directory (changes root_dir).

const std::filesystem::path &	root_dir () const
	Get the root directory.

FileAccessTracker &	tracker ()
	Get the file access tracker.

const FilesystemConfig &	config () const
	Get the filesystem config.

int	max_read_bytes () const
	Get max read bytes (size gate).

std::filesystem::path	resolve_path (const std::string &requested) const
	Resolve and validate a path against root.

const IgnoreMatcher &	ignore () const
	Get the ignore matcher (#15, v2.1.4).

Public Member Functions inherited from entropic::MCPServerBase
	MCPServerBase (std::string name)
	Construct with server name.

const std::string &	name () const
	Get the server name.

void	register_tool (ToolBase *tool)
	Register a tool with this server.

std::string	list_tools () const
	List all registered tools as a JSON array string.

std::string	execute (const std::string &tool_name, const std::string &args_json)
	Execute a tool and wrap result in ServerResponse JSON.

virtual std::string	get_permission_pattern (const std::string &tool_name, const std::string &args_json) const
	Generate permission pattern for 'Always Allow/Deny'.

virtual bool	configure (const std::string &config_json)
	Configure the server after creation.

const ToolRegistry &	registry () const
	Get the tool registry (const).

Additional Inherited Members
Protected Attributes inherited from entropic::MCPServerBase
std::string	name_
	Server name.

ToolRegistry	registry_
	Tool registry.

Detailed Description

Filesystem MCP server with read-before-write enforcement.

Version: 1.8.5

Definition at line 65 of file filesystem.h.

Constructor & Destructor Documentation

◆ FilesystemServer()

entropic::FilesystemServer::FilesystemServer	(	const std::filesystem::path &	root_dir,
		const FilesystemConfig &	config,
		const std::string &	data_dir,
		int	model_context_bytes = `0`
	)

Construct with root directory, config, and data dir.

Construct filesystem server, create and register all tools.

Parameters

root_dir	Project root directory.
config	Filesystem configuration.
data_dir	Path to bundled data directory (for tool JSONs).
model_context_bytes	Model context window in bytes (for size gate).

Version: 1.8.5

Issue #15 (v2.1.4): also loads .gitignore + .explorerignore via the IgnoreMatcher member so glob/grep/read filter ignored paths.

Parameters

root_dir	Project root directory — canonicalised here, and the boundary every tool's paths are confined to.
config	Filesystem configuration.
data_dir	Path to bundled data directory.
model_context_bytes	Model context window in bytes. @req REQ-MCP-001 @req REQ-MCP-021 @req REQ-MCP-022

Version: 2.3.7

Definition at line 1439 of file filesystem.cpp.

◆ ~FilesystemServer()

entropic::FilesystemServer::~FilesystemServer ( )

overridedefault

Destructor (default, unique_ptr cleanup).

@dg_internal

Version: 1.8.5

Member Function Documentation

◆ config()

const FilesystemConfig & entropic::FilesystemServer::config ( ) const

Get the filesystem config.

Returns: Config reference.

Version: 1.8.5

Returns: Config reference. @dg_internal

Version: 1.8.5

Definition at line 1597 of file filesystem.cpp.

◆ ignore()

const IgnoreMatcher & entropic::FilesystemServer::ignore ( ) const

Get the ignore matcher (#15, v2.1.4).

Loaded from .gitignore (recursive) + .explorerignore at server construction and on set_working_dir. Used by glob, grep, and read_file to filter results / refuse access.

Returns: Matcher reference.

Version: 2.1.4

Returns: Read-only reference to the loaded .gitignore + .explorerignore rule set that glob, grep and read_file all consult. @req REQ-MCP-022

Version: 2.1.4

Definition at line 1587 of file filesystem.cpp.

◆ max_read_bytes()

int entropic::FilesystemServer::max_read_bytes ( ) const

Get max read bytes (size gate).

Get max read bytes for size gate.

Returns: Max bytes, or 0 for unlimited.

Version: 1.8.5

Returns: The read size limit in bytes, or 0 for unlimited — a file over the limit is refused with size_exceeded. @req REQ-MCP-021

Version: 1.8.5

Definition at line 1608 of file filesystem.cpp.

◆ resolve_path()

fs::path entropic::FilesystemServer::resolve_path ( const std::string & requested ) const

Resolve and validate a path against root.

Resolve and validate a path against root directory.

Parameters

requested User-requested path.

Returns: Resolved canonical path.

Exceptions

std::runtime_error if path escapes root.

Version: 1.8.5

Resolves relative paths against root_dir_, canonicalizes, and checks that the result does not escape root. Throws on escape unless allow_outside_root is configured.

Containment uses lexically_relative so that "/home/user/project" does not falsely contain "/home/user/projectile" via string-prefix.

The single confinement point every filesystem tool goes through, so no tool can traverse outside the project.

Parameters

requested User-requested path string (absolute or relative to the root).

Returns: The canonical path when it lies under the root — or anywhere, when allow_outside_root is configured.

Exceptions

std::runtime_error when the canonical result leaves the root, logged as "Path escape blocked". @req REQ-MCP-021

Version: 2.1.1-rc1

Definition at line 1634 of file filesystem.cpp.

◆ root_dir()

const fs::path & entropic::FilesystemServer::root_dir ( ) const

Get the root directory.

Returns: Root directory path.

Version: 1.8.5

Returns: The canonical root every requested path is resolved against and confined to. @req REQ-MCP-021

Version: 1.8.5

Definition at line 1564 of file filesystem.cpp.

◆ set_working_dir()

bool entropic::FilesystemServer::set_working_dir ( const std::string & path )

overridevirtual

Set working directory (changes root_dir).

Set working directory by updating root_dir.

Parameters

path	New root directory.

Returns: true on success.

Version: 1.8.5

Issue #15 (v2.1.4): also reloads IgnoreMatcher rules so the new root's .gitignore + .explorerignore take effect immediately.

Parameters

path	New root directory.

Returns: true when the path is a directory, in which case the server is re-rooted AND the ignore rules are reloaded from the new root; false when it is not, leaving the server untouched. @req REQ-MCP-021 @req REQ-MCP-022

Version: 2.1.4

Reimplemented from entropic::MCPServerBase.

Definition at line 1542 of file filesystem.cpp.

◆ skip_duplicate_check()

bool entropic::FilesystemServer::skip_duplicate_check ( const std::string & tool_name ) const

overridevirtual

read_file must always execute (updates FileAccessTracker).

read_file always executes (updates FileAccessTracker).

Parameters

tool_name Tool name.

Returns: true for read_file.

Version: 1.8.5

read_file must run even when repeated, because its side effect — recording the read in the tracker — is what unlocks a later write.

Parameters

tool_name Tool name to check.

Returns: true for "read_file", false for every other filesystem tool, which stay duplicate-checked. @req REQ-MCP-015 @req REQ-MCP-021

Version: 1.8.5

Reimplemented from entropic::MCPServerBase.

Definition at line 1523 of file filesystem.cpp.

◆ tracker()

FileAccessTracker & entropic::FilesystemServer::tracker ( )

Get the file access tracker.

Returns: Tracker reference.

Version: 1.8.5

Returns: Mutable reference to the read-before-write tracker shared by read_file (which records) and write_file (which enforces). @req REQ-MCP-021

Version: 1.8.5

Definition at line 1575 of file filesystem.cpp.

The documentation for this class was generated from the following files:

entropic/mcp/servers/filesystem.h
mcp/servers/filesystem.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FilesystemServer()

◆ ~FilesystemServer()

Member Function Documentation

◆ config()

◆ ignore()

◆ max_read_bytes()

◆ resolve_path()

◆ root_dir()

◆ set_working_dir()

◆ skip_duplicate_check()

◆ tracker()