API Reference

Package

Command Line

class mcp_pykingenie.main.EnvironmentType(*values)[source]

Bases: Enum

Enum to define environment type.

PRODUCTION = 1
DEVELOPMENT = 2
mcp_pykingenie.main.run_development_transport(mcp, transport: str, port: int, hostname: str)[source]

Run the configured development transport.

Server State

mcp_pykingenie.server.build_server_instructions(data_dir: str) → str[source]

Return MCP server instructions including the active output folder.

MCP Server

Stdio Transport

Stdio helpers for running the MCP server.

mcp_pykingenie.stdio.stdio_server_ignoring_empty_lines(stdin: AsyncIterator[str] | None = None, stdout: Any | None = None)[source]

Create an MCP stdio transport that ignores blank inbound lines.

Parameters:

  • stdin (AsyncIterator[str] | None) – Optional stdin stream. If None, the process stdin is used.

  • stdout (Any | None) – Optional stdout stream. If None, the process stdout is used.

async mcp_pykingenie.stdio.run_stdio_ignoring_empty_lines(server: Any, show_banner: bool = True, log_level: str | None = None, stateless: bool = False, stdio_context: Any | None = None) → None[source]

Run a FastMCP server over stdio while ignoring blank inbound lines.

Parameters:

  • server (Any) – FastMCP server instance to run.

  • show_banner (bool) – Whether to display the FastMCP server banner.

  • log_level (str | None) – Temporary log level to use while the server runs.

  • stateless (bool) – Whether to run without session initialization state.

  • stdio_context (Any | None) – Optional async context manager factory that yields read/write streams.

mcp_pykingenie.stdio.run_stdio(server: Any, **kwargs: Any) → None[source]

Synchronously run a FastMCP server with the hardened stdio transport.

Parameters:

  • server (Any) – FastMCP server instance to run.

  • **kwargs (Any) – Keyword arguments forwarded to run_stdio_ignoring_empty_lines.

Tools

mcp_pykingenie.tools._pykingenie.resolve_experiment_name(experiment_id: str) → str | None[source]

Resolve a PyKinGenie experiment name from a name or 1-based index.

Parameters:

experiment_id (str) – Experiment name or 1-based index in PY_KINETICS.experiment_names.

Returns:

The resolved experiment name, or None when the selector is invalid.

Return type:

str or None

mcp_pykingenie.tools._pykingenie.current_hour_min_sec()[source]

Get the current time in HH-MM-SS format.

Returns:

Current time as a string.

Return type:

str

mcp_pykingenie.tools._pykingenie.import_octet_experiment_base(folder: str = '.', exp_name: str = 'Experiment') → str[source]

Import Octet BLI data into the shared PyKinGenie analyzer.

The folder is read with pykingenie.OctetExperiment. PyKinGenie parses the .frd sensor traces and sample plate metadata, then the resulting experiment is registered in PY_KINETICS.

Parameters:

  • folder (str) – Absolute path or DATA_DIR-relative folder containing Octet files.

  • exp_name (str) – Name used when storing the experiment in the analyzer.

Returns:

Confirmation message naming the imported folder.

Return type:

str

mcp_pykingenie.tools._pykingenie.print_data_dir() → str[source]

Print the path to the data directory, where the generated files will be stored.

Returns:

The path to the data directory.

Return type:

str

mcp_pykingenie.tools._pykingenie.list_files_in_folder(folder: str = '') → list[source]

List all files in the selected folder.

Parameters:

folder (str) – The folder to list files from.

Returns:

A list of file names in the data directory.

Return type:

list

mcp_pykingenie.tools._pykingenie.import_kingenie_surface_csv(csv: str, exp_name: str = 'Experiment') → str[source]

Import a KinGenie surface-simulation CSV into the analyzer.

The CSV is parsed with pykingenie.KinGenieCsv. It should contain exported surface-simulation columns such as Time, Signal, Smax, and Analyte_concentration_micromolar_constant; a Cycle column is supported for single-cycle data. If exp_name already exists, a numeric suffix is appended before storing the experiment in PY_KINETICS.

Parameters:

  • csv (str) – Absolute path or DATA_DIR-relative path to the simulation CSV file.

  • exp_name (str) – Requested experiment name in the analyzer.

Returns:

Confirmation message naming the imported CSV path.

Return type:

str

mcp_pykingenie.tools._pykingenie.import_octet_experiment(folder: str = '.', exp_name: str = 'Experiment') → str[source]

Import an Octet experiment folder into the shared PyKinGenie analyzer.

This wraps pykingenie.OctetExperiment, loading sensor traces and sample plate metadata before adding the experiment to PY_KINETICS.

Parameters:

  • folder (str) – Absolute path or DATA_DIR-relative folder containing Octet files.

  • exp_name (str) – Name used when storing the experiment in the analyzer.

Returns:

Confirmation message naming the imported folder.

Return type:

str

mcp_pykingenie.tools._pykingenie.import_gator_experiment(folder: str = '.', exp_name: str = 'Experiment') → str[source]

Import Gator BLI data into the shared PyKinGenie analyzer.

Folder contents are parsed with pykingenie.GatorExperiment, which reads experiment steps, settings, and sensor-channel CSV traces. If a zip file is provided, it is extracted under DATA_DIR and then read as a folder.

Parameters:

  • folder (str) – Absolute path or DATA_DIR-relative folder or zip file containing Assay_#_Channel#.csv files plus Setting.ini and ExperimentStep.ini.

  • exp_name (str) – Name used when storing the experiment in the analyzer.

Returns:

Confirmation message naming the imported folder or zip stem.

Return type:

str

mcp_pykingenie.tools._pykingenie.load_octet_example() → str[source]

Load the packaged Octet example into the shared analyzer.

The bundled BLI example is imported through the same pykingenie.OctetExperiment path as import_octet_experiment and stored as "Example Experiment".

Returns:

Confirmation message naming the packaged example folder.

Return type:

str

mcp_pykingenie.tools._pykingenie.plot_sample_plate_info(experiment_id: str = '1', font_size: int = 18, save_html: bool = False) → str[source]

Save a PyKinGenie sample-plate layout plot for one experiment.

The plot is produced by pykingenie.plot_plate_info() and written as a PNG in DATA_DIR. The experiment may be selected by name or by 1-based analyzer index.

Parameters:

  • experiment_id (str) – The name or index of the experiment to plot. If a number is provided, it will be used to select the experiment by its index.

  • font_size (int) – The font size for the plot annotations.

  • save_html (bool) – If True, saves the plot as an HTML file for interactive viewing.

Returns:

Message containing the saved PNG path.

Return type:

str

mcp_pykingenie.tools._pykingenie.get_legends_table() → str[source]

Build a plotting legend table from PyKinGenie sensor metadata.

Sensor names and unique sensor IDs are collected with PY_KINETICS.get_experiment_properties and converted with pykingenie.get_plotting_df().

Returns:

JSON records for a DataFrame with Internal_ID, Color, Legend, and Show columns.

Return type:

str

async mcp_pykingenie.tools._pykingenie.plot_traces_with_all_steps(legends_df: str = '', plot_width: int = 26, plot_height: int = 24, plot_type: str = 'png', font_size: int = 18, show_grid_x: bool = True, show_grid_y: bool = True, marker_size: int = 3, line_width: int = 2, save_html: bool = False) → str[source]

Save a PyKinGenie plot containing all loaded trace steps.

The plot is produced by pykingenie.plot_traces_all() using a legend table created by get_legends_table or supplied as JSON records. It can include baseline, loading, association, dissociation, and regeneration segments present in the imported experiments.

Parameters:

  • legends_df (str) – A JSON string representing the legend DataFrame.

  • plot_width (int) – Plot width forwarded to PyKinGenie/Plotly.

  • plot_height (int) – Plot height forwarded to PyKinGenie/Plotly.

  • plot_type (str) – Type of the plot to generate ('png', 'svg', 'jpeg').

  • font_size (int) – Font size for the plot annotations.

  • show_grid_x (bool) – Whether to show grid lines on the x-axis.

  • show_grid_y (bool) – Whether to show grid lines on the y-axis.

  • marker_size (int) – Size of the markers in the plot.

  • line_width (int) – Width of the lines in the plot.

  • save_html (bool) – Whether to save the plot as an HTML file for interactive viewing.

Returns:

Message containing the saved image path.

Return type:

str

async mcp_pykingenie.tools._pykingenie.plot_steady_state(plot_width: int = 26, plot_height: int = 24, plot_type: str = 'png', font_size: int = 18, show_grid_x: bool = True, show_grid_y: bool = True, marker_size: int = 3, line_width: int = 2, save_html: bool = False) → str[source]

Save a PyKinGenie steady-state plot for generated fittings.

This calls pykingenie.plot_steady_state() with plot_fit=True and requires fitting datasets generated by initiate_fitting_datasets.

Parameters:

  • plot_width (int) – Plot width forwarded to PyKinGenie/Plotly.

  • plot_height (int) – Plot height forwarded to PyKinGenie/Plotly.

  • plot_type (str) – Type of the plot to generate ('png', 'svg', 'jpeg').

  • font_size (int) – Font size for the plot annotations.

  • show_grid_x (bool) – Whether to show grid lines on the x-axis.

  • show_grid_y (bool) – Whether to show grid lines on the y-axis.

  • marker_size (int) – Size of the markers in the plot.

  • line_width (int) – Width of the lines in the plot.

  • save_html (bool) – Whether to save the plot as an HTML file for interactive viewing.

Returns:

Message containing the saved image path.

Return type:

str

mcp_pykingenie.tools._pykingenie.list_experiment_names() → list[source]

Get the names of all experiments in the pykinetics analyzer.

Returns:

A list of experiment names.

Return type:

list

mcp_pykingenie.tools._pykingenie.align_association(experiment_id: str = '1', sensor_names: list = [], in_place: bool = True, new_names: bool = False) → str[source]

Align association phases for selected sensors in a PyKinGenie experiment.

This calls SurfaceBasedExperiment.align_association. PyKinGenie subtracts the signal before association from the selected traces and updates trace arrays, sensor names, and ligand metadata according to in_place and new_names.

Parameters:

  • experiment_id (str) – The name of the experiment to align. If a number is provided, it will be used to select the experiment by its index.

  • sensor_names (list) – Sensor names to align. If empty, all sensors in the experiment are used.

  • in_place (bool) – If True, modifies the existing sensors; if False, creates new sensors.

  • new_names (bool) – If True, uses new names for the aligned sensors.

Returns:

A confirmation message.

Return type:

str

mcp_pykingenie.tools._pykingenie.subtract_reference(experiment_id: str = '1', list_of_sensor_names: list = [], reference_sensor: str = '1', inplace: bool = True) → str[source]

Subtract a reference sensor from selected PyKinGenie sensor traces.

This calls SurfaceBasedExperiment.subtraction and updates trace arrays, sensor names, and ligand metadata. The reference sensor may be named directly or selected by 1-based sensor index.

Parameters:

  • experiment_id (str) – The name of the experiment to subtract the reference from. If a number is provided, it will be used to select the experiment by its index.

  • list_of_sensor_names (list) – A list of sensor names to subtract the reference from. If no names are provided, all sensors except the reference will be used.

  • reference_sensor (str) – The name of the reference sensor to subtract. If a number is provided, it will be used to select the sensor by its index.

  • inplace (bool) – If True, modifies the existing sensors; if False, creates new sensors.

Returns:

A confirmation message.

Return type:

str

mcp_pykingenie.tools._pykingenie.subtract_experiment(experiment_id: str = '1', reference_experiment_id: str = '2', inplace: bool = True) → str[source]

Subtract one surface-based experiment from another sensor by sensor.

This calls SurfaceBasedExperiment.subtract_experiment on the selected target experiment. PyKinGenie sorts sensor names alphanumerically and subtracts each matching sensor trace from the reference experiment. Both experiments must have the same number of sensors and compatible time data.

Parameters:

  • experiment_id (str) – Name or 1-based index of the experiment to modify.

  • reference_experiment_id (str) – Name or 1-based index of the experiment to subtract from experiment_id.

  • inplace (bool) – If True, modifies the target experiment; if False, creates new sensors.

Returns:

A confirmation message with the updated target sensor names.

Return type:

str

mcp_pykingenie.tools._pykingenie.subtract_sensor_columns(experiment_id: str = '1', sensors_column_one: int = 1, sensors_column_two: int = 2, inplace: bool = True) → str[source]

Subtract one column of sensors from another in a surface experiment.

This calls SurfaceBasedExperiment.subtraction_by_column. PyKinGenie finds sensor names containing sensors_column_one and subtracts the corresponding sensor obtained by replacing that column number with sensors_column_two.

Parameters:

  • experiment_id (str) – Name or 1-based index of the experiment to modify.

  • sensors_column_one (int) – Column number of the sensors to subtract from.

  • sensors_column_two (int) – Column number of the reference sensors to subtract.

  • inplace (bool) – If True, modifies the target sensors; if False, creates new sensors.

Returns:

A confirmation message listing PyKinGenie’s subtraction messages and updated sensor names.

Return type:

str

mcp_pykingenie.tools._pykingenie.align_dissociation(experiment_id: str = '1', sensor_names: list = [], in_place: bool = True, new_names: bool = False, npoints: int = 10) → str[source]

Align dissociation phases for selected sensors in a PyKinGenie experiment.

This calls SurfaceBasedExperiment.align_dissociation. PyKinGenie smooths or offsets traces around association-to-dissociation transitions and updates trace arrays, sensor names, and ligand metadata according to in_place and new_names.

Parameters:

  • experiment_id (str) – The name of the experiment to align. If a number is provided, it will be used to select the experiment by its index.

  • sensor_names (list) – A list of sensor names to align. If no names are provided, all sensors in the experiment will be used.

  • in_place (bool) – If True, modifies the existing sensors; if False, creates new sensors.

  • new_names (bool) – If True, uses new names for the aligned sensors.

  • npoints (int) – Number of points PyKinGenie uses around alignment positions.

Returns:

A confirmation message.

Return type:

str

mcp_pykingenie.tools._pykingenie.align_and_subtract(experiment_id: str = '1', reference_sensor: str = '1', align_dissociation: bool = False) → str[source]

Align traces and subtract a reference sensor in one PyKinGenie workflow.

The selected experiment is association-aligned in place, optionally dissociation-aligned in place, and then all non-reference sensors are reference-subtracted in place.

Parameters:

  • experiment_id (str) – The name of the experiment. If a number is provided, it will be used to select the experiment by its index.

  • reference_sensor (str) – The name of the reference sensor to subtract. If a number is provided, it will be used to select the sensor by its index.

  • align_dissociation (bool) – If True, aligns the dissociation phase of the sensors after subtraction.

Returns:

A confirmation message.

Return type:

str

mcp_pykingenie.tools._pykingenie.obtain_sample_info_table() → str[source]

Return merged PyKinGenie sample metadata as JSON records.

This calls PY_KINETICS.merge_ligand_conc_df across loaded experiments. The resulting table can be edited and passed to initiate_fitting_datasets to choose traces, concentrations, sample names, replicates, and Smax grouping.

Returns:

JSON records for the merged ligand-concentration DataFrame.

Return type:

str

mcp_pykingenie.tools._pykingenie.initiate_fitting_datasets(json_str: str) → str[source]

Generate PyKinGenie fitting objects from sample metadata JSON.

A template for the JSON representation can be generated using the obtain_sample_info_table tool. The user can edit the JSON string to select only the data they want to fit, change analyte concentrations, change sample names, and alter Smax grouping. Existing fitting objects are reset before PY_KINETICS.generate_fittings is called.

Parameters:

json_str (str) – JSON string representing the DataFrame.

Returns:

A message listing the names of the generated fitting datasets.

Return type:

str

async mcp_pykingenie.tools._pykingenie.plot_kinetic_traces(plot_width: int = 26, plot_height: int = 24, plot_type: str = 'png', font_size: int = 16, show_grid_x: bool = True, show_grid_y: bool = True, marker_size: int = 3, line_width: int = 2, split_by_smax_id: bool = False, max_points_per_plot: int = 1000, smooth_curves_fit: bool = False, rolling_window: int = 10, save_html: bool = False) → str[source]

Save a PyKinGenie association/dissociation plot for fittings.

Requires that the fitting datasets have been generated using the initiate_fitting_datasets tool. The ligand concentrations are colored by PyKinGenie, and fitted curves are included when fitting results are present.

Parameters:

  • plot_width (int) – Plot width forwarded to PyKinGenie/Plotly.

  • plot_height (int) – Plot height forwarded to PyKinGenie/Plotly.

  • plot_type (str) – Type of the plot to generate ('png', 'svg', 'jpeg').

  • font_size (int) – Font size for the plot annotations.

  • show_grid_x (bool) – Whether to show grid lines on the x-axis.

  • show_grid_y (bool) – Whether to show grid lines on the y-axis.

  • marker_size (int) – Size of the markers in the plot.

  • line_width (int) – Width of the lines in the plot.

  • split_by_smax_id (bool) – If True, splits the plots by Smax ID.

  • max_points_per_plot (int) – Maximum number of points per plot. If exceeded, data will be subsetted.

  • smooth_curves_fit (bool) – If True, asks PyKinGenie to smooth fitted curves.

  • rolling_window (int) – Rolling-window value forwarded to PyKinGenie for smoothing.

  • save_html (bool) – If True, saves the plot as an HTML file for interactive viewing.

Returns:

Message containing the saved image path.

Return type:

str

async mcp_pykingenie.tools._pykingenie.run_steady_state_fitting(steady_state_model: str = 'one_to_one', fit_sigma: bool = False) → str[source]

Run PyKinGenie steady-state fitting for generated fitting datasets.

This calls PY_KINETICS.submit_steady_state_fitting to fit concentration-response data independently from kinetic trace fitting.

Parameters:

  • steady_state_model (str) – Steady-state model to fit. PyKinGenie accepts 'one_to_one' and 'two_to_one'.

  • fit_sigma (bool) – If True with 'two_to_one' steady-state fitting, fit the shared cooperativity factor sigma.

Returns:

A confirmation message with the steady-state fitting settings used.

Return type:

str

async mcp_pykingenie.tools._pykingenie.run_kinetics_fitting(fitting_model: str = 'one_to_one', fitting_region: str = 'association_dissociation', linked_smax: bool = False, fit_sigma: bool = False) → str[source]

Run PyKinGenie kinetic fitting for generated fitting datasets.

This calculates the starting values required by PyKinGenie internally, then calls PY_KINETICS.submit_kinetics_fitting with the selected kinetic model, fitted region, Smax sharing setting, and optional two-site cooperativity setting. Use run_steady_state_fitting separately only when you want a standalone steady-state fit.

Parameters:

  • fitting_model (str) – Kinetic model to fit. PyKinGenie accepts 'one_to_one', 'one_to_one_mtl' (mass transport limitation), 'one_to_one_if' (induced fit), and 'two_to_one'. Only 'one_to_one' supports every fitting region; the other kinetic models support only 'association_dissociation'.

  • fitting_region (str) – The region of the data to be fitted. 'one_to_one' supports 'association_dissociation', 'association', and 'dissociation'. 'one_to_one_mtl', 'one_to_one_if', and 'two_to_one' support only 'association_dissociation'.

  • linked_smax (bool) – Whether to link the Smax values across curves, i.e. assume the same sensor capacity.

  • fit_sigma (bool) – If True with 'two_to_one' kinetic fitting, fit the shared cooperativity factor sigma.

Returns:

A confirmation message with the kinetic fitting settings used.

Return type:

str

mcp_pykingenie.tools._pykingenie.get_kinetics_fitting_results() → str[source]

Return PyKinGenie kinetic fitting results as JSON records.

This calls PY_KINETICS.get_fitting_results and serializes fit_params_kinetics_all, which contains fitted parameters such as Kd, k_off, k_on, and Smax when available.

Returns:

A JSON string representing the fitting results.

Return type:

str

mcp_pykingenie.tools._pykingenie.create_export_df(export_type: str = 'raw') → str[source]

Return exported PyKinGenie association/dissociation traces as JSON records.

This calls PY_KINETICS.create_export_df for all generated fitting objects. Raw export returns the measured association and dissociation signals; fitted export returns fitted curves after run_kinetics_fitting has been called.

Parameters:

export_type (str) – Signal type to export. Accepts 'raw', 'fit', or 'fitted'. 'fitted' is normalized to PyKinGenie’s 'fit' spelling.

Returns:

JSON records for a DataFrame with exported trace points.

Return type:

str

mcp_pykingenie.tools._pykingenie.list_experiment_properties(variable: str, fittings: bool = False) → list[source]

Get a PyKinGenie property from all experiments or fittings.

This is a direct wrapper around PY_KINETICS.get_experiment_properties.

Parameters:

  • variable (str) – The attribute to retrieve, e.g., 'ligand_concentration', 'sensor_names', etc.

  • fittings (bool) – If True, returns attributes from the fitting objects instead of the experiments.

Returns:

A list of values for the specified variable from the experiments or fittings.

Return type:

list

mcp_pykingenie.tools._pykingenie.list_experiment_attributes(experiment_name: str) → dict[source]

Return all stored attributes for one PyKinGenie experiment.

Run this tool only if the user asks for it specifically.

Parameters:

experiment_name (str) – The name of the experiment to list attributes for. If a number is provided, it will be used to select the experiment by its index.

Returns:

A dictionary of experiment attributes.

Return type:

dict