Isabl MCP Server

https://github.com/juanesarango/isabl-mcp
Admin
An MCP server and knowledge base that enables AI assistants to query the Isabl genomics platform,...
Tokens:94,173
Snippets:1,053
Trust Score:8.3
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Use `import isabl_cli as ii` convention
- Filter queries with Django-style syntax: status='SUCCEEDED', application__name='MUTECT'
- Applications inherit from AbstractApplication
- Data model hierarchy: Individual -> Sample -> Experiment -> Analysis
- Analysis statuses: CREATED -> STAGED -> SUBMITTED -> STARTED -> SUCCEEDED / FAILED
- Use system_id for experiments/individuals/samples, pk for analyses/projects/applications

================
CODE SNIPPETS
================
### Example: run GRCh38 app with --commit

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-write-app/SKILL.md

Concrete example of running a GRCh38 app called my_application version 1.0.0 with a tumor-normal pair and the --commit flag.

```bash
isabl apps-grch38 my-application-1.0.0 --pairs IID_H209923_T01_01_WG01 IID_H209923_N01_01_WG01 --commit
```

--------------------------------

### Install Isabl MCP in Claude Code

Source: https://github.com/juanesarango/isabl-mcp/blob/main/README.md

Install the Isabl MCP server and its 8 guided skills as /isabl-* slash commands in Claude Code. Credentials are auto-discovered from ~/.isabl/settings.json. For MCP only (no skills), use: claude mcp add isabl -- uvx isabl-mcp.

```text
/plugin marketplace add juanesarango/isabl-mcp
/plugin install isabl
```

--------------------------------

### Set up and run MCP server development commands

Source: https://github.com/juanesarango/isabl-mcp/blob/main/README.md

Development workflow for the MCP server: sync dependencies, run tests, lint, test with MCP Inspector, and start the server locally.

```bash
cd mcp-server
uv sync --dev
uv run pytest
uv run ruff check isabl_mcp/  # lint
uv run mcp dev isabl_mcp/server.py  # test with MCP Inspector
uv run isabl-mcp           # start server locally
```

--------------------------------

### Get project info with isabl_cli

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-project-report/SKILL.md

Retrieves a project instance by primary key and prints its key fields. Requires the project primary key (PROJECT_PK) to be defined.

```python
import isabl_cli as ii

project = ii.get_instance("projects", PROJECT_PK)

print(f"Project: {project.title}")
print(f"Short title: {project.short_title}")
print(f"PI: {project.principal_investigator}")
print(f"Analyst: {project.analyst}")
print(f"Description: {project.description}")
```

--------------------------------

### Run Isabl MCP with uvx or pip

Source: https://github.com/juanesarango/isabl-mcp/blob/main/README.md

Run the Isabl MCP server directly with uvx or install it globally with pip. Works with any MCP-compatible client such as Windsurf, Zed, or Claude Desktop.

```bash
uvx isabl-mcp        # run directly, no install needed
pip install isabl-mcp # or install globally
```

--------------------------------

### Track Running Jobs with ii.get_analyses

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-monitor-analyses/SKILL.md

Fetches analyses with status STARTED, ordered by start time descending, and prints the first 20 running jobs with their elapsed hours and target system ID.

```python
running = ii.get_analyses(
    projects=PROJECT_PK,
    status="STARTED",
    ordering="-started"
)

if running:
    print(f"\n=== RUNNING ({len(running)}) ===")
    for a in running[:20]:
        hours = (datetime.now() - a.started).total_seconds() / 3600
        target = a.targets[0].system_id if a.targets else "N/A"
        print(f"  [{a.pk}] {a.application.name}: {target} ({hours:.1f}h)")
```

--------------------------------

### Create reference data instances (centers, techniques, diseases)

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Use ii.create_instance to create a new center, technique, and disease. Each call returns an object with a slug attribute that is printed. The center example uses name 'Memorial Sloan Kettering' and acronym 'MSK'; the technique uses name 'WGS 30X', method 'WGS', and category 'DNA'; the disease uses name 'Acute Myeloid Leukemia' and acronym 'AML'.

```python
# Create a new center
center = ii.create_instance("centers", {
    "name": "Memorial Sloan Kettering",
    "acronym": "MSK",
})
print(f"Created center: {center.slug}")

# Create a new technique
technique = ii.create_instance("techniques", {
    "name": "WGS 30X",
    "method": "WGS",
    "category": "DNA",
})
print(f"Created technique: {technique.slug}")

# Create a new disease
disease = ii.create_instance("diseases", {
    "name": "Acute Myeloid Leukemia",
    "acronym": "AML",
})
print(f"Created disease: {disease.slug}")
```

--------------------------------

### Filter Queries by Project, Status, Application, Date, and Combined Filters

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Shows how to filter queries using various criteria such as project, status, application, date range, and combined filters. Each filter is demonstrated with a separate example.

```python
# Filter by project
experiments = ii.get_experiments(projects=102)
```

```python
# Filter by status
analyses = ii.get_analyses(status="SUCCEEDED")
```

```python
# Filter by application
analyses = ii.get_analyses(application__name="MUTECT")
```

```python
# Filter by date range
analyses = ii.get_analyses(created__gte="2024-01-01")
```

```python
# Combine multiple filters
experiments = ii.get_experiments(
    projects=102,
    sample__category="TUMOR",
    technique__method="WGS"
)
```

--------------------------------

### Get single instance by ID

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Retrieves a single experiment by system_id or an analysis by primary key.

```python
import isabl_cli as ii

# By system_id
exp = ii.Experiment("SAMPLE_001")

# By primary key
analysis = ii.Analysis(12345)
```

--------------------------------

### ID display convention: get experiments with system_id

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Fetches experiments with only system_id and sample fields, printing experiment IDs. Use this when the user asks for an experiment ID, preferring system_id over numeric pk.

```python
import isabl_cli as ii

experiments = ii.get_experiments(projects=102, fields=["system_id", "sample"])
for exp in experiments:
    print(f"experiment_id={exp.system_id}")
```

--------------------------------

### Get individual's full tree

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Retrieves an individual's full tree and prints samples and their experiments.

```python
import isabl_cli as ii

individual = ii.get_tree(individual_pk)
for sample in individual.sample_set:
    print(f"Sample: {sample.identifier}")
    for exp in sample.experiment_set:
        print(f"  Experiment: {exp.system_id}")
```

--------------------------------

### Get analysis details with isabl_cli

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-debug-analysis/SKILL.md

Retrieve an Isabl analysis by primary key and print its status, application name/version, storage URL, targets, and references. Use this as the first step when debugging a failed analysis.

```python
import isabl_cli as ii

# Get the analysis
analysis = ii.Analysis(ANALYSIS_PK)

print(f"Status: {analysis.status}")
print(f"Application: {analysis.application.name} v{analysis.application.version}")
print(f"Storage URL: {analysis.storage_url}")
print(f"Targets: {[t.system_id for t in analysis.targets]}")
print(f"References: {[r.system_id for r in analysis.references]}")
```

--------------------------------

### Merge VCFs with bcftools using a file list

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-merge-results/SKILL.md

Collects paths to output.vcf.gz files from analyses, writes them to vcf_files.txt, then merges them with bcftools using the -l flag. Requires bcftools installed and the analyses variable from a prior query.

```python
# First, generate VCF list file from Python
vcf_paths = []
for a in analyses:
    vcf_path = Path(a.storage_url) / "output.vcf.gz"
    if vcf_path.exists():
        vcf_paths.append(str(vcf_path))

# Write to file for bcftools
with open("vcf_files.txt", "w") as f:
    f.write("\n".join(vcf_paths))

print(f"Listed {len(vcf_paths)} VCF files")
```

```bash
# Then merge with bcftools
bcftools merge -l vcf_files.txt -o merged.vcf.gz -O z
```

--------------------------------

### Convert experiment data to pandas DataFrame

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Convert experiment data into a pandas DataFrame for easier manipulation and display. The example builds a list of dictionaries from experiment attributes and then creates a DataFrame, showing the first few rows with head().

```python
import isabl_cli as ii
import pandas as pd

experiments = ii.get_experiments(projects=102)
df = pd.DataFrame([
    {
        "system_id": e.system_id,
        "sample": e.sample.identifier,
        "category": e.sample.category,
        "technique": e.technique.method,
    }
    for e in experiments
])
df.head()
```

--------------------------------

### Merge BAM coverage metrics from analyses

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-merge-results/SKILL.md

Parses coverage_metrics.txt files from analyses, extracting lines starting with MEAN_COVERAGE and storing sample ID and mean coverage. The file format varies by tool, so adjust parsing as needed.

```python
# Collect coverage metrics from multiple analyses
coverage_data = []
for a in analyses:
    metrics_file = Path(a.storage_url) / "coverage_metrics.txt"
    if metrics_file.exists():
        # Parse coverage metrics (format varies by tool)
        with open(metrics_file) as f:
            for line in f:
                if line.startswith("MEAN_COVERAGE"):
                    coverage_data.append({
                        "sample": a.targets[0].system_id,
                        "mean_coverage": float(line.split("\t")[1])
                    })
```

--------------------------------

### Suggest actions based on analysis status

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-monitor-analyses/SKILL.md

Defines a function that queries analyses for a project and generates a list of suggested actions based on status: failed analyses, stale analyses (STARTED for over 48 hours), and stuck jobs (SUBMITTED for over 12 hours). Prints the suggestions to the console. Requires `ii` (isabl instance), `datetime`, `timedelta`, and `PROJECT_PK` to be defined.

```python
def suggest_actions(project_pk):
    """Suggest actions based on analysis status."""
    actions = []

    # Check for failures
    failed = list(ii.get_analyses(projects=project_pk, status="FAILED"))
    if failed:
        actions.append(f"- Debug {len(failed)} failed analyses (use /isabl-debug-analysis)")

    # Check for stale
    stale_cutoff = datetime.now() - timedelta(days=2)
    stale = list(ii.get_analyses(
        projects=project_pk,
        status="STARTED",
        started__lt=stale_cutoff.isoformat()
    ))
    if stale:
        actions.append(f"- Investigate {len(stale)} stale analyses (running > 48h)")

    # Check for queue issues
    queue_cutoff = datetime.now() - timedelta(hours=12)
    stuck = list(ii.get_analyses(
        projects=project_pk,
        status="SUBMITTED",
        submitted__lt=queue_cutoff.isoformat()
    ))
    if stuck:
        actions.append(f"- Check batch system for {len(stuck)} stuck jobs")

    if not actions:
        actions.append("- No immediate actions required")

    print("\n## Suggested Actions")
    for action in actions:
        print(action)

suggest_actions(PROJECT_PK)
```

--------------------------------

### Find Stale Analyses (Running > 48h)

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-monitor-analyses/SKILL.md

Finds analyses that have been running for more than 48 hours by querying status STARTED with a started timestamp older than the cutoff, then prints each with its running time in hours.

```python
stale_cutoff = datetime.now() - timedelta(hours=48)

stale = ii.get_analyses(
    projects=PROJECT_PK,
    status="STARTED",
    started__lt=stale_cutoff.isoformat()
)

if stale:
    print(f"\n=== STALE (running > 48h) ({len(stale)}) ===")
    for a in stale:
        hours = (datetime.now() - a.started).total_seconds() / 3600
        print(f"  [{a.pk}] {a.application.name}: running {hours:.1f}h")
```

--------------------------------

### Import experiments from CSV with ii.create_instance

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Reads a CSV of sample metadata and creates an experiment for each row using ii.create_instance. Requires pandas and a pre-defined PROJECT_PK. Prints the created experiment's system_id.

```python
import pandas as pd

df = pd.read_csv("samples.csv")

for _, row in df.iterrows():
    experiment = ii.create_instance("experiments", {
        "identifier": row["library_id"],
        "sample": {
            "identifier": row["sample_id"],
            "category": row["category"],
            "disease": {"acronym": row["disease"]},
            "individual": {
                "identifier": row["patient_id"],
                "species": "HUMAN",
                "center": {"slug": "msk"},
            },
        },
        "technique": {"slug": row["technique"]},
        "platform": {"slug": row["platform"]},
        "center": {"slug": "msk"},
        "projects": [{"pk": PROJECT_PK}],
        "raw_data": [
            {"file_url": row["r1_path"], "file_type": "FASTQ"},
            {"file_url": row["r2_path"], "file_type": "FASTQ"},
        ],
    })
    print(f"Created: {experiment.system_id}")
```

--------------------------------

### create_instance

Source: https://github.com/juanesarango/isabl-mcp/blob/main/knowledge/output/site/cli-usage-tooling/api-client-helpers-cli/README.md

Creates a database instance via the API.

```APIDOC
## create_instance

### Description
Creates a new database object through the Isabl API. Takes an endpoint string (e.g., 'analyses') and a data dict of fields to set, and returns a types.SimpleNamespace populated with the API response.

### Method
Function

### Signature
`create_instance(endpoint, data)`

### Parameters
- **endpoint** (str) - Required - The API endpoint name (e.g., 'analyses').
- **data** (dict) - Required - Dictionary of fields to set for the new instance.

### Returns
- **types.SimpleNamespace** - The created instance data as a SimpleNamespace.
```

--------------------------------

### Verify application settings

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-debug-analysis/SKILL.md

Retrieve the application settings and print them, then check a specific setting (tool_path) from a custom application instance. Use this to verify configuration values.

```python
# Get application settings
app = ii.get_instance("applications", analysis.application.pk)
print(f"Settings: {app.settings}")

# Check specific setting
from my_apps import MyApplication
instance = MyApplication()
print(f"Tool path: {instance.settings.tool_path}")
```

--------------------------------

### Find stale analyses (running too long)

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-project-report/SKILL.md

Finds analyses with status STARTED that were modified more than 7 days ago, indicating they may be stale. Uses the modified__lt filter with an ISO-formatted datetime.

```python
from datetime import datetime, timedelta

stale_cutoff = datetime.now() - timedelta(days=7)

stale = ii.get_analyses(
    projects=PROJECT_PK,
    status="STARTED",
    modified__lt=stale_cutoff.isoformat()
)

if stale:
    print(f"Stale analyses (started > 7 days ago): {len(stale)}")
```

--------------------------------

### Find Available Isabl Apps

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-run-pipeline/SKILL.md

Lists available Isabl commands and shows how to find apps for a specific assembly using the format `isabl apps-<assembly> --help`.

```bash
isabl --help

# i.e 
isabl apps-grch37 --help
```

--------------------------------

### Batch pipeline submission with isabl CLI

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-run-pipeline/SKILL.md

Builds all isabl CLI commands first, then executes them with subprocess.run. Recommended over sequential submission because it submits all targets at once using a comma-separated list. Returns the list of commands; use commit=True to actually run them.

```python
import subprocess

def run_pipeline_batch(experiments, pipeline, pairs=None, commit=False):
    """Submit all pipeline steps at once."""
    commands = []
    commit_flag = "--commit" if commit else ""

    for step in pipeline:
        app_name = step["app"]
        app_type = step["type"]

        if app_type == "TARGETS":
            # Submit all targets at once
            targets = ",".join(e.system_id for e in experiments)
            commands.append(f"isabl {app_name} --targets {targets} {commit_flag}")

        elif app_type == "PAIRS" and pairs:
            # Submit all pairs at once
            for tumor, normal in pairs:
                commands.append(
                    f"isabl {app_name} --targets {tumor.system_id} "
                    f"--references {normal.system_id} {commit_flag}"
                )

    # Execute commands
    for cmd in commands:
        print(f"Executing: {cmd}")
        if commit:
            subprocess.run(cmd, shell=True)

    return commands

commands = run_pipeline_batch(experiments, PIPELINE, pairs=pairs, commit=False)
```

--------------------------------

### Check Analysis Status Counts

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-monitor-analyses/SKILL.md

Retrieves analyses within the defined scope and counts them by status. Prints the total and percentage for each status category (SUCCEEDED, FAILED, STARTED, SUBMITTED, STAGED, CREATED).

```python
from collections import Counter

# Get all analyses in scope
filters = {"projects": PROJECT_PK}
if APPLICATION_NAME:
    filters["application__name"] = APPLICATION_NAME

analyses = list(ii.get_analyses(**filters))

# Count by status
status_counts = Counter(a.status for a in analyses)

print(f"=== Analysis Status (Project {PROJECT_PK}) ===")
print(f"Total: {len(analyses)}")
for status in ["SUCCEEDED", "FAILED", "STARTED", "SUBMITTED", "STAGED", "CREATED"]:
    count = status_counts.get(status, 0)
    pct = (count / len(analyses) * 100) if analyses else 0
    print(f"  {status}: {count} ({pct:.1f}%)")
```

--------------------------------

### Run isabl application via CLI

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-write-app/SKILL.md

Shows how to invoke the application via the assembly-specific CLI command. Use --targets for single experiments, --pairs for tumor-normal pairs, and add --commit to actually submit.

```bash
# Dry run (no --commit)
isabl apps-<assembly-name> <app-name>-<version> --targets EXPERIMENT_SYSTEM_ID

# Paired tumor-normal
isabl apps-<assembly-name> <app-name>-<version> --pairs TUMOR_SYSTEM_ID NORMAL_SYSTEM_ID

# Actually submit
isabl apps-<assembly-name> <app-name>-<version> --pairs TUMOR_SYSTEM_ID NORMAL_SYSTEM_ID --commit
```

--------------------------------

### Configure Isabl MCP in Codex (~/.codex/config.toml)

Source: https://github.com/juanesarango/isabl-mcp/blob/main/README.md

Add the Isabl MCP server to Codex by placing this configuration in ~/.codex/config.toml. The env variables ISABL_API_URL and ISABL_API_TOKEN must be set to your Isabl instance URL and API token.

```toml
[mcp_servers.isabl]
command = "uvx"
args = ["isabl-mcp"]
env = { "ISABL_API_URL" = "https://your-isabl-instance.com/api/v1/", "ISABL_API_TOKEN" = "your-token" }
```

--------------------------------

### Configure Isabl MCP in Cursor (.cursor/mcp.json)

Source: https://github.com/juanesarango/isabl-mcp/blob/main/README.md

Add the Isabl MCP server to Cursor by placing this configuration in .cursor/mcp.json. The env variables ISABL_API_URL and ISABL_API_TOKEN must be set to your Isabl instance URL and API token.

```json
{
  "mcpServers": {
    "isabl": {
      "command": "uvx",
      "args": ["isabl-mcp"],
      "env": {
        "ISABL_API_URL": "https://your-isabl-instance.com/api/v1/",
        "ISABL_API_TOKEN": "your-token"
      }
    }
  }
}
```

--------------------------------

### Set ISABL API credentials via environment variables

Source: https://github.com/juanesarango/isabl-mcp/blob/main/README.md

Set the API URL and token explicitly. These environment variables take precedence over the settings file.

```bash
export ISABL_API_URL="https://your-isabl-instance.com/api/v1/"
export ISABL_API_TOKEN="your-token"
```

--------------------------------

### Define Monitoring Scope with isabl_cli

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-monitor-analyses/SKILL.md

Sets up the monitoring scope by defining the project primary key, optional application name, and a time cutoff for the last N hours. Used as the first step in the monitoring workflow.

```python
import isabl_cli as ii
from datetime import datetime, timedelta

# Define what to monitor
PROJECT_PK = 102
APPLICATION_NAME = "MUTECT"  # or None for all
HOURS_BACK = 24  # Look at last N hours

cutoff = datetime.now() - timedelta(hours=HOURS_BACK)
```

--------------------------------

### get_instance

Source: https://github.com/juanesarango/isabl-mcp/blob/main/knowledge/output/site/cli-usage-tooling/api-client-helpers-cli/README.md

Lookup a database instance by various identifiers.

```APIDOC
## get_instance

### Description
Retrieves a database instance from an API endpoint using flexible identifiers (primary key, system_id, email, or username). Accepts an endpoint and optional fields list, returning a SimpleNamespace populated with the instance data for easy attribute access.

### Method
Function

### Signature
`get_instance(endpoint, identifier, fields=None)`

### Parameters
- **endpoint** (str) - Required - The API endpoint name (e.g., 'analyses').
- **identifier** (str/int) - Required - The instance identifier (primary key, system_id, email, or username).
- **fields** (list) - Optional - List of fields to include in the response.

### Returns
- **types.SimpleNamespace** - The instance data as a SimpleNamespace.
```

--------------------------------

### Define application metadata with AbstractApplication

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-write-app/SKILL.md

Defines the application class with required metadata (NAME, VERSION) and optional ASSEMBLY/SPECIES restrictions. Use as the foundation for any Isabl application.

```python
from isabl_cli import AbstractApplication, options

class MyApplication(AbstractApplication):
    """
    Brief description of what this application does.
    """

    # Required metadata
    NAME = "my_application"
    VERSION = "1.0.0"

    # Optional: restrict to specific assembly/species
    ASSEMBLY = "GRCh37"  # or "GRCh38", None for any
    SPECIES = "HUMAN"    # or None for any
```

--------------------------------

### Optimize experiment queries with fields, count_limit, and cursor pagination

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Performance tips for querying experiments: use the fields parameter to fetch only needed fields, count_limit to stop after a certain number of results, and paginator="cursor" for cursor-based pagination on large datasets.

```python
import isabl_cli as ii

# Only fetch needed fields
experiments = ii.get_experiments(
    projects=102,
    fields=["pk", "system_id", "sample"]
)

# Stop after N results
experiments = ii.get_experiments(
    projects=102,
    count_limit=100
)

# Use cursor pagination for very large datasets
experiments = ii.get_instances(
    "experiments",
    projects=102,
    paginator="cursor"
)
```

--------------------------------

### Verify experiments created with get_experiments

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Verifies that experiments were created by querying the API with a project primary key and an identifier prefix, then prints details for each experiment including sample and individual identifiers and the count of raw data files.

```python
# Check experiments were created
experiments = list(ii.get_experiments(
    projects=PROJECT_PK,
    identifier__startswith="LIB_001"
))

print(f"Created {len(experiments)} experiments:")
for exp in experiments:
    print(f"  {exp.system_id}")
    print(f"    Sample: {exp.sample.identifier} ({exp.sample.category})")
    print(f"    Individual: {exp.sample.individual.identifier}")
    print(f"    Raw data files: {len(exp.raw_data or [])}")
```

--------------------------------

### Count experiments by technique and category

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-project-report/SKILL.md

Counts experiments by technique and sample category using Counter, then prints the totals. Requires PROJECT_PK and the isabl_cli import from the previous step.

```python
from collections import Counter

experiments = ii.get_experiments(projects=PROJECT_PK)

# By technique
techniques = Counter(e.technique.method for e in experiments)
print("Experiments by technique:")
for tech, count in techniques.most_common():
    print(f"  {tech}: {count}")

# By sample category
categories = Counter(e.sample.category for e in experiments)
print("\nExperiments by category:")
for cat, count in categories.most_common():
    print(f"  {cat}: {count}")

print(f"\nTotal experiments: {len(experiments)}")
```

--------------------------------

### Configure CLI options with options.TARGETS

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-write-app/SKILL.md

Configures CLI options for the application, specifying how it receives input experiments. Use options.TARGETS, options.REFERENCES, or options.PAIRS as needed.

```python
from isabl_cli import AbstractApplication, options

class MyApplication(AbstractApplication):
    NAME = "my_application"
    VERSION = "1.0.0"

    # CLI configuration
    cli_help = "Run my application on experiments"
    cli_options = [options.TARGETS]  # or REFERENCES, PAIRS
```

--------------------------------

### makedirs(path, exist_ok=True, mode=511)

Source: https://github.com/juanesarango/isabl-mcp/blob/main/knowledge/output/site/utilities-filesystem-helpers/filesystem-links-archiving/README.md

Creates directories while explicitly handling permissions to ignore the process umask. Behaves similarly to os.makedirs but ensures the requested mode is applied regardless of the calling process's umask.

```APIDOC
## makedirs(path, exist_ok=True, mode=511)

### Description
Creates directories while explicitly handling permissions to ignore the process umask. Behaves similarly to os.makedirs but ensures the requested mode is applied regardless of the calling process's umask.

### Parameters
- **path** (str) - Required - The directory path to create.
- **exist_ok** (bool) - Optional - If True, no error is raised if the directory already exists. Defaults to True.
- **mode** (int) - Optional - The permission mode to apply. Defaults to 511 (octal 0777).

### Returns
None

### Example
```python
makedirs('/tmp/example', exist_ok=True, mode=0o755)
```
```

--------------------------------

### Find experiments by project

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Fetches experiments for a project and sample category, printing system IDs and sample identifiers.

```python
import isabl_cli as ii

experiments = ii.get_experiments(
    projects=102,
    sample__category="TUMOR"
)
for exp in experiments:
    print(f"{exp.system_id}: {exp.sample.identifier}")
```

--------------------------------

### Understand Result Schema with isabl_cli get_instance

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-merge-results/SKILL.md

Inspects available results for a sample analysis and retrieves the application's result definitions using isabl_cli's get_instance.

```python
# Check what results are available
sample_analysis = analyses[0]
print(f"Available results: {list(sample_analysis.results.keys())}")

# Check application's result definitions
app = ii.get_instance("applications", sample_analysis.application.pk)
print(f"Result schema: {app.results}")
```

--------------------------------

### Check Reference Data with isabl_cli

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Use this snippet to verify required reference data before submission. It lists available centers, techniques, platforms, and diseases, and prints the target project title. Requires the isabl_cli package and a valid PROJECT_PK.

```python
import isabl_cli as ii

# Check available centers
centers = list(ii.get_instances("centers"))
print("Centers:", [c.slug for c in centers])

# Check available techniques
techniques = list(ii.get_instances("techniques"))
print("Techniques:", [(t.slug, t.method) for t in techniques])

# Check available platforms
platforms = list(ii.get_instances("platforms"))
print("Platforms:", [p.slug for p in platforms])

# Check available diseases
diseases = list(ii.get_instances("diseases"))
print("Diseases:", [d.acronym for d in diseases[:10]])

# Check target project
project = ii.get_instance("projects", PROJECT_PK)
print(f"Target project: {project.title}")
```

--------------------------------

### Sequential pipeline submission with isabl CLI

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-run-pipeline/SKILL.md

Runs each pipeline step one at a time, iterating over experiments or pairs. Use commit=False for a dry run that only prints commands; set commit=True to execute them via os.system. Requires the experiments, PIPELINE, and pairs variables to be defined beforehand.

```python
def run_pipeline_sequential(experiments, pipeline, pairs=None, commit=False):
    """Run pipeline steps sequentially."""
    commit_flag = "--commit" if commit else ""

    for step in pipeline:
        app_name = step["app"]
        app_type = step["type"]

        print(f"\n=== Running {app_name} ===")

        if app_type == "TARGETS":
            for exp in experiments:
                cmd = f"isabl {app_name} --targets {exp.system_id} {commit_flag}"
                print(f"Executing: {cmd}")
                if commit:
                    os.system(cmd)

        elif app_type == "PAIRS" and pairs:
            for tumor, normal in pairs:
                cmd = f"isabl {app_name} --targets {tumor.system_id} --references {normal.system_id} {commit_flag}"
                print(f"Executing: {cmd}")
                if commit:
                    os.system(cmd)

# Dry run first
run_pipeline_sequential(experiments, PIPELINE, pairs=pairs, commit=False)

# Then commit
# run_pipeline_sequential(experiments, PIPELINE, pairs=pairs, commit=True)
```

--------------------------------

### make_tar(source_dir, output_path)

Source: https://github.com/juanesarango/isabl-mcp/blob/main/knowledge/output/site/utilities-filesystem-helpers/filesystem-links-archiving/README.md

Creates a tar archive from a source directory, compressing or archiving it into the specified output path for transport or storage. Packages a directory tree into a single file, preserving necessary metadata.

```APIDOC
## make_tar(source_dir, output_path)

### Description
Creates a tar archive from a source directory, compressing or archiving it into the specified output path for transport or storage. Packages a directory tree into a single file, preserving necessary metadata.

### Parameters
- **source_dir** (str) - Required - The source directory to archive.
- **output_path** (str) - Required - The destination tarball file path.

### Returns
None

### Example
```python
make_tar('/path/to/dir', '/path/to/output.tar.gz')
```
```

--------------------------------

### Add experiment to project by patching projects list

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Retrieves an experiment, appends a new project PK to its existing projects list, and patches the experiment. Requires NEW_PROJECT_PK to be defined.

```python
# Add existing experiment to a new project
exp = ii.get_instance("experiments", system_id="ISB_H000001_T01_WGS01")
current_projects = [{"pk": p.pk} for p in exp.projects]
current_projects.append({"pk": NEW_PROJECT_PK})

ii.patch_instance("experiments", exp.pk, {
    "projects": current_projects,
})
```

--------------------------------

### Define application settings and results

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-write-app/SKILL.md

Defines an isabl application with configurable settings and expected results. The application_settings dictionary can be overridden in the database, and application_results defines the output file metadata.

```python
from isabl_cli import AbstractApplication, options

class MyApplication(AbstractApplication):
    NAME = "my_application"
    VERSION = "1.0.0"
    cli_options = [options.TARGETS]

    # Configurable settings (can be overridden in database)
    application_settings = {
        "tool_path": "/usr/bin/mytool",
        "threads": 4,
        "memory_gb": 16,
    }

    # Define expected results
    application_results = {
        "output_file": {
            "frontend_type": "text-file",
            "description": "Main output file",
            "verbose_name": "Output",
        }
    }
```

--------------------------------

### Update existing experiment with raw_data using ii.patch_instance

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Fetches an existing experiment by system_id and patches it to add raw_data entries. Uses ii.get_instance and ii.patch_instance.

```python
# Add raw_data to existing experiment
exp = ii.get_instance("experiments", system_id="ISB_H000001_T01_WGS01")

ii.patch_instance("experiments", exp.pk, {
    "raw_data": [
        {"file_url": "/new/path/R1.fastq.gz", "file_type": "FASTQ"},
        {"file_url": "/new/path/R2.fastq.gz", "file_type": "FASTQ"},
    ],
})
```

--------------------------------

### Run pipeline via isabl Python API

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-run-pipeline/SKILL.md

Uses the isabl_cli.api module to run pipeline steps programmatically. Retrieves the application class with api.get_application and calls app.run with tuples of targets/references. The final call is commented out; uncomment and set commit=True to execute.

```python
from isabl_cli import api

def run_pipeline_api(experiments, pipeline, pairs=None, commit=False):
    """Run pipeline using Python API."""

    for step in pipeline:
        app_name = step["app"]
        app_type = step["type"]

        # Get application class
        app_class = api.get_application(app_name)
        app = app_class()

        print(f"\n=== {app_name} ===")

        if app_type == "TARGETS":
            tuples = [([exp], []) for exp in experiments]
        elif app_type == "PAIRS" and pairs:
            tuples = [([tumor], [normal]) for tumor, normal in pairs]
        else:
            continue

        # Run application
        app.run(tuples=tuples, commit=commit)

# run_pipeline_api(experiments, PIPELINE, pairs=pairs, commit=True)
```

--------------------------------

### Create experiment with nested hierarchy using isabl API

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Creates an experiment with nested individual and sample definitions, letting the API get-or-create the hierarchy. Uses slugs for technique, platform, and center, and includes raw_data file entries.

```python
# Create experiment with nested individual/sample
# API will get-or-create the hierarchy

experiment = ii.create_instance("experiments", {
    "identifier": "LIB_001_T_WGS",
    "sample": {
        "identifier": "PATIENT_001_TUMOR",
        "category": "TUMOR",
        "disease": {"acronym": "AML"},
        "individual": {
            "identifier": "PATIENT_001",
            "species": "HUMAN",
            "gender": "FEMALE",
            "center": {"slug": "msk"},
        },
    },
    "technique": {"slug": "wgs-30x"},
    "platform": {"slug": "illumina-novaseq"},
    "center": {"slug": "msk"},
    "projects": [{"pk": PROJECT_PK}],
    "raw_data": [
        {"file_url": "/data/fastq/R1.fastq.gz", "file_type": "FASTQ"},
        {"file_url": "/data/fastq/R2.fastq.gz", "file_type": "FASTQ"},
    ],
})
```

--------------------------------

### Check input file existence with ls

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-debug-analysis/SKILL.md

List the input file with details to confirm it exists and check permissions.

```bash
# Check files exist
ls -la {path_to_input_file}
```

--------------------------------

### Check Prerequisites for Pipeline with isabl_cli

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-run-pipeline/SKILL.md

Defines a function to verify that each experiment has raw data files and that required applications are registered. Prints a list of issues or a success message.

```python
from pathlib import Path

def check_prerequisites(experiments, pipeline):
    """Check if experiments are ready for pipeline."""
    issues = []

    for exp in experiments:
        # Check raw data exists
        if not exp.raw_data:
            issues.append(f"{exp.system_id}: No raw data")
            continue

        # Check files exist
        for rd in exp.raw_data:
            if not Path(rd["file_url"]).exists():
                issues.append(f"{exp.system_id}: Missing {rd['file_url']}")

    # Check required apps are registered
    for step in pipeline:
        apps = list(ii.get_instances("applications", name=step["app"].rsplit("-", 1)[0]))
        if not apps:
            issues.append(f"Application not found: {step['app']}")

    return issues

issues = check_prerequisites(experiments, PIPELINE)
if issues:
    print("Prerequisites not met:")
    for issue in issues:
        print(f"  - {issue}")
else:
    print("All prerequisites met!")
```

--------------------------------

### Identify Entity Types with isabl_cli

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Lists the main entity types and their query functions in isabl_cli. Use these to retrieve experiments, analyses, samples, individuals, applications, and projects.

```python
import isabl_cli as ii

# Main entity types and their query functions
experiments = ii.get_experiments(...)      # Sequencing data
analyses = ii.get_analyses(...)            # Pipeline results
samples = ii.get_instances("samples", ...) # Tissue specimens
individuals = ii.get_instances("individuals", ...)  # Patients/subjects
applications = ii.get_instances("applications", ...)  # Pipelines
projects = ii.get_instances("projects", ...)  # Project groupings
```

--------------------------------

### Create submission individually with isabl API

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Creates individuals, samples, and experiments individually using the isabl API, giving more control over the hierarchy. Prints the system_id of each created object.

```python
# 1. Create individual
individual = ii.create_instance("individuals", {
    "identifier": submission_data["individual"]["identifier"],
    "species": submission_data["individual"]["species"],
    "gender": submission_data["individual"]["gender"],
    "center": submission_data["individual"]["center"],
})
print(f"Created individual: {individual.system_id}")

# 2. Create samples
samples = {}
for sample_data in submission_data["samples"]:
    sample = ii.create_instance("samples", {
        "identifier": sample_data["identifier"],
        "category": sample_data["category"],
        "disease": sample_data["disease"],
        "individual": {"pk": individual.pk},
    })
    samples[sample_data["identifier"]] = sample
    print(f"Created sample: {sample.system_id}")

# 3. Create experiments
for exp_data in submission_data["experiments"]:
    sample = samples[exp_data["sample_identifier"]]
    experiment = ii.create_instance("experiments", {
        "identifier": exp_data["identifier"],
        "sample": {"pk": sample.pk},
        "technique": exp_data["technique"],
        "platform": exp_data["platform"],
        "center": exp_data["center"],
        "raw_data": exp_data["raw_data"],
        "projects": [{"pk": PROJECT_PK}],
    })
    print(f"Created experiment: {experiment.system_id}")
```

--------------------------------

### Implement get_command() in isabl_cli application

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-write-app/SKILL.md

Implement the get_command() method to generate the shell command that will be executed. It uses the analysis target's BAM file URL and the application settings for the tool path and thread count.

```python
from isabl_cli import AbstractApplication, options

class MyApplication(AbstractApplication):
    NAME = "my_application"
    VERSION = "1.0.0"
    cli_options = [options.TARGETS]

    application_settings = {
        "tool_path": "/usr/bin/mytool",
        "threads": 4,
    }

    def get_command(self, analysis, inputs, settings):
        """
        Return the shell command to execute.
        This is the core of the application.
        """
        target = analysis.targets[0]
        output_dir = analysis.storage_url

        return f"""
        {settings.tool_path} \\
            --input {target.bam_files["GRCh37"]["url"]} \\
            --output {output_dir}/result.txt \\
            --threads {settings.threads}
        """
```

--------------------------------

### Retrieve analysis results with isabl_cli.utils

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Use utils.get_result and utils.get_results to retrieve analysis results from an experiment. get_result returns a tuple of the result path and the analysis object, while get_results returns all results for a given application.

```python
import isabl_cli as ii
from isabl_cli import utils

# Get specific result from an experiment
vcf_path, analysis = utils.get_result(
    experiment=experiment,
    application_key=123,
    result_key="vcf"
)
print(f"VCF: {vcf_path}")

# Get all results for an application
results = utils.get_results(
    experiment=experiment,
    application_name="variant_caller"
)
```

--------------------------------

### Implement get_dependencies() in isabl_cli application

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-write-app/SKILL.md

Define the get_dependencies() method to declare dependencies on other application results. It uses utils.get_result() to fetch a BAM file from a specified alignment application and returns a tuple of dependency analysis keys and an inputs dictionary.

```python
from isabl_cli import AbstractApplication, options, utils

class MyApplication(AbstractApplication):
    NAME = "my_application"
    VERSION = "1.0.0"
    cli_options = [options.TARGETS]

    application_settings = {
        "alignment_app_pk": 10,  # PK of alignment application
    }

    def get_dependencies(self, targets, references, settings):
        """
        Return (dependency_analyses, inputs_dict) if this app needs
        results from other applications.
        """
        bam, analysis_key = utils.get_result(
            experiment=targets[0],
            application_key=settings.alignment_app_pk,
            result_key="bam"
        )
        return [analysis_key], {"input_bam": bam}
```

--------------------------------

### Run analysis locally with --local

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-debug-analysis/SKILL.md

Run the analysis locally instead of on the batch system for debugging purposes.

```bash
# Execute locally instead of batch system
isabl myapp-1-0 --targets EXPERIMENT_ID --local --commit
```

--------------------------------

### MCP isabl_query for experiments

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-query-data/SKILL.md

Preferred MCP isabl_query call for experiments, using filters and output_fields to return system_id.

```python
isabl_query(
    endpoint="experiments",
    filters={"projects": 102},
    output_fields=["system_id"]
)
```

--------------------------------

### Verify pipeline completion with ii.get_analyses

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-run-pipeline/SKILL.md

Verifies that all pipeline steps completed successfully by counting analyses with status SUCCEEDED for each app. It compares the actual count against the expected number (based on experiments or pairs) and prints a summary with checkmarks. Returns True if all steps are complete.

```python
def verify_pipeline(project_pk, pipeline, experiments, pairs=None):
    """Verify all pipeline steps completed successfully."""
    results = {}

    for step in pipeline:
        app_name = step["app"].rsplit("-", 1)[0]  # Remove version

        analyses = list(ii.get_analyses(
            projects=project_pk,
            application__name=app_name,
            status="SUCCEEDED"
        ))

        expected = len(experiments) if step["type"] == "TARGETS" else len(pairs or [])
        actual = len(analyses)

        results[step["app"]] = {
            "expected": expected,
            "succeeded": actual,
            "complete": actual >= expected
        }

    print("\n=== Pipeline Verification ===")
    all_complete = True
    for app, stats in results.items():
        status = "✓" if stats["complete"] else "✗"
        print(f"  {status} {app}: {stats['succeeded']}/{stats['expected']}")
        if not stats["complete"]:
            all_complete = False

    return all_complete

verify_pipeline(PROJECT_PK, PIPELINE, experiments, pairs=pairs)
```

--------------------------------

### Bulk import using submission form with isabl API

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-submit-data/SKILL.md

Creates a submission form for bulk import and processes it with commit=True. The data field expects a list of experiment dictionaries.

```python
# Create submission form for bulk import
submission = ii.create_instance("submissions", {
    "title": "Batch import 2024-01",
    "data": {
        "experiments": [...],  # List of experiment dicts
    },
})

# Process the submission
ii.process_submission(submission.pk, commit=True)
```

--------------------------------

### Generate bulk retry commands for failed analyses

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-monitor-analyses/SKILL.md

Retrieves failed MUTECT analyses for a project and prints retry commands using the `isabl mutect-2-0` CLI with the `--force` and `--commit` flags. Requires `ii` and `PROJECT_PK` to be defined.

```python
# Get failed analyses to retry
failed = list(ii.get_analyses(
    projects=PROJECT_PK,
    application__name="MUTECT",
    status="FAILED"
))

# Generate retry commands
print("# Retry commands:")
for a in failed:
    target = a.targets[0].system_id if a.targets else ""
    print(f"isabl mutect-2-0 --targets {target} --force --commit")
```

--------------------------------

### Find samples without a specific app (MUTECT)

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-project-report/SKILL.md

Identifies experiments that lack a MUTECT analysis by comparing experiment primary keys with those targeted by MUTECT analyses. Requires PROJECT_PK.

```python
# All experiments in project
all_exps = set(e.pk for e in ii.get_experiments(projects=PROJECT_PK))

# Experiments with MUTECT analysis
mutect_exps = set()
for a in ii.get_analyses(projects=PROJECT_PK, application__name="MUTECT"):
    mutect_exps.update(t.pk for t in a.targets)

# Missing
missing = all_exps - mutect_exps
print(f"Experiments without MUTECT: {len(missing)}")
```

--------------------------------

### Verify Files Exist

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-merge-results/SKILL.md

Checks which collected paths exist on disk using os.path.exists. Prints counts of valid and missing paths, and lists the first five missing files.

```python
import os

valid_paths = []
missing = []

for item in paths:
    if os.path.exists(item["path"]):
        valid_paths.append(item)
    else:
        missing.append(item)

print(f"Valid: {len(valid_paths)}, Missing: {len(missing)}")

if missing:
    print("Missing files:")
    for m in missing[:5]:
        print(f"  Analysis {m['analysis_pk']}: {m['path']}")
```

--------------------------------

### Verify target experiment data

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-debug-analysis/SKILL.md

Iterate over the analysis targets and print their system ID, raw data, and BAM files to verify that input data exists.

```python
# Verify target experiments have data
for target in analysis.targets:
    print(f"{target.system_id}:")
    print(f"  Raw data: {target.raw_data}")
    print(f"  BAM files: {target.bam_files}")
```

--------------------------------

### View head_job.sh command script

Source: https://github.com/juanesarango/isabl-mcp/blob/main/skills/isabl-debug-analysis/SKILL.md

Display the generated command script (head_job.sh) for the analysis. Inspect it for incorrect paths, missing environment variables, or malformed command syntax.

```bash
# View the command that was executed
cat {analysis.storage_url}/head_job.sh
```
Tokens:
Raw