JaimeCernuda/adios_mcp_server

ADIOS2 BP5 MCP Server

This project provides a Model Context Protocol (MCP) server for interacting with ADIOS2 BP5 files. It allows LLM-powered clients like Claude Desktop or custom agents to inspect metadata, read data slices, and understand the contents of scientific datasets stored in the BP5 format.

Features

• List Variables: Discover all variables within a BP5 file, including their type, shape, and available steps.
• Describe Variables: Get detailed decomposition information for any variable, showing block-level statistics (min/max) for each step.
• Read Data: Read data from any variable, with support for slicing dimensions and selecting specific steps.
• Inspect Attributes: List and read global and variable-specific attributes.
• Dual Transport: Supports both stdio for local integrations (e.g., Claude Desktop) and a streamable HTTP interface for network-based clients.

Installation

It is recommended to use uv for managing Python environments.

1. Clone the repository:

   git clone https://github.com/your-username/adios2-mcp-server.git
   cd adios2-mcp-server
   

2. Create a virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
   uv pip install -e .
   

Usage

The server can be run using two different transports: stdio or http.

1. Standard I/O (stdio) Transport

This is the standard for local integrations with clients like Claude Desktop or the MCP Inspector.

Running directly:

python src/adios_mcp_server/server.py

Using the mcp CLI for development and testing: The MCP Inspector is a powerful tool for debugging your server.

# Start the server in development mode with the MCP Inspector
mcp dev src/adios_mcp_server/server.py

# To test with a specific file:
mcp dev src/adios_mcp_server/server.py -- --file-path /path/to/your/data.bp

2. Streamable HTTP Transport

This exposes the server over HTTP, allowing network clients to connect.

Start the server with Uvicorn:

uvicorn adios_mcp_server.server:app --host 0.0.0.0 --port 8000

The MCP SSE endpoint will be available at http://localhost:8000/. You can test it with curl:

# Example: Send an `initialize` request
curl -X POST -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"curl-test"},"capabilities":{}}}' \
     http://localhost:8000/

Tool Reference

The server exposes the following tools:

Testing

To run the test suite:

# Install test dependencies
pip install pytest

# Run tests
pytest tests/

The tests create sample BP5 files and verify that all MCP tools work correctly with various data types and configurations.

Examples

Example 1: Basic Variable Inspection

# List all variables in a BP5 file
result = list_variables("/path/to/simulation.bp")
print(result)

# Get detailed info about a specific variable
result = describe_variable("/path/to/simulation.bp", "temperature")
print(result)

Example 2: Reading Data Slices

# Read full data for all steps
result = read_data("/path/to/simulation.bp", "temperature")

# Read a specific spatial slice from step 10-20
result = read_data(
    "/path/to/simulation.bp",
    "temperature",
    start=[0, 0, 50],
    count=[100, 100, 50],
    step_start=10,
    step_count=10
)

Example 3: Attribute Inspection

# List all attributes
result = list_attributes("/path/to/simulation.bp")

# Read a specific attribute
result = read_attribute("/path/to/simulation.bp", "simulation_time")

Configuration

Claude Desktop Integration

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "adios2-bp5": {
      "command": "python",
      "args": ["/path/to/adios2-mcp-server/src/adios_mcp_server/server.py"],
      "env": {}
    }
  }
}

Environment Variables

You can configure the server using environment variables:

• ADIOS2_MCP_LOG_LEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR)
• ADIOS2_MCP_MAX_ARRAY_SIZE: Maximum array size to return in JSON (default: 10000 elements)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• ADIOS2 for the high-performance I/O framework
• Model Context Protocol for the protocol specification
• FastMCP for the high-level MCP server framework