clio-kit 2.0.0__py3-none-any.whl

clio_kit/__init__.py

@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+import os
+import sys
+import subprocess
+from pathlib import Path
+import click
+
+# Determine if we're running from development or installed package
+MODULE_DIR = Path(__file__).parent
+
+def get_servers_path():
+    """Get the path to servers directory (dev or installed)"""
+    # First try development path (../../clio-kit-mcp-servers from module)
+    dev_path = MODULE_DIR.parent.parent / "clio-kit-mcp-servers"
+    if dev_path.exists():
+        return dev_path
+
+    # Try to find shared data in the installed package
+    # When installed via wheel, shared data goes to site-packages/
+    # Look for clio-kit-mcp-servers directory in various possible locations
+    possible_paths = [
+        # Standard site-packages installation
+        MODULE_DIR.parent / "clio-kit-mcp-servers",  # ../clio-kit-mcp-servers from module
+        # Alternative installation paths
+        MODULE_DIR / "clio-kit-mcp-servers",  # ./clio-kit-mcp-servers from module (if included directly)
+        # System-wide data directory
+        Path(sys.prefix) / "share" / "clio-kit" / "clio-kit-mcp-servers",
+        # Local data directory
+        Path.home() / ".local" / "share" / "clio-kit" / "clio-kit-mcp-servers",
+    ]
+
+    # Try each possible path
+    for path in possible_paths:
+        if path.exists() and path.is_dir():
+            return path
+
+    # If none found, check if we're in an isolated environment (like uvx)
+    # and try to find the data directory relative to the Python executable
+    python_path = Path(sys.executable)
+    isolated_paths = [
+        # uvx style isolated environment - clio-kit-mcp-servers is at the root level
+        python_path.parent.parent / "clio-kit-mcp-servers",
+        python_path.parent.parent / "share" / "clio-kit-mcp-servers",
+        python_path.parent.parent / "purelib" / "clio-kit-mcp-servers",
+        python_path.parent.parent / "data" / "clio-kit-mcp-servers",
+    ]
+
+    for path in isolated_paths:
+        if path.exists() and path.is_dir():
+            return path
+
+    # Last resort: return the dev path even if it doesn't exist
+    # so the caller can handle the missing directory appropriately
+    return dev_path
+
+def get_prompts_path():
+    """Get the path to prompts directory (dev or installed)"""
+    # First try development path (../../prompts from module)
+    dev_path = MODULE_DIR.parent.parent / "prompts"
+    if dev_path.exists():
+        return dev_path
+
+    # Try to find shared data in the installed package
+    possible_paths = [
+        # Standard site-packages installation
+        MODULE_DIR.parent / "prompts",  # ../prompts from module
+        # Alternative installation paths
+        MODULE_DIR / "prompts",  # ./prompts from module
+        # System-wide data directory
+        Path(sys.prefix) / "share" / "clio-kit" / "prompts",
+        # Local data directory
+        Path.home() / ".local" / "share" / "clio-kit" / "prompts",
+    ]
+
+    # Try each possible path
+    for path in possible_paths:
+        if path.exists() and path.is_dir():
+            return path
+
+    # If none found, check if we're in an isolated environment (like uvx)
+    python_path = Path(sys.executable)
+    isolated_paths = [
+        # uvx style isolated environment
+        python_path.parent.parent / "prompts",
+        python_path.parent.parent / "share" / "prompts",
+        python_path.parent.parent / "purelib" / "prompts",
+        python_path.parent.parent / "data" / "prompts",
+    ]
+
+    for path in isolated_paths:
+        if path.exists() and path.is_dir():
+            return path
+
+    # Last resort: return the dev path
+    return dev_path
+
+def auto_discover_mcps():
+    """Auto-discover MCP servers from the clio-kit-mcp-servers directory"""
+    servers_path = get_servers_path()
+    if not servers_path.exists():
+        return {}, {}
+
+    server_command_map = {}
+    dir_name_map = {}
+
+    # Scan for directories containing pyproject.toml
+    for item in servers_path.iterdir():
+        if item.is_dir() and not item.name.startswith('.'):
+            pyproject_file = item / "pyproject.toml"
+            if pyproject_file.exists():
+                # Read pyproject.toml to extract entry point
+                try:
+                    with open(pyproject_file, 'r') as f:
+                        content = f.read()
+
+                    # Simple parsing to find the entry point
+                    # Look for lines like: server-name-mcp = "module:main"
+                    entry_point = None
+                    for line in content.split('\n'):
+                        line = line.strip()
+                        if '-mcp =' in line and '=' in line:
+                            entry_point = line.split('=')[0].strip().strip('"\'')
+                            break
+
+                    if entry_point:
+                        # Create server name by removing -mcp suffix
+                        server_name = entry_point.replace('-mcp', '').lower()
+                        # Handle special cases for naming
+                        if server_name == 'node-hardware':
+                            server_name = 'node-hardware'
+                        elif server_name == 'parallel-sort':
+                            server_name = 'parallel-sort'
+
+                        server_command_map[server_name] = entry_point
+                        dir_name_map[server_name] = item.name
+
+                except Exception as e:
+                    # Skip directories that can't be processed
+                    continue
+
+    return server_command_map, dir_name_map
+
+def auto_discover_prompts():
+    """Auto-discover prompts from the prompts directory (recursively)"""
+    prompts_path = get_prompts_path()
+    if not prompts_path.exists():
+        return {}
+
+    prompt_map = {}
+
+    # Recursively scan for .md files
+    for md_file in prompts_path.rglob("*.md"):
+        # Get relative path from prompts directory
+        relative_path = md_file.relative_to(prompts_path)
+
+        # Create prompt name from relative path without extension
+        # e.g., "code-coverage-prompt.md" -> "code-coverage-prompt"
+        # e.g., "testing/foo.md" -> "testing/foo"
+        prompt_name = str(relative_path.with_suffix(''))
+
+        # Also support underscore version
+        # "code-coverage-prompt" -> also accessible as "code_coverage_prompt"
+        prompt_map[prompt_name] = md_file
+        prompt_map[prompt_name.replace('-', '_')] = md_file
+
+    return prompt_map
+
+def list_available_servers():
+    """List all available servers"""
+    server_command_map, _ = auto_discover_mcps()
+    return sorted(server_command_map.keys())
+
+def list_available_prompts():
+    """List all available prompts"""
+    prompt_map = auto_discover_prompts()
+    # Remove duplicates (dash vs underscore versions)
+    unique_prompts = set()
+    for name in prompt_map.keys():
+        # Normalize to dash version for display
+        unique_prompts.add(name.replace('_', '-'))
+    return sorted(unique_prompts)
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def main(ctx):
+    """clio-kit: Unified launcher for MCP servers and AI prompts"""
+    if ctx.invoked_subcommand is None:
+        click.echo("clio-kit: Unified launcher for MCP servers and AI prompts")
+        click.echo("\nAvailable commands:")
+        click.echo("  mcp-server   Run an MCP server")
+        click.echo("  mcp-servers  List all available MCP servers")
+        click.echo("  prompt       Print a prompt to stdout")
+        click.echo("  prompts      List all available prompts")
+        click.echo("\nUsage:")
+        click.echo("  uvx clio-kit mcp-server <server-name>")
+        click.echo("  uvx clio-kit prompt <prompt-name>")
+        click.echo("\nFor more help: uvx clio-kit <command> --help")
+
+@main.command("mcp-server")
+@click.argument('server', required=False)
+@click.option('-b', '--branch', help='Git branch to use (for development)')
+@click.argument('args', nargs=-1, type=click.UNPROCESSED)
+def mcp_server(server, branch, args):
+    """Run an MCP server. List all if no server specified."""
+
+    server_command_map, dir_name_map = auto_discover_mcps()
+
+    if not server:
+        click.echo("Available MCP servers:")
+        for s in sorted(server_command_map.keys()):
+            click.echo(f"  - {s}")
+        click.echo("\nUsage: uvx clio-kit mcp-server <server-name>")
+        click.echo("   or: clio-kit mcp-server <server-name> (if installed)")
+        return
+
+    # Normalize server name to lowercase
+    server_lower = server.lower()
+
+    if server_lower not in server_command_map:
+        click.echo(f"Error: Unknown server '{server}'")
+        click.echo(f"Available servers: {', '.join(sorted(server_command_map.keys()))}")
+        sys.exit(1)
+
+    # Get the entry point command and directory name
+    entry_command = server_command_map[server_lower]
+    actual_dir = dir_name_map[server_lower]
+
+    # Build uvx command
+    if branch:
+        # Run from git branch
+        cmd = [
+            "uvx",
+            "--from",
+            f"git+https://github.com/iowarp/clio-kit.git@{branch}#subdirectory=clio-kit-mcp-servers/{actual_dir}",
+            entry_command
+        ]
+    else:
+        # Run from local path in development mode
+        servers_path = get_servers_path()
+        server_path = servers_path / actual_dir
+
+        if server_path.exists():
+            # Development mode - run from local path
+            cmd = [
+                "uvx",
+                "--from",
+                str(server_path),
+                entry_command
+            ]
+        else:
+            # Not in development, try to run the command directly (if installed)
+            cmd = [entry_command]
+
+    # Add any additional arguments
+    cmd.extend(args)
+
+    # Execute the command
+    try:
+        subprocess.run(cmd, check=True)
+    except subprocess.CalledProcessError as e:
+        sys.exit(e.returncode)
+    except FileNotFoundError:
+        if cmd[0] == "uvx":
+            click.echo("Error: uvx not found. Please install uv: https://github.com/astral-sh/uv")
+        else:
+            click.echo(f"Error: {entry_command} not found. Please install the server package.")
+        sys.exit(1)
+
+@main.command("mcp-servers")
+def list_mcp_servers():
+    """List all available MCP servers"""
+    servers = list_available_servers()
+    if servers:
+        click.echo("Available MCP servers:")
+        for s in servers:
+            click.echo(f"  - {s}")
+    else:
+        click.echo("No MCP servers found.")
+
+@main.command("prompt")
+@click.argument('prompt_name', required=False)
+def prompt(prompt_name):
+    """Print a prompt to stdout. List all if no name specified."""
+
+    prompt_map = auto_discover_prompts()
+
+    if not prompt_name:
+        # List all prompts
+        prompts = list_available_prompts()
+        if prompts:
+            click.echo("Available prompts:")
+            for p in prompts:
+                click.echo(f"  - {p}")
+        else:
+            click.echo("No prompts found.")
+        click.echo("\nUsage: uvx clio-kit prompt <prompt-name>")
+        click.echo("   or: clio-kit prompt <prompt-name> (if installed)")
+        return
+
+    # Normalize prompt name (support both dash and underscore)
+    prompt_lower = prompt_name.lower()
+
+    if prompt_lower not in prompt_map:
+        click.echo(f"Error: Unknown prompt '{prompt_name}'")
+        click.echo(f"Available prompts: {', '.join(list_available_prompts())}")
+        sys.exit(1)
+
+    # Read and print the prompt file
+    prompt_file = prompt_map[prompt_lower]
+    try:
+        with open(prompt_file, 'r') as f:
+            content = f.read()
+        click.echo(content)
+    except Exception as e:
+        click.echo(f"Error reading prompt file: {e}")
+        sys.exit(1)
+
+@main.command("prompts")
+def list_prompts_cmd():
+    """List all available prompts"""
+    prompts = list_available_prompts()
+    if prompts:
+        click.echo("Available prompts:")
+        for p in prompts:
+            click.echo(f"  - {p}")
+    else:
+        click.echo("No prompts found.")
+
+def cli():
+    """Entry point for the CLI"""
+    main()
+
+if __name__ == "__main__":
+    main()

clio_kit-2.0.0.data/data/clio-kit-mcp-servers/adios/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "clio-adios",
+  "description": "Fetch and analyze BP5 data files using ADIOS2. Access scientific data, metadata, and attributes for research and analysis purposes.",
+  "version": "1.0.0"
+}

clio_kit-2.0.0.data/data/clio-kit-mcp-servers/adios/.gitignore

@@ -0,0 +1,27 @@
+
+.venv/
+
+
+__pycache__/
+*.pyc
+
+
+*.gz
+*.png
+*.log
+
+
+*.coverage
+.coverage
+htmlcov/
+
+
+.vscode/
+.idea/
+
+# Python packaging artifacts
+*.egg-info/
+*.egg-info
+build/
+dist/
+*.egg

clio_kit-2.0.0.data/data/clio-kit-mcp-servers/adios/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "clio-adios": {
+    "command": "uvx",
+    "args": [
+      "clio-kit",
+      "adios"
+    ]
+  }
+}

clio_kit-2.0.0.data/data/clio-kit-mcp-servers/adios/README.md

@@ -0,0 +1,323 @@
+# Adios MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/adios-mcp.svg)](https://pypi.org/project/adios-mcp/)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
+
+**Part of [CLIO Kit](https://toolkit.iowarp.ai/) - Gnosis Research Center**
+
+ADIOS MCP is a comprehensive Model Context Protocol (MCP) server that enables Language Learning Models (LLMs) to access and analyze scientific simulation and real-time data through the ADIOS2 framework. This server provides read-only access to BP5 datasets with intelligent data handling and seaml...
+
+## Quick Start
+
+```bash
+uvx clio-kit mcp-server adios
+```
+
+## Documentation
+
+- **Full Documentation**: [CLIO Kit Website](https://toolkit.iowarp.ai/)
+- **Installation Guide**: See [INSTALLATION.md](../../../CLAUDE.md#setup--installation)
+- **Contributing**: See [Contribution Guide](https://github.com/iowarp/clio-kit/wiki/Contribution)
+
+---
+
+## Description
+
+ADIOS MCP is a comprehensive Model Context Protocol (MCP) server that enables Language Learning Models (LLMs) to access and analyze scientific simulation and real-time data through the ADIOS2 framework. This server provides read-only access to BP5 datasets with intelligent data handling and seamless integration with AI coding assistants.
+
+
+
+**Key Features:**
+- **High-Performance Data Access**: Read-only access to ADIOS2 BP5 files with optimized I/O operations
+- **Intelligent Data Processing**: Automatic variable type detection, shape analysis, and step-based data handling
+- **Multiple Data Operations**: Variable inspection, attribute reading, data slicing, and statistical analysis
+- **Scientific Computing Support**: Time-series analysis, multi-dimensional arrays, and metadata handling
+- **Cross-Platform Compatibility**: Pure Python implementation for Linux, macOS, and Windows
+- **MCP Integration**: Full Model Context Protocol compliance for seamless LLM integration
+
+
+
+## 🛠️ Installation
+
+### Requirements
+
+- Python 3.10 or higher
+- [uv](https://docs.astral.sh/uv/) package manager (recommended)
+- Linux/macOS environment (Windows supported)
+
+<details>
+<summary><b>Install in Cursor</b></summary>
+
+Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
+
+Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
+
+```json
+{
+  "mcpServers": {
+    "adios-mcp": {
+      "command": "uvx",
+      "args": ["clio-kit", "mcp-server", "adios"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in VS Code</b></summary>
+
+Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
+
+```json
+"mcp": {
+  "servers": {
+    "adios-mcp": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["clio-kit", "mcp-server", "adios"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in Claude Code</b></summary>
+
+Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp) for more info.
+
+```sh
+claude mcp add adios-mcp -- uvx clio-kit mcp-server adios
+```
+
+</details>
+
+<details>
+<summary><b>Install in Claude Desktop</b></summary>
+
+Add this to your Claude Desktop `claude_desktop_config.json` file. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.
+
+```json
+{
+  "mcpServers": {
+    "adios-mcp": {
+      "command": "uvx",
+      "args": ["clio-kit", "mcp-server", "adios"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Manual Setup</b></summary>
+
+**Linux/macOS:**
+```bash
+CLONE_DIR=$(pwd)
+git clone https://github.com/iowarp/clio-kit.git
+uv --directory=$CLONE_DIR/clio-kit/clio-kit-mcp-servers/adios run adios-mcp --help
+```
+ 
+**Windows CMD:**
+```cmd
+set CLONE_DIR=%cd%
+git clone https://github.com/iowarp/clio-kit.git
+uv --directory=%CLONE_DIR%\clio-kit\clio-kit-mcp-servers\adios run adios-mcp --help
+```
+ 
+**Windows PowerShell:**
+```powershell
+$env:CLONE_DIR=$PWD
+git clone https://github.com/iowarp/clio-kit.git
+uv --directory=$env:CLONE_DIR\clio-kit\clio-kit-mcp-servers\adios run adios-mcp --help
+```
+
+</details>
+
+## Capabilities
+
+### `list_bp5`
+**Description**: Lists all BP5 files in a given directory. The 'directory' parameter must be an absolute path.
+**Hints**: read-only, idempotent
+**Tags**: adios, scientific-io
+
+### `inspect_variables`
+**Description**: Inspects variables in a BP5 file, returning type, shape, and steps. Optionally filters by variable name.
+**Hints**: read-only, idempotent
+**Tags**: adios, variables
+
+### `inspect_variables_at_step`
+**Description**: Inspects a specific variable at a given step in a BP5 file. All parameters are required.
+**Hints**: read-only, idempotent
+**Tags**: adios, variables
+
+### `inspect_attributes`
+**Description**: Reads global or variable-specific attributes from a BP5 file. The 'variable_name' is optional.
+**Hints**: read-only, idempotent
+**Tags**: adios, attributes
+
+### `read_variable_at_step`
+**Description**: Reads a named variable at a specific step from a BP5 file. All parameters are required.
+**Hints**: read-only, idempotent
+**Tags**: adios, variables
+
+### Resources
+
+- `adios://capabilities` - ADIOS2 file format capabilities and supported engines.
+
+### Prompts
+
+- **explore_bp_file**: Guided workflow for exploring an ADIOS2 BP file.
+## Claude Code
+
+```bash
+claude mcp add clio-adios -- uvx clio-kit adios
+```
+
+Or install via the CLIO Kit plugin marketplace:
+
+```
+/plugin marketplace add iowarp/clio-kit
+/plugin install clio-adios@iowarp-clio-kit
+```
+## Claude Desktop
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "clio-adios": {
+      "command": "uvx",
+      "args": [
+        "clio-kit",
+        "adios"
+      ]
+    }
+  }
+}
+```
+## Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "clio-adios": {
+      "command": "uvx",
+      "args": [
+        "clio-kit",
+        "adios"
+      ]
+    }
+  }
+}
+```
+
+Or install the CLIO Kit extension:
+
+```bash
+gemini extensions install https://github.com/iowarp/clio-kit
+```
+## Examples
+
+### 1. Scientific Data Structure Analysis
+```
+I have a BP5 simulation file at /data/simulation_results.bp. Can you first analyze the data structure and then show me the temperature variable evolution over time?
+```
+
+**Tools called:**
+- `inspect_variables` - Analyze the dataset structure and available variables
+- `read_variable_at_step` - Read temperature data at specific time steps
+
+This prompt will:
+- Use `inspect_variables` to analyze the BP5 file structure and discover all variables
+- Extract temperature variable data using `read_variable_at_step` at different time steps
+- Provide insights about the simulation data structure and temporal evolution
+
+### 2. Multi-Variable Scientific Analysis
+```
+Using the file /data/fluid_dynamics.bp, perform a comprehensive analysis showing:
+1. All available variables and their properties
+2. Pressure field at step 50
+3. Variable metadata and attributes for the pressure field
+```
+
+**Tools called:**
+- `inspect_variables` - List all available variables and properties
+- `read_variable_at_step` - Extract pressure field at step 50
+- `inspect_attributes` - Get pressure variable metadata
+
+This prompt will:
+- Generate comprehensive variable inventory using `inspect_variables`
+- Extract specific time step data using `read_variable_at_step`
+- Analyze variable metadata with `inspect_attributes`
+- Provide detailed analysis of fluid dynamics simulation data
+
+### 3. Time-Series Variable Inspection
+```
+From /data/climate_model.bp, I want to understand the temperature variable structure across different time steps and inspect its properties at step 25.
+```
+
+**Tools called:**
+- `inspect_variables` - Get temperature variable structure and available steps
+- `inspect_variables_at_step` - Detailed inspection at step 25
+
+This prompt will:
+- Use `inspect_variables` to understand overall variable structure
+- Use `inspect_variables_at_step` to get detailed information at a specific time step
+- Provide comprehensive time-series data structure analysis
+
+### 4. High-Performance Computing Data Analysis
+```
+Analyze the simulation output at /data/parallel_computation.bp - show me the variable structure, read specific computational domain data, and extract metadata attributes.
+```
+
+**Tools called:**
+- `inspect_variables` - Analyze computational variables and structure
+- `inspect_attributes` - Extract simulation metadata and parameters
+- `read_variable_at_step` - Read domain-specific data
+
+This prompt will:
+- Use `inspect_variables` to understand parallel computation structure
+- Extract simulation parameters with `inspect_attributes`
+- Read specific computational domain data using `read_variable_at_step`
+- Provide HPC-focused data analysis
+
+### 5. Scientific Data Validation and Exploration
+```
+I need to validate the integrity of my ADIOS dataset at /data/experimental_results.bp - check all variables, their step-wise properties, and ensure metadata completeness.
+```
+
+**Tools called:**
+- `inspect_variables` - Comprehensive variable structure validation
+- `inspect_variables_at_step` - Step-specific variable validation
+- `inspect_attributes` - Metadata integrity check
+
+This prompt will:
+- Use `inspect_variables` to validate overall data structure integrity
+- Perform step-specific analysis with `inspect_variables_at_step`
+- Check metadata completeness with `inspect_attributes`
+- Provide comprehensive data quality assessment for scientific workflows
+
+### 6. Quick BP5 File Discovery
+```
+Show me all BP5 files in my simulation directory at /data/simulations/ and provide a quick overview of their contents and structure.
+```
+
+**Tools called:**
+- `list_bp5` - Directory-wide BP5 file discovery
+- `inspect_variables` - Quick structure overview for each file
+
+This prompt will:
+- Use `list_bp5` to discover all BP5 files in the directory
+- Use `inspect_variables` to provide structural overview of discovered files
+- Generate comprehensive overview of available simulation datasets
+- Suggest optimal data access strategies based on file contents