root_mcp.config module

Configuration management for ROOT-MCP server.

class root_mcp.config.AnalysisConfig(*args, **kwargs)

Bases: BaseModel

Analysis operation settings.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

default_chunk_size: int = 10000

default_read_limit: int = 1000

class root_mcp.config.CacheConfig(*args, **kwargs)

Bases: BaseModel

File-handle cache settings.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

enabled: bool = True

file_cache_size: int = 50

class root_mcp.config.Config(*args, **kwargs)

Bases: BaseModel

Root configuration for ROOT-MCP server.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

get_default_resource()

Get the first configured resource (default).

Return type:

ResourceConfig | None

get_resource(name)

Get resource configuration by name.

Parameters:

name (str)

Return type:

ResourceConfig | None

class root_mcp.config.CoreConfig(*args, **kwargs)

Bases: BaseModel

Core mode configuration.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

class root_mcp.config.ExtendedConfig(*args, **kwargs)

Bases: BaseModel

Extended mode configuration.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

fitting_max_iterations: int = 10000

class root_mcp.config.FeatureFlags(*args, **kwargs)

Bases: BaseModel

Feature toggles.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

enable_export: bool = True

enable_root: bool = False

class root_mcp.config.HistogramConfig(*args, **kwargs)

Bases: BaseModel

Histogram-specific settings.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

max_bins_1d: int = 10000

max_bins_2d: int = 1000

class root_mcp.config.LimitsConfig(*args, **kwargs)

Bases: BaseModel

Resource limits for safety.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

max_export_rows: int = 10000000

max_rows_per_call: int = 1000000

class root_mcp.config.OutputConfig(*args, **kwargs)

Bases: BaseModel

Output and export settings.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

export_base_path: str = '/tmp/root_mcp_output'

validate_export_path()

Ensure export path is absolute.

class root_mcp.config.PlottingConfig(*args, **kwargs)

Bases: BaseModel

Plotting and visualization settings.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

data_color: str = 'black'

default_format: str = 'png'

dpi: int = 100

error_bar_cap_size: float = 2.0

figure_height: float = 6.0

figure_width: float = 10.0

fit_line_color: str = 'red'

fit_line_style: str = '-'

grid_alpha: float = 0.3

grid_enabled: bool = True

hist_fill_alpha: float = 0.2

hist_fill_color: str = 'blue'

line_width: float = 2.0

marker_size: float = 4.0

marker_style: str = 'o'

class root_mcp.config.ResourceConfig(*args, **kwargs)

Bases: BaseModel

Configuration for a data resource (MCP root).

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

description: str = ''

name: str

uri: str

validate_name()

Ensure resource name is valid.

class root_mcp.config.RootNativeConfig(*args, **kwargs)

Bases: BaseModel

Configuration for native ROOT/PyROOT execution.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

execution_timeout: int = 60

max_code_length: int = 100000

max_output_size: int = 10000000

working_directory: str = '/tmp/root_mcp_native'

class root_mcp.config.SecurityConfig(*args, **kwargs)

Bases: BaseModel

Security and access control settings.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

allow_remote: bool = False

effective_protocols(resources)

Return the union of explicitly allowed protocols and protocols inferred from the URI scheme of declared resources.

This means a resource with uri: "root://…" automatically permits the root protocol without requiring allow_remote: true or manually adding root to allowed_protocols.

Parameters:

resources (list) – List of ResourceConfig objects (pass config.resources).

Returns:

Deduplicated list of permitted protocol strings.

Return type:

list[str]

max_path_depth: int = 10

validate_roots()

Ensure allowed roots are absolute paths.

An empty list is valid and means permissive / zero-config mode: the server will allow access to any path the OS permits.

class root_mcp.config.ServerConfig(*args, **kwargs)

Bases: BaseModel

Server-level settings.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

mode: str = 'extended'

name: str = 'root-mcp'

root_mcp.config.apply_cli_overrides(config, args)

Apply parsed CLI arguments onto config in-place.

CLI flags are the highest-priority source — they override both YAML and env vars. This function only mutates a field when the corresponding args attribute is explicitly set (not None).

** Server & Mode**:

• args.mode → Config.server.mode

• args.server_name → Config.server.name

** Security**:

• args.allowed_root → Config.security.allowed_roots (list; replaces)

• args.allow_remote → Config.security.allow_remote (True/False/None)

• args.allowed_protocols → Config.security.allowed_protocols (comma-string, split on parse)

• args.max_path_depth → Config.security.max_path_depth

** Output / Export**:

• args.export_path → Config.output.export_base_path

• args.export_formats → Config.output.allowed_formats (comma-string)

• args.enable_export → Config.features.enable_export (False when --no-export is given, None when not specified)

** Core Limits & Cache**:

• args.max_rows → Config.core.limits.max_rows_per_call

• args.max_export_rows → Config.core.limits.max_export_rows

• args.cache_enabled → Config.core.cache.enabled (False when --no-cache is given, None when not specified)

• args.cache_size → Config.core.cache.file_cache_size

** Extended Analysis**:

• args.max_bins_1d → Config.extended.histogram.max_bins_1d

• args.max_bins_2d → Config.extended.histogram.max_bins_2d

• args.fitting_iterations → Config.extended.fitting_max_iterations

• args.plot_dpi → Config.extended.plotting.dpi

• args.plot_format → Config.extended.plotting.default_format

• args.plot_width → Config.extended.plotting.figure_width

• args.plot_height → Config.extended.plotting.figure_height

** Native ROOT Execution**:

• args.root_timeout → Config.root_native.execution_timeout

• args.root_workdir → Config.root_native.working_directory

• args.root_max_output → Config.root_native.max_output_size

• args.root_max_code → Config.root_native.max_code_length

** Remote Resources**:

• args.resource → Config.resources (repeated NAME=URI[|DESCRIPTION] specs; YAML-declared URIs take precedence via deduplication)

Parameters:

• config (Config) – The Config to update in-place.

• args (Namespace) – Parsed argparse.Namespace from the server’s argument parser.

Returns:

The same config object (mutated) for convenience.

Raises:

ValueError – When a CLI flag contains an invalid value.

Return type:

Config

root_mcp.config.apply_data_paths(config, paths)

Merge a list of local directory paths into config as resources.

Each path is added as a new ResourceConfig only when no existing resource already points to the same URI (YAML-declared resources take precedence). When security.allowed_roots is non-empty (restrictive mode), the path is also appended there so the validator permits access.

This is the shared building block used by both the --data-path CLI flag and the ROOT_MCP_DATA_PATH environment variable.

Parameters:

• config (Config) – The Config to update in-place.

• paths (list[str]) – List of local directory paths (resolved to absolute).

Returns:

The same config object (mutated) for convenience.

Return type:

Config

root_mcp.config.apply_env_overrides(config)

Read ROOT_MCP_* environment variables and merge into config in-place.

Env vars sit between the YAML file (priority 2) and CLI flags (priority 4) in the merge chain — i.e. an env var overrides the YAML but is itself overridden by an explicit --flag on the command line.

Only non-empty env vars are applied; missing or empty vars leave the corresponding field untouched.

** Server & Mode**:

• ROOT_MCP_MODE → Config.server.mode (core or extended)

• ROOT_MCP_SERVER_NAME → Config.server.name

** Security**:

• ROOT_MCP_ALLOWED_ROOTS → Config.security.allowed_roots (colon-separated paths; replaces the YAML list)

• ROOT_MCP_ALLOW_REMOTE → Config.security.allow_remote (1/true/yes → True)

• ROOT_MCP_ALLOWED_PROTOCOLS → Config.security.allowed_protocols (comma-separated; replaces the YAML list)

• ROOT_MCP_MAX_PATH_DEPTH → Config.security.max_path_depth (positive integer)

Output / Export:

• ROOT_MCP_EXPORT_PATH → Config.output.export_base_path (directory string)

• ROOT_MCP_EXPORT_FORMATS → Config.output.allowed_formats (comma-separated; replaces the YAML list)

• ROOT_MCP_ENABLE_EXPORT → Config.features.enable_export (1/true/yes → True, anything else → False)

** Core Limits & Cache**:

• ROOT_MCP_MAX_ROWS → Config.core.limits.max_rows_per_call (positive int)

• ROOT_MCP_MAX_EXPORT_ROWS → Config.core.limits.max_export_rows (positive int)

• ROOT_MCP_CACHE → Config.core.cache.enabled (1/true/yes → True, anything else → False)

• ROOT_MCP_CACHE_SIZE → Config.core.cache.file_cache_size (positive int)

** Extended Analysis**:

• ROOT_MCP_MAX_BINS_1D → Config.extended.histogram.max_bins_1d (positive int)

• ROOT_MCP_MAX_BINS_2D → Config.extended.histogram.max_bins_2d (positive int)

• ROOT_MCP_FITTING_ITERATIONS → Config.extended.fitting_max_iterations (positive int)

• ROOT_MCP_PLOT_DPI → Config.extended.plotting.dpi (positive int)

• ROOT_MCP_PLOT_FORMAT → Config.extended.plotting.default_format (png, pdf, or svg)

• ROOT_MCP_PLOT_WIDTH → Config.extended.plotting.figure_width (positive float)

• ROOT_MCP_PLOT_HEIGHT → Config.extended.plotting.figure_height (positive float)

** Native ROOT Execution**:

• ROOT_MCP_ROOT_TIMEOUT → Config.root_native.execution_timeout (positive int, seconds)

• ROOT_MCP_ROOT_WORKDIR → Config.root_native.working_directory (path string)

• ROOT_MCP_ROOT_MAX_OUTPUT → Config.root_native.max_output_size (positive int, bytes)

• ROOT_MCP_ROOT_MAX_CODE → Config.root_native.max_code_length (positive int, chars)

** Remote Resources**:

• ROOT_MCP_RESOURCES → Config.resources (semicolon-sep list of NAME=URI or NAME=URI|DESCRIPTION specs; YAML-declared URIs take precedence via deduplication)

Parameters:

config (Config) – The Config to update in-place.

Returns:

The same config object (mutated) for convenience.

Raises:

ValueError – When an env var contains an invalid value (e.g. an unrecognised mode string).

Return type:

Config

root_mcp.config.apply_log_level(level_str)

Set the Python root logger’s level.

This is called in main() before load_config() so that log messages emitted during configuration loading and all subsequent startup already respect the requested verbosity.

Parameters:

level_str (str) – Case-insensitive level name. Accepted values: DEBUG, INFO, WARNING, ERROR.

Raises:

ValueError – When level_str is not one of the accepted names.

Return type:

None

root_mcp.config.create_default_config(output_path, data_path=None, permissive=True)

Generate a minimal, human-readable config.yaml.

The output uses the same two-tier format as root-mcp init: a short QUICK START section with the only field most users need to change, followed by an ADVANCED section with fine-tuning knobs.

Parameters:

• output_path (str | Path) – Destination file path.

• data_path (Path | None) – Local directory to use as the resource URI. When None and permissive is True, defaults to the current working directory. When None and permissive is False, writes a placeholder that the user must edit before use.

• permissive (bool) – When True (default), security.allowed_roots is left empty (allow any OS-readable path). Ignored when data_path is None and permissive is False.

Return type:

None

root_mcp.config.load_config(config_path=None)

Load configuration from YAML file.

After loading (or using built-in defaults when no file is found), the ROOT_MCP_DATA_PATH environment variable is checked. Any colon-separated directory paths it contains are merged into the config as resources via apply_data_paths(), exactly as if those directories had been passed via --data-path on the CLI. YAML-declared resources always take precedence over env-var paths; CLI --data-path flags (applied in main()) take precedence over both.

Config merge priority (ascending — later wins):

1. Built-in Pydantic defaults

2. ROOT_MCP_DATA_PATH environment variable

3. --data-path CLI flags (applied in main())

4. YAML config file values

Parameters:

config_path (str | Path | None) – Path to config file. If None, looks for: 1. ROOT_MCP_CONFIG env var 2. ./config.yaml 3. ~/.config/root-mcp/config.yaml

Returns:

Validated Config object

Return type:

Config