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

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

Inheritance diagram for entropic::FilesystemServer:

[legend]

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.

bool	release_session (const std::string &key) override
	Release `key`'s recorded reads (gh#158).

std::size_t	session_count () const override
	Sessions whose reads this server currently tracks (gh#158).

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, PathAccess access, const std::string &tool) const
	Resolve a path and apply the outside-root policy (v2.13.0).

void	set_outside_root_approver (OutsideRootApprover fn, void *user_data)
	Install the approver consulted under `optional` (v2.13.0).

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 &raw_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).

Public Member Functions inherited from entropic::SessionStateOwner
virtual	~SessionStateOwner ()=default
	Virtual destructor for a polymorphic mixin.

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.

gh#158 (v2.13.0): also a SessionStateOwner — its read tracker is per session, and the facade releases a session's reads with its conversation.

Version: 2.13.0

Definition at line 153 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.13.0

Definition at line 2053 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 2237 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 2227 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 2248 of file filesystem.cpp.

◆ release_session()

bool entropic::FilesystemServer::release_session ( const std::string & key )

overridevirtual

Release key's recorded reads (gh#158).

Release a session's recorded reads (gh#158).

Parameters

key	Session key.

Returns: true when the session had recorded reads.

Version: 2.13.0

Parameters

key	Session key.

Returns: true when the session had recorded reads. @req REQ-MCP-021 @req REQ-LOOP-009

Version: 2.13.0

Implements entropic::SessionStateOwner.

Definition at line 2205 of file filesystem.cpp.

◆ resolve_path()

fs::path entropic::FilesystemServer::resolve_path	(	const std::string &	requested,
		PathAccess	access,
		const std::string &	tool
	)		const

Resolve a path and apply the outside-root policy (v2.13.0).

Resolve a path and apply the outside-root policy.

The single confinement point for every path-taking tool. A path under the root is served. One outside it is decided by, in order: outside_root_deny, outside_root_allow, then allow_outside_root (false refuse / true serve / optional ask the approver).

Parameters

requested	User-requested path (absolute or root-relative).
access	Whether the calling tool reads or writes it.
tool	Bare tool name, for the approval request and logs.

Returns: Resolved canonical path.

Exceptions

std::runtime_error on any refusal — thrown rather than returned so MCPServerBase's barrier also skips the ContextAnchor for a refused read.

Version: 2.13.0

Resolves relative paths against root_dir_ and canonicalizes. A result under the root is served. One outside it goes to authorize_outside_root, which throws on any refusal.

Containment uses lexically_relative so that "/home/user/project" does not falsely contain "/home/user/projectile" via string-prefix — and the SAME test decides the outside-root allow/deny subtrees.

The single confinement point every path-taking filesystem tool goes through, so no tool can reach outside the project without the policy saying so.

Parameters

requested	User-requested path string (absolute or relative to the root).
access	Whether the calling tool reads or writes the path.
tool	Bare calling tool name (e.g. "write_file").

Returns: The canonical path when it lies under the root, or when the outside-root policy served it.

Exceptions

std::runtime_error when the policy refuses the path — thrown, so MCPServerBase's barrier returns it as a tool error AND skips the ContextAnchor a refused read must not get. @req REQ-MCP-021

Version: 2.13.0

Definition at line 2279 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 2181 of file filesystem.cpp.

◆ session_count()

std::size_t entropic::FilesystemServer::session_count ( ) const

overridevirtual

Sessions whose reads this server currently tracks (gh#158).

Sessions whose reads this server tracks (gh#158).

Returns: Session count.

Version: 2.13.0

Returns: Session count. @req REQ-LOOP-009

Version: 2.13.0

Implements entropic::SessionStateOwner.

Definition at line 2215 of file filesystem.cpp.

◆ set_outside_root_approver()

void entropic::FilesystemServer::set_outside_root_approver	(	OutsideRootApprover	fn,
		void *	user_data
	)

Install the approver consulted under optional (v2.13.0).

NOT installed on a named workspace's servers, which are confined unconditionally (gh#166). Thread-safe against a concurrent call.

Parameters

fn	Approver, or nullptr to clear (escapes then refuse with `outside_root_approval_required`).
user_data	Forwarded to `fn`.

Version: 2.13.0

Parameters

fn	Approver, or nullptr to clear.
user_data	Forwarded to `fn`. @req REQ-MCP-021

Version: 2.13.0

Definition at line 2377 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.13.0

Reimplemented from entropic::MCPServerBase.

Definition at line 2157 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 2138 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), both under the calling session's key (gh#158). @req REQ-MCP-021

Version: 1.8.5

Definition at line 2193 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()

◆ release_session()

◆ resolve_path()

◆ root_dir()

◆ session_count()

◆ set_outside_root_approver()

◆ set_working_dir()

◆ skip_duplicate_check()

◆ tracker()