clio-kit

# CLIO Kit

<!-- mcp-name: io.github.iowarp/adios-mcp -->
<!-- mcp-name: io.github.iowarp/arxiv-mcp -->
<!-- mcp-name: io.github.iowarp/chronolog-mcp -->
<!-- mcp-name: io.github.iowarp/compression-mcp -->
<!-- mcp-name: io.github.iowarp/darshan-mcp -->
<!-- mcp-name: io.github.iowarp/geo-mcp -->
<!-- mcp-name: io.github.iowarp/hdf5-mcp -->
<!-- mcp-name: io.github.iowarp/jarvis-mcp -->
<!-- mcp-name: io.github.iowarp/lmod-mcp -->
<!-- mcp-name: io.github.iowarp/ndp-mcp -->
<!-- mcp-name: io.github.iowarp/node-hardware-mcp -->
<!-- mcp-name: io.github.iowarp/pandas-mcp -->
<!-- mcp-name: io.github.iowarp/parallel-sort-mcp -->
<!-- mcp-name: io.github.iowarp/paraview-mcp -->
<!-- mcp-name: io.github.iowarp/parquet-mcp -->
<!-- mcp-name: io.github.iowarp/plot-mcp -->
<!-- mcp-name: io.github.iowarp/seismology-mcp -->
<!-- mcp-name: io.github.iowarp/scientific-catalog-mcp -->
<!-- mcp-name: io.github.iowarp/slurm-mcp -->
<!-- mcp-name: io.github.iowarp/spack-mcp -->
<!-- mcp-name: io.github.iowarp/terrain-mcp -->
<!-- mcp-name: io.github.iowarp/web-mcp -->

[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![PyPI version](https://img.shields.io/pypi/v/clio-kit.svg)](https://pypi.org/project/clio-kit/)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![FastMCP](https://img.shields.io/badge/FastMCP-4.0-purple)](https://github.com/jlowin/fastmcp)
[![CI](https://github.com/iowarp/clio-kit/actions/workflows/quality_control.yml/badge.svg)](https://github.com/iowarp/clio-kit/actions/workflows/quality_control.yml)
[![Coverage](https://codecov.io/gh/iowarp/clio-kit/branch/main/graph/badge.svg)](https://codecov.io/gh/iowarp/clio-kit)

[![MCP Servers](https://img.shields.io/badge/MCP%20Servers-22-green)](https://github.com/iowarp/clio-kit/tree/main/mcp-servers)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Type Checked](https://img.shields.io/badge/mypy-type%20checked-blue)](http://mypy-lang.org/)
[![Package Manager](https://img.shields.io/badge/uv-package%20manager-orange)](https://github.com/astral-sh/uv)
[![Security Audit](https://img.shields.io/badge/pip--audit-security%20scanned-green)](https://github.com/pypa/pip-audit)

**CLIO Kit** is the IoWarp meta-marketplace for scientific computing. It brings together MCP servers, workflow skills, plugins, agent definitions, and community contributions—including plugins from external marketplaces—and enables AI agents to interact with HPC resources, scientific data formats, and research datasets.

**Choose individual MCPs, skills, agents and hooks—or a plugin that bundles what your workflow needs.** A plugin can include any of these components; it does not need all four.

[**Website**](https://toolkit.iowarp.ai/) | [**IOWarp**](https://iowarp.ai)

[**Documentation**](docs/README.md) · **For agents:** [read here](AGENTS.md).

Chat with us on [**Zulip**](https://iowarp.zulipchat.com/#narrow/channel/543872-Agent-Toolkit) or [**join us**](https://iowarp.zulipchat.com/join/e4wh24du356e4y2iw6x6jeay/)

Developed by <img src="https://grc.iit.edu/img/logo.png" alt="GRC Logo" width="18" height="18"> [**Gnosis Research Center**](https://grc.iit.edu/)

---

## ❌ Without CLIO Kit

Working with scientific data and HPC resources requires manual scripting and tool-specific knowledge:

- ❌ Write custom scripts for every HDF5/Parquet file exploration
- ❌ Manually craft Slurm job submission scripts
- ❌ Switch between multiple tools for data analysis
- ❌ No AI assistance for scientific workflows
- ❌ Repetitive coding for common research tasks

## ✅ With CLIO Kit

Install workflow bundles, use skills to guide your agent, and discover community tools:

- ✅ **"Analyze the temperature dataset in this HDF5 file"** - HDF5 MCP does it
- ✅ **"Submit this simulation to Slurm with 32 cores"** - Slurm MCP handles it
- ✅ **"Find papers on neural networks from ArXiv"** - ArXiv MCP searches
- ✅ **"Plot the results from this CSV file"** - Plot MCP visualizes
- ✅ **"Optimize memory usage for this pandas DataFrame"** - Pandas MCP optimizes
- ✅ **Workflow guidance** - Skills explain tool sequences; optional agents help plan and review results
- ✅ **Community contributions** - Discover external plugins and marketplace collections

**MCP servers · Skills · Plugins · Agents · Hooks · Community marketplaces**

CLIO Kit is part of the IoWarp platform's tooling ecosystem for AI agents. Its meta-marketplace brings tools and reusable workflows together for scientific computing—from exploring HDF5 datasets and managing Slurm jobs to analyzing results and finding research papers. Built by researchers, for researchers, at Illinois Institute of Technology with NSF support.

> **Part of IoWarp Platform:** CLIO Kit is the platform's meta-marketplace and tooling layer, bringing together MCP servers, skills, workflow plugins, agent definitions, and community marketplace collections.

> **One launcher for MCP servers. Individual components or workflow bundles.** BSD-3-Clause licensed, with automated checks and real installation, MCP, and HPC workflow tests. See the [validation guide](docs/marketplace.md#scientific-acceptance-boundaries) for tested coverage and environment requirements.

## 🚀 Quick Installation

```bash
git clone https://github.com/iowarp/clio-kit.git
cd clio-kit
```

**Recommended:** Ask your agent:

```text
Read setup.md and set up CLIO Kit for me.
```

**Manual setup:** Install this checkout's launcher, then choose an option below.
For the no-clone release route (2.11.0 or newer), see [selective installation](docs/installation.md).

```bash
uv tool install --force --reinstall --editable ".[verification]"
```

### Claude Code

Install a workflow plugin (bundle) with its MCP servers and skills:

```bash
claude plugin marketplace add "$PWD"
claude plugin install clio-hpc@clio-kit
claude mcp list
```

Restart Claude Code after installation and confirm the servers connect.
First launches download dependencies; see [startup recovery](setup.md#update-and-troubleshoot)
if a server exceeds the client's connection timeout.

Or install an individual MCP or a skill collection:

```bash
claude plugin install clio-hdf5@clio-kit                  # HDF5 server
claude plugin install clio-scientific-io-skills@clio-kit  # Scientific I/O skills
```

Claude Code uses `plugin install` for component packages too. CLIO Kit lists
those separately from workflow plugins; see [components and plugins](docs/plugins.md).

### Codex and Other Agents

Install a workflow's skills and MCP configuration together:

```bash
clio-kit plugin install clio-scientific-io --client codex --project /path/to/project
```

Also supports `opencode`, `cursor`, `antigravity`, `vscode` and `claude-code`.
This sets up project components; native agents and hooks need client-specific
adapters. See [client installation and limits](docs/intro.md#install-a-workflow-for-your-client).

Install a bundle or one skill into your project:

```bash
# Bundle
clio-kit skill install --bundle clio-scientific-io --target /path/to/project/.agents/skills
# Individual skill
clio-kit skill install dataset-explore --target /path/to/project/.agents/skills
```

Configure the required MCP servers using [setup.md](setup.md). Use your agent’s supported skill directory.

### Install Skills with npm

Requires Node.js 22.20.0+. From your working project:

```bash
# All skills
npx skills@1.5.25 add /path/to/clio-kit --skill '*' --agent codex --copy
# Individual skill
npx skills@1.5.25 add /path/to/clio-kit --skill dataset-explore --agent codex --copy
```

Replace `codex` with `claude-code` or `antigravity`. MCP servers require separate configuration.

Choose either the Python or npm installer for each skill. See the [skills CLI guide](docs/marketplace.md#optional-skills-cli) for selecting skills, updates and removal.

### One Command for Any Server

```bash
# From the CLIO Kit checkout, install the CLI in a persistent tool environment
uv tool install --force --reinstall --editable .
# If uv's executable directory is not on PATH:
uv tool update-shell

# List all 22 available MCP servers
clio-kit mcp-servers

# Run an individual server
clio-kit mcp-server hdf5
clio-kit mcp-server pandas
clio-kit mcp-server slurm
```

Once 2.11.0 is published, install it with `uv tool install 'clio-kit>=2.11.0'`
(2.11.0 or newer; earlier releases lack the `skill`, `plugin` and `doctor` commands).
`uv tool install` creates a persistent, isolated environment; use
`uvx --from 'clio-kit>=2.11.0' clio-kit ...` for a temporary, one-shot invocation.

The release separates the small launcher from component downloads: one MCP
fetches only that server, one skill fetches only its files, and a workflow selects
its components. Server dependencies stay isolated and locked. See
[selective installation](docs/installation.md) for release, checkout and native plugin routes.
The `--branch` option is for development, not an immutable release installation.

The wheel also includes machine-readable tool contracts for JARVIS, Slurm, Spack
and Scientific Catalog, with SHA-256 digests for downstream verification:

```bash
clio-kit mcp-contracts
clio-kit mcp-contract clio-kit-jarvis-user-v3.7.2
clio-kit mcp-contract clio-kit-slurm-user-v3
clio-kit mcp-contract clio-kit-spack-user-v2.3
clio-kit mcp-contract clio-kit-scientific-catalog-user-v1.1
```

### Workflow Bundles

These are broad workflow plugins. Each combines its MCP servers and skills.

| Bundle | Purpose | MCP servers |
|---|---|---|
| `clio-hpc` | Build software and run cluster jobs | spack, lmod, jarvis, slurm, node-hardware |
| `clio-performance` | Diagnose slow jobs and inspect logs | darshan, chronolog, parallel-sort |
| `clio-scientific-io` | Explore scientific data files | hdf5, adios, parquet, compression |
| `clio-analysis` | Analyze res