root_mcp.extended.tools package

Extended MCP tools for analysis operations.

class root_mcp.extended.tools.AnalysisTools(config, file_manager, path_validator, analysis_ops, tree_reader)

Bases: object

Tools for physics analysis operations.

Parameters:

• config (Config)

• file_manager (FileManager)

• path_validator (PathValidator)

• analysis_ops (AnalysisOperations)

• tree_reader (TreeReader)

__init__(config, file_manager, path_validator, analysis_ops, tree_reader)

Initialize analysis tools.

Parameters:

• config (Config) – Server configuration

• file_manager (FileManager) – File manager instance

• path_validator (PathValidator) – Path validator instance

• analysis_ops (AnalysisOperations) – Analysis operations instance

• tree_reader (TreeReader) – Tree reader instance

apply_selection(path, tree, selection, defines=None)

Count entries passing a selection.

Parameters:

• path (str) – File path

• tree (str) – Tree name

• selection (str) – Cut expression

• defines (dict[str, str] | None) – Optional variable definitions

Returns:

Selection statistics

Return type:

dict[str, Any]

compute_histogram(path, tree_name, branch, bins, range=None, selection=None, weights=None, defines=None)

Compute a 1D histogram.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branch (str) – Branch to histogram

• bins (int) – Number of bins

• range (tuple[float, float] | None) – (min, max) for histogram

• selection (str | None) – Optional cut expression

• weights (str | None) – Optional weight branch

• defines (dict[str, str] | None) – Optional variable definitions

Returns:

Histogram data and metadata

Return type:

dict[str, Any]

compute_histogram_2d(path, tree_name, x_branch, y_branch, x_bins, y_bins, x_range=None, y_range=None, selection=None, defines=None)

Compute a 2D histogram.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• x_branch (str) – X-axis branch

• y_branch (str) – Y-axis branch

• x_bins (int) – Number of bins in x

• y_bins (int) – Number of bins in y

• x_range (tuple[float, float] | None) – (min, max) for x-axis

• y_range (tuple[float, float] | None) – (min, max) for y-axis

• selection (str | None) – Optional cut expression

• defines (dict[str, str] | None) – Optional variable definitions

Returns:

2D histogram data and metadata

Return type:

dict[str, Any]

compute_histogram_arithmetic(operation, data1, data2)

Perform histogram arithmetic.

Parameters:

• operation (str) – Operation name

• data1 (dict[str, Any]) – First histogram

• data2 (dict[str, Any]) – Second histogram

Return type:

dict[str, Any]

compute_kinematics(path, tree, computations, selection=None, limit=None)

Compute kinematic quantities from four-momenta.

Parameters:

• path (str) – File path

• tree (str) – Tree name

• computations (list[dict[str, Any]]) – List of kinematic calculations. Each entry is a dict with keys name (output variable name), type (one of invariant_mass, invariant_mass_squared, transverse_mass, delta_r, delta_phi), particles (list of branch prefixes, e.g. ['K', 'pi1']), and optionally components (component suffixes; defaults vary by type).

• selection (str | None) – Optional cut expression

• limit (int | None) – Maximum entries to process

Returns:

Dictionary with computed kinematic quantities

Return type:

dict[str, Any]

export_branches(path, tree, branches, output_path, output_format, selection=None, limit=None)

Export branch data to a file.

Parameters:

• path (str) – File path

• tree (str) – Tree name

• branches (list[str]) – Branches to export

• output_path (str) – Destination file path

• output_format (str) – Output format (json, csv, parquet)

• selection (str | None) – Optional cut expression

• limit (int | None) – Maximum entries to export

Returns:

Export metadata

Return type:

dict[str, Any]

fit_histogram(model, data=None, path=None, tree_name=None, branch=None, bins=None, range=None, selection=None, weights=None, defines=None, initial_guess=None, bounds=None, fixed_parameters=None)

Fit a histogram to a model. Can either take existing histogram data or compute it from a file.

Parameters:

• model (str | list[str | dict[str, Any]] | dict[str, Any]) – Model configuration

• data (dict[str, Any] | None) – Optional histogram data (from compute_histogram)

• path (str | None) – File path (if data not provided)

• tree_name (str | None) – Tree name (if data not provided)

• branch (str | None) – Branch to histogram (if data not provided)

• bins (int | None) – Number of bins (if data not provided)

• range (tuple[float, float] | None) – Histogram range (optional)

• selection (str | None) – Cut expression (optional)

• weights (str | None) – Weight branch (optional)

• defines (dict[str, str] | None) – Variable definitions (optional)

• initial_guess (list[float] | None) – Initial parameters for fit

• bounds (list[list[float]] | None) – Parameter bounds

• fixed_parameters (dict[str | int, float] | None) – Fixed parameters

Returns:

Fit results

Return type:

dict[str, Any]

generate_plot(data, plot_type='histogram', fit_data=None, options=None)

Generate a plot.

Parameters:

• data (dict[str, Any]) – Analysis data

• plot_type (str) – Plot type

• fit_data (dict[str, Any] | None) – Optional fit to overlay

• options (dict[str, Any] | None) – Plot settings

Returns:

Plot image data

Return type:

dict[str, Any]

class root_mcp.extended.tools.PlottingTools(config, file_manager, path_validator, histogram_ops)

Bases: object

Tools for creating plots from ROOT data.

Parameters:

• config (Config)

• file_manager (FileManager)

• path_validator (PathValidator)

• histogram_ops (HistogramOperations)

__init__(config, file_manager, path_validator, histogram_ops)

Initialize plotting tools.

Parameters:

• config (Config) – Server configuration

• file_manager (FileManager) – File manager instance

• path_validator (PathValidator) – Path validator instance

• histogram_ops (HistogramOperations) – Histogram operations instance

plot_histogram_1d(data=None, path=None, tree_name=None, branch=None, bins=None, range=None, selection=None, weights=None, defines=None, output_path='/tmp/histogram.png', title=None, xlabel=None, ylabel='Events', log_y=False, style='default')

Create a 1D histogram plot.

Parameters:

• data (dict[str, Any] | None) – Pre-calculated histogram data (optional)

• path (str | None) – File path (optional if data provided)

• tree_name (str | None) – Tree name (optional if data provided)

• branch (str | None) – Branch to histogram (optional if data provided)

• bins (int | None) – Number of bins (optional if data provided)

• range (tuple[float, float] | None) – (min, max) for histogram

• selection (str | None) – Optional cut expression

• weights (str | None) – Optional weight branch

• defines (dict[str, str] | str | None) – Optional variable definitions (dict or JSON string)

• output_path (str) – Where to save the plot

• title (str | None) – Plot title (default: branch name)

• xlabel (str | None) – X-axis label (default: branch name)

• ylabel (str) – Y-axis label

• log_y (bool) – Use logarithmic y-axis

• style (str) – Plot style (“default”, “publication”, “presentation”)

Returns:

Plot metadata including path and statistics

Return type:

dict[str, Any]

plot_histogram_2d(data=None, path=None, tree_name=None, branch_x=None, branch_y=None, bins_x=None, bins_y=None, range_x=None, range_y=None, selection=None, weights=None, defines=None, output_path='/tmp/histogram_2d.png', title=None, xlabel=None, ylabel=None, colormap='viridis', log_z=False, style='default')

Create a 2D histogram plot.

Parameters:

• data (dict[str, Any] | None) – Pre-calculated histogram data (optional)

• path (str | None) – File path (optional if data provided)

• tree_name (str | None) – Tree name (optional if data provided)

• branch_x (str | None) – X-axis branch (optional if data provided)

• branch_y (str | None) – Y-axis branch (optional if data provided)

• bins_x (int | None) – Number of bins in X (optional if data provided)

• bins_y (int | None) – Number of bins in Y (optional if data provided)

• range_x (tuple[float, float] | None) – (min, max) for X axis

• range_y (tuple[float, float] | None) – (min, max) for Y axis

• selection (str | None) – Optional cut expression

• weights (str | None) – Optional weight branch

• defines (dict[str, str] | str | None) – Optional variable definitions (dict or JSON string)

• output_path (str) – Where to save the plot

• title (str | None) – Plot title

• xlabel (str | None) – X-axis label

• ylabel (str | None) – Y-axis label

• colormap (str) – Matplotlib colormap name

• log_z (bool) – Use logarithmic color scale

• style (str) – Plot style

Returns:

Plot metadata including path and statistics

Return type:

dict[str, Any]

class root_mcp.extended.tools.RootNativeTools(config)

Bases: object

MCP tool handler for native ROOT/PyROOT code execution.

This tool is only registered when both: - config.features.enable_root is True - Native ROOT/PyROOT is detected as available

Parameters:

config (Config) – Server configuration.

__init__(config)

Parameters:

config (Config)

Return type:

None

run_rdataframe(file_path, tree_name, branch, bins, range_min, range_max, selection=None, weight=None, output_path=None, timeout=None)

Compute a 1D histogram using RDataFrame.

This is a convenience wrapper around run_root_code that generates RDataFrame code from parameters, avoiding the need to write PyROOT boilerplate.

Parameters:

• file_path (str) – Path to the ROOT file.

• tree_name (str) – Name of the TTree or RNTuple.

• branch (str) – Branch to histogram.

• bins (int) – Number of bins.

• range_min (float) – Histogram range.

• range_max (float) – Histogram range.

• selection (str | None) – Optional cut expression (C++ syntax).

• weight (str | None) – Optional weight column name.

• output_path (str | None) – If provided, save histogram plot to this path.

• timeout (int | None) – Execution timeout in seconds.

Returns:

Structured result with histogram data.

Return type:

dict

run_root_code(code, output_dir=None, timeout=None, input_files=None)

Execute PyROOT/Python code and return structured results.

Parameters:

• code (str) – Python code to execute (may import ROOT).

• output_dir (str | None) – Directory for output files (optional).

• timeout (int | None) – Execution timeout in seconds (optional, overrides config default).

• input_files (list[str] | None) – Paths to ROOT files the code needs access to.

Returns:

Structured result with status, stdout, stderr, output_files, etc.

Return type:

dict

run_root_macro(macro_code, output_path=None, timeout=None)

Execute a ROOT C++ macro via gROOT.ProcessLine.

Parameters:

• macro_code (str) – C++ code to execute.

• output_path (str | None) – If provided, save any canvas output to this path.

• timeout (int | None) – Execution timeout in seconds.

Returns:

Structured result.

Return type:

dict

Submodules

• root_mcp.extended.tools.analysis module
  • AnalysisTools
    • AnalysisTools.__init__()
    • AnalysisTools.apply_selection()
    • AnalysisTools.compute_histogram()
    • AnalysisTools.compute_histogram_2d()
    • AnalysisTools.compute_histogram_arithmetic()
    • AnalysisTools.compute_kinematics()
    • AnalysisTools.export_branches()
    • AnalysisTools.fit_histogram()
    • AnalysisTools.generate_plot()
• root_mcp.extended.tools.plotting module
  • PlottingTools
    • PlottingTools.__init__()
    • PlottingTools.plot_histogram_1d()
    • PlottingTools.plot_histogram_2d()
• root_mcp.extended.tools.root_native module
  • RootNativeTools
    • RootNativeTools.__init__()
    • RootNativeTools.run_rdataframe()
    • RootNativeTools.run_root_code()
    • RootNativeTools.run_root_macro()