Overview
========

``mcp_pykingenie`` exposes ``pykingenie`` surface-based binding kinetics
workflows through the Model Context Protocol. This MCP server is only for
surface-based binding data, such as Octet and Gator BLI experiments. It
provides tools for importing experiments, aligning association and dissociation
phases, subtracting reference sensors, preparing fitting datasets, running
kinetic fits, plotting traces, and inspecting fitted parameters.

Basic Workflow
--------------

The typical workflow for surface-based binding kinetics analysis is:

1. Import an Octet or Gator experiment.
2. Align the association phase.
3. Align the dissociation phase.
4. Subtract a reference sensor.
5. Inspect the sample information table.
6. Select traces and generate fitting datasets.
7. Run either a steady-state fitting model or a kinetic fitting model.
8. Plot fitted curves and retrieve fitting results, when running kinetic fitting.

Importing Data
--------------

Data can be imported from absolute paths or from paths relative to the active
MCP data directory. Use ``print_data_dir`` to see that directory. Relative-path
imports are useful when you first place or copy input files into the server's
date-stamped data folder.

Supported import paths are:

* ``load_octet_example`` loads the packaged Octet BLI example and is the
  quickest way to test the full workflow. Users can also download the same raw
  example data as :download:`octet_bli_example_data.zip
  <_static/downloads/octet_bli_example_data.zip>`.
* ``import_octet_experiment`` imports an Octet folder containing ``.frd`` files
  and the sample plate metadata files produced by the Octet software.
* ``import_gator_experiment`` imports a Gator folder or ``.zip`` archive. The
  folder/archive should contain the channel CSV files plus ``Setting.ini`` and
  ``ExperimentStep.ini``. Zip archives are extracted into the active MCP data
  directory before loading.
* ``import_kingenie_surface_csv`` imports a KinGenie surface-simulation CSV.
  The CSV should contain surface trace columns such as ``Time``, ``Signal``,
  ``Smax``, and ``Analyte_concentration_micromolar_constant``.

Each import tool stores the loaded experiment in the in-memory
``pykingenie.KineticsAnalyzer`` under the supplied experiment name. Use
``list_experiment_names`` after importing to confirm what is available for
alignment, subtraction, plotting, and fitting.

MCP Tools
---------

The server keeps a ``pykingenie.KineticsAnalyzer`` instance in memory for the
current MCP session. Generated plots are written to the active data directory,
which defaults to ``~/user_data_mcp_pykingenie/<YYYY-MM-DD>/``. Set
``RESULTS_DIR`` before starting the server to choose a different root folder.
Use the ``print_data_dir`` tool to display the exact folder used by the running
server.

Example Chat Flow
-----------------

Once connected through your MCP client, ask your AI assistant to run a flow
like:

.. code-block:: text

   1. load the Octet example experiment
   2. align the association phase
   3. align the dissociation phase
   4. subtract the sensor H1
   5. plot all the steps
   6. show me the sample information
   7. create a fitting dataset using sample wt - imd
   8. run kinetic fitting with a one-to-one model
   9. plot the fitted curves

Local Development
-----------------

For local MCP clients that support the ``mcp.json`` convention, point the
server command at the repository:

.. code-block:: json

   {
     "mcpServers": {
       "mcp_pykingenie": {
         "command": "uv",
         "args": ["run", "--directory", "/absolute/path/to/mcp_pykingenie", "mcp_pykingenie"]
       }
     }
   }

Citation
--------

If you use ``mcp_pykingenie``, please cite it as:

Burastero, O. (2026). ``mcp_pykingenie`` (Version 1.0) [Computer software].
GitHub. https://github.com/osvalB/mcp_pykingenie

.. code-block:: bibtex

   @software{burastero_2026_mcp_pykingenie,
     author = {Burastero, Osvaldo},
     title = {mcp_pykingenie},
     version = {1.0},
     year = {2026},
     url = {https://github.com/osvalB/mcp_pykingenie}
   }