Metadata-Version: 2.4
Name: mcp_pykingenie
Version: 1.0.0
Summary: MCP_PYKINGENIE is a MCP server that provides tools for the analysis of binding kinetics data.
Project-URL: Documentation, https://osvalb.github.io/mcp_pykingenie/
Project-URL: Homepage, https://github.com/osvalB/mcp_pykingenie
Project-URL: Source, https://github.com/osvalB/mcp_pykingenie
Author: Osvaldo Burastero
Maintainer-email: Osvaldo Burastero <oburastero@gmail.com>
License: 
        MIT License
        
        Copyright (c) 2026, Osvaldo Burastero
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: click
Requires-Dist: fastmcp
Requires-Dist: kaleido>=1.2.0
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: numpy>=2.4.3
Requires-Dist: pandas>=3.0.1
Requires-Dist: plotly>=6.6.0
Requires-Dist: pykingenie>=1.0.0
Requires-Dist: scipy>=1.17.1
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: twine>=4.0.2; extra == 'dev'
Provides-Extra: doc
Requires-Dist: docutils!=0.18.*,!=0.19.*,>=0.8; extra == 'doc'
Requires-Dist: ipykernel; extra == 'doc'
Requires-Dist: ipython; extra == 'doc'
Requires-Dist: nbsphinx; extra == 'doc'
Requires-Dist: numpydoc; extra == 'doc'
Requires-Dist: pandas; extra == 'doc'
Requires-Dist: setuptools; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-design; extra == 'doc'
Requires-Dist: sphinx-rtd-theme; extra == 'doc'
Requires-Dist: sphinx-tabs; extra == 'doc'
Requires-Dist: sphinx>=8.1; extra == 'doc'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Description-Content-Type: text/markdown

# mcp_pykingenie

[![Tests][badge-tests]][tests]
[![Documentation][badge-docs]][documentation]

[badge-tests]: https://img.shields.io/github/actions/workflow/status/osvalB/mcp_pykingenie/test.yaml?branch=main&label=tests
[badge-docs]: https://img.shields.io/github/actions/workflow/status/osvalB/mcp_pykingenie/docs.yaml?branch=main&label=docs

This repository contains a local MCP server for the analysis of surface-based binding kinetics data from Octet and Gator experiments.
It is based on the Python package [pykingenie](https://github.com/osvalB/pykingenie).

## Demo videos

- [Example with Visual Studio Code](https://drive.google.com/file/d/1PtUdFNThLG6F2T55cUc4p69JeCwhSrNs/view?usp=drive_link)
- [Example with Claude](https://drive.google.com/file/d/1iXqUMakI-m5Vrpya-cI7e0YT6krsfvbn/view?usp=drive_link)

## Installation

We recommend running mcp_pykingenie with [uv][].

### Run from the command line

```bash
uvx mcp_pykingenie
```

By default, generated plots and relative-path input data are stored in
`~/user_data_mcp_pykingenie/<YYYY-MM-DD>/`. To choose a different results
folder, set `RESULTS_DIR` before starting the server. Use the `print_data_dir`
MCP tool to inspect the active output folder for a running server.

```bash
RESULTS_DIR=~/Documents/user_data_mcp_pykingenie uvx mcp_pykingenie
```

### Configure an MCP client

Add the server to any MCP-compatible client that supports the `mcpServers`
configuration format:

```json
{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uvx",
      "args": ["mcp_pykingenie"],
      "env": {
        "RESULTS_DIR": "/absolute/path/to/results-folder"
      }
    }
  }
}
```

After updating the configuration, restart the MCP client so it can launch the
server.

If you want to run directly from the Git repository:

```json
{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uvx",
      "args": ["git+https://github.com/osvalB/mcp_pykingenie.git@main"]
    }
  }
}
```

#### Claude Desktop

In Claude Desktop, open **Settings**, go to **Developer**, and click
**Edit Config**. Add `mcp_pykingenie` to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uvx",
      "args": ["mcp_pykingenie"],
      "env": {
        "RESULTS_DIR": "/Users/your-name/Documents/user_data_mcp_pykingenie"
      }
    }
  }
}
```

Claude Desktop stores this file at:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Save the file, then fully quit and reopen Claude Desktop.

### Local development

To run the server from a local checkout, use an absolute path to the repository:

```json
{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uvx",
      "args": [
        "--refresh",
        "--from",
        "/absolute/path/to/mcp_pykingenie",
        "mcp_pykingenie"
      ]
    }
  }
}
```

If you want to reuse the checkout's existing environment, run it through `uv`:

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

For HTTP transport during development:

```bash
uv run mcp_pykingenie -t http -p 8000
```

### Install with pip

```bash
pip install --user mcp_pykingenie
```

Then run the server with:

```bash
mcp_pykingenie
```

If your shell cannot find the command, make sure your user-level Python scripts
directory is on `PATH`.

### Install from source

```bash
git clone https://github.com/osvalB/mcp_pykingenie.git
cd mcp_pykingenie
uv sync --extra dev --extra doc --extra test
```

Run tests with:

```bash
uv run pytest
```

Build the documentation with:

```bash
uv run --extra doc make -C docs html
```

## Example workflow

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

```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
```

## Importing data

Use `print_data_dir` to see the active MCP data directory. Import tools accept
absolute paths, or paths relative to that directory.

- Download the bundled Octet BLI example data:
  [`octet_bli_example_data.zip`](docs/_static/downloads/octet_bli_example_data.zip).
- `import_octet_experiment`: pass a folder containing Octet `.frd` files and
  sample plate metadata.
- `import_gator_experiment`: pass a Gator folder or `.zip` archive containing
  channel CSV files plus `Setting.ini` and `ExperimentStep.ini`.
- `import_kingenie_surface_csv`: pass a surface-simulation CSV with trace
  columns such as `Time`, `Signal`, `Smax`, and
  `Analyte_concentration_micromolar_constant`.
- `load_octet_example`: load the packaged example to test the workflow.

## Contact

If you found a bug, please use the [issue tracker][].

## 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

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

[uv]: https://github.com/astral-sh/uv
[issue tracker]: https://github.com/osvalB/mcp_pykingenie/issues
[tests]: https://github.com/osvalB/mcp_pykingenie/actions/workflows/test.yaml
[documentation]: https://osvalb.github.io/mcp_pykingenie/
[api documentation]: https://osvalb.github.io/mcp_pykingenie/modules.html
[pypi]: https://pypi.org/project/mcp_pykingenie
