Kappybara

Runs Kappa simulations via MCP, returning stdout, stderr, and CSV results for analysis.

python

0

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "metareflection-kappybara-mcp": {
      "command": "fastmcp",
      "args": [
        "run",
        "main.py"
      ]
    }
  }
}

You can run Kappa-based simulations directly through an MCP server that leverages the Kappybara library. This setup lets you execute rule-based molecular interaction models and receive results as CSV data for easy analysis, all from an MCP client.

How to use

To run a Kappa simulation, call the run_kappa_simulation tool with your Kappa model code and optional parameters. You will receive three outputs: stdout, stderr, and a CSV-formatted dataset showing the simulation results over time.

Code example for a Kappa run

kappa_code = """
%init: 100 A(x[.])
%init: 100 B(x[.])

%obs: 'AB' |A(x[1]), B(x[1])|

A(x[.]), B(x[.]) <-> A(x[1]), B(x[1]) @ 1, 1
"""

result = run_kappa_simulation(kappa_code, time_limit=50, points=100)
# Result is a JSON string like:
# {
#   "stdout": "",
#   "stderr": "",
#   "output": "time,AB\n0.0,0\n0.01,1\n..."
# }

How to install

Prerequisites you need before installing: Python3 and a functioning Python package manager. You also need the MCP runtime tooling available via the fastmcp command.

Step by step commands you should run in your terminal:

# Obtain the MCP server sources
# You can clone the project or download the package as provided by your setup

# Navigate to the project directory

# Install Python dependencies
pip install -r requirements.txt

# Run the MCP server using the main entry point
fastmcp run main.py

# Optional: integrate with Claude Desktop if you want a GUI workflow
fastmcp install claude-desktop main.py

Notes and tips

The server uses the Kappybara Python library to parse Kappa models and execute simulations. Built-in example models demonstrate reversible binding and linear polymerization, which you can study or adapt for your own experiments.

If you plan to share results, you will receive a CSV payload that you can load into your favorite analysis tool. The tool also returns stdout and stderr so you can inspect console messages and warnings.

Available tools

run_kappa_simulation

Execute a Kappa model using the Kappybara library, returning a JSON string with three fields: stdout, stderr, and output containing CSV results.