Concrete base class for MCP servers (80% logic). More...

#include <entropic/mcp/server_base.h>

Inheritance diagram for entropic::MCPServerBase:

[legend]

Collaboration diagram for entropic::MCPServerBase:

Public Member Functions
	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	skip_duplicate_check (const std::string &tool_name) const
	Check if a tool should skip duplicate detection.

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

virtual bool	set_working_dir (const std::string &path)
	Set the working directory.

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

Protected Attributes
std::string	name_
	Server name.

ToolRegistry	registry_
	Tool registry.

Detailed Description

Concrete base class for MCP servers (80% logic).

Owns a ToolRegistry. Provides:

Tool registration via register_tool()
Tool listing via list_tools() → JSON array
Tool dispatch via execute() → ServerResponse JSON envelope
Automatic ContextAnchor injection when a tool declares anchor_key()
Permission pattern generation (virtual, default: "server.tool_name")
Duplicate check skip (virtual, default: false)
Working directory management (virtual, default: no-op)
Configuration via configure() (virtual, default: no-op)

Concrete servers (FilesystemServer, BashServer, etc.) subclass and:

Create ToolBase subclasses for each tool
Register them in the constructor
Override get_permission_pattern() / skip_duplicate_check() as needed

Lifecycle: auto server = std::make_unique<FilesystemServer>();

server->configure(config_json); // server-specific init

server->list_tools(); // JSON array of tool defs

auto result = server->execute("read_file", args_json);

entropic::OutsideRootAccess::optional
@ optional
optional: every escape asks the host's path approver

Version: 1.8.5

Definition at line 66 of file server_base.h.

Constructor & Destructor Documentation

◆ MCPServerBase()

entropic::MCPServerBase::MCPServerBase ( std::string name )

explicit

Construct with server name.

Parameters

name	Server name (e.g., "filesystem", "bash", "git").

Version: 1.8.5

Parameters

name	Server name. @dg_internal

Version: 1.8.5

Definition at line 25 of file server_base.cpp.

Member Function Documentation

◆ configure()

bool entropic::MCPServerBase::configure ( const std::string & config_json )

virtual

Configure the server after creation.

Default configure: no-op.

Parameters

config_json JSON configuration string.

Returns: true on success.

Version: 1.8.5

Default: no-op, returns true. Override for server-specific init.

Extension point with a safe default so a server needing no configuration is not forced to implement one.

Parameters

config_json Configuration JSON (unused in the default).

Returns: true — the no-op default always succeeds. @req REQ-MCP-001

Version: 1.8.5

Definition at line 246 of file server_base.cpp.

◆ execute()

std::string entropic::MCPServerBase::execute	(	const std::string &	tool_name,
		const std::string &	raw_args_json
	)

Execute a tool and wrap result in ServerResponse JSON.

Execute a tool and return ServerResponse JSON.

Parameters

tool_name	Tool name (without server prefix).
raw_args_json	JSON string of arguments, as supplied.

Returns: ServerResponse JSON envelope string. An unknown tool, or one that throws, yields the envelope with error text in result and no directives — never a throw (gh#143).

Version: 2.12.0

Flow:

Normalise non-object arguments to {} (gh#143)
Dispatch to registered ToolBase::execute()
If tool declares anchor_key(): auto-inject ContextAnchor directive
Serialize to JSON ServerResponse envelope

Steps 2-3 run under an exception barrier, so a throwing tool neither escapes nor gets its arguments anchored into context.

The base owns the whole dispatch path — registry lookup, automatic ContextAnchor injection for any tool declaring an anchor_key, and envelope serialisation — so a concrete server that overrides nothing still produces the exact shape the DirectiveProcessor parses.

gh#143 (v2.12.0): a tool that THROWS is answered the same way as an unknown one — the exception becomes error text in result. This is the in-process counterpart of gh#133's ServerManager::route_plugin_call, which already guarantees that a misbehaving PLUGIN server "becomes a normal tool error rather than an exception unwinding through the loop". In-process servers had no equivalent, so an unhandled throw — a .value() on a non-object (type_error.306), a missing .at() key (out_of_range.403) — escaped four uncaught hops up to run_as_inner and aborted the entire turn. The model never saw the failure and could not correct it.

The barrier is HERE rather than in ToolRegistry::dispatch so that a throwing tool also skips inject_anchor_if_needed. A tool that failed must not have its arguments recorded as a ContextAnchor: for FilesystemServer a rejected path traversal would otherwise be anchored into context as though it had been legitimately read.

Parameters

tool_name	Tool name (without server prefix).
args_json	JSON arguments.

Returns: ServerResponse JSON envelope: a string result plus a directives array (empty when the tool has no side effects). An unknown tool, or one that throws, yields the same envelope with error text in result rather than a throw — and with no directives, anchor included. @req REQ-MCP-001 @req REQ-MCP-002

Version: 2.12.0

Definition at line 165 of file server_base.cpp.

◆ get_permission_pattern()

std::string entropic::MCPServerBase::get_permission_pattern	(	const std::string &	tool_name,
		const std::string &	args_json
	)		const

virtual

Generate permission pattern for 'Always Allow/Deny'.

Default permission pattern: tool-level.

Parameters

tool_name	Fully-qualified tool name (e.g., "filesystem.read_file").
args_json	Tool call arguments as JSON string.

Returns: Permission pattern string.

Version: 1.8.5

Default: returns tool_name (tool-level granularity). Override in subclasses for finer granularity.

One of the four extension points with a safe default. A server that wants coarser or finer "always allow" granularity (BashServer keys on the base command) overrides this; everyone else inherits tool-level.

Parameters

tool_name	Fully-qualified tool name.
args_json	Tool arguments (unused in the default — the default granularity is deliberately argument-independent).

Returns: tool_name as-is, i.e. tool-level permission granularity. @req REQ-MCP-001 @req REQ-MCP-009

Version: 1.8.5

Reimplemented in entropic::BashServer.

Definition at line 209 of file server_base.cpp.

◆ list_tools()

std::string entropic::MCPServerBase::list_tools ( ) const

List all registered tools as a JSON array string.

List all registered tools as JSON array.

Returns: JSON array of tool definitions.

Version: 1.8.5

Non-virtual: ServerManager concatenates this across every in-process server so the model sees one flat tool list.

Returns: JSON array string — one object per registered tool carrying name, description and inputSchema; "[]" when nothing is registered. @req REQ-MCP-001 @req REQ-MCP-007

Version: 1.8.5

Definition at line 68 of file server_base.cpp.

◆ name()

const std::string & entropic::MCPServerBase::name ( ) const

Get the server name.

Returns: Server name string.

Version: 1.8.5

Returns: Server name. @dg_internal

Version: 1.8.5

Definition at line 34 of file server_base.cpp.

◆ register_tool()

void entropic::MCPServerBase::register_tool ( ToolBase * tool )

Register a tool with this server.

Parameters

tool	Non-owning pointer. Server does NOT take ownership.

Version: 1.8.5

Registration is the one thing every concrete server does in its constructor; the base owns the registry so a subclass cannot lose dispatch, envelope shape, or anchoring by forgetting to wire them.

Parameters

tool	Tool pointer (non-owning; the server retains ownership of the tool objects themselves). @req REQ-MCP-001 @req REQ-MCP-003

Version: 1.8.5

Definition at line 51 of file server_base.cpp.

◆ registry()

const ToolRegistry & entropic::MCPServerBase::registry ( ) const

inline

Get the tool registry (const).

Returns: Reference to this server's tool registry. @utility

Version: 1.9.4

Definition at line 171 of file server_base.h.

◆ set_working_dir()

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

virtual

Set the working directory.

Default set_working_dir: no-op.

Parameters

path	New working directory path.

Returns: true on success.

Version: 1.8.5

Default: no-op, returns true. Override in directory-aware servers.

Extension point with a safe default — only directory-aware servers (filesystem, bash, git) need to re-root.

Parameters

path	Working directory (unused in the default).

Returns: true — the no-op default always succeeds. @req REQ-MCP-001

Version: 1.8.5

Reimplemented in entropic::BashServer, entropic::FilesystemServer, and entropic::GitServer.

Definition at line 261 of file server_base.cpp.

◆ skip_duplicate_check()

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

virtual

Check if a tool should skip duplicate detection.

Default: do not skip duplicate check.

Parameters

tool_name Local tool name (without server prefix).

Returns: true if duplicate check should be skipped.

Version: 1.8.5

Override for tools with side effects that must always execute (e.g., read_file updates FileAccessTracker).

Extension point with a safe default — a server opts an individual tool out only when the tool must always run for its side effect (filesystem.read_file updates the read tracker; entropic.delegate and entropic.pipeline are legitimately repeatable).

Parameters

tool_name Tool name (unused in the default).

Returns: false — every tool is duplicate-checked unless a subclass says otherwise. @req REQ-MCP-001 @req REQ-MCP-015

Version: 1.8.5

Reimplemented in entropic::EntropicServer, and entropic::FilesystemServer.

Definition at line 230 of file server_base.cpp.

Member Data Documentation

◆ name_

std::string entropic::MCPServerBase::name_

protected

Server name.

Definition at line 174 of file server_base.h.

◆ registry_

ToolRegistry entropic::MCPServerBase::registry_

protected

Tool registry.

Definition at line 175 of file server_base.h.

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

entropic/mcp/server_base.h
mcp/server_base.cpp

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ MCPServerBase()

Member Function Documentation

◆ configure()

◆ execute()

◆ get_permission_pattern()

◆ list_tools()

◆ name()

◆ register_tool()

◆ registry()

◆ set_working_dir()

◆ skip_duplicate_check()

Member Data Documentation

◆ name_

◆ registry_