Metadata-Version: 2.4
Name: ngff-zarr-mcp
Version: 0.1.1
Summary: Model Context Protocol server for OME-Zarr image conversion
Project-URL: Documentation, https://github.com/thewtex/ngff-zarr#readme
Project-URL: Issues, https://github.com/thewtex/ngff-zarr/issues
Project-URL: Source, https://github.com/thewtex/ngff-zarr
Author-email: Matt McCormick <matt@fideus.io>
License-Expression: MIT
Keywords: image-conversion,mcp,microscopy,ome-zarr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: aiofiles
Requires-Dist: httpx
Requires-Dist: mcp
Requires-Dist: ngff-zarr[cli]
Requires-Dist: pathvalidate
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: gcsfs; extra == 'all'
Requires-Dist: ngff-zarr[all]; extra == 'all'
Requires-Dist: s3fs; extra == 'all'
Provides-Extra: cloud
Requires-Dist: gcsfs; extra == 'cloud'
Requires-Dist: s3fs; extra == 'cloud'
Provides-Extra: dev
Requires-Dist: black>=23.1.0; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff>=0.0.243; extra == 'dev'
Requires-Dist: types-aiofiles; extra == 'dev'
Requires-Dist: types-psutil; extra == 'dev'
Description-Content-Type: text/markdown

# ngff-zarr MCP Server

A Model Context Protocol (MCP) server that provides AI agents with the ability to convert images to OME-Zarr format using the ngff-zarr library.

## Features

### Tools
- **convert_images_to_ome_zarr**: Convert various image formats to OME-Zarr with full control over metadata, compression, and multiscale generation
- **get_ome_zarr_info**: Inspect existing OME-Zarr stores and get detailed information
- **validate_ome_zarr_store**: Validate OME-Zarr structure and metadata
- **optimize_ome_zarr_store**: Optimize existing stores with new compression and chunking

### Resources
- **supported-formats**: List of supported input/output formats and backends
- **downsampling-methods**: Available downsampling methods for multiscale generation
- **compression-codecs**: Available compression codecs and their characteristics

### Input Support
- Local files (all formats supported by ngff-zarr)
- Local directories (Zarr stores)
- Network URLs (HTTP/HTTPS)
- S3 URLs (with optional s3fs dependency)

### Output Optimization
- Multiple compression codecs (gzip, lz4, zstd, blosc variants)
- Configurable compression levels
- Flexible chunk sizing
- Sharding support (Zarr v3/OME-Zarr v0.5)
- OME-Zarr version selection (0.4 or 0.5)

## Installation

### Requirements

- Python >= 3.9
- Cursor, Windsurf, Claude Desktop, VS Code, or another MCP Client

### Quick Install

The easiest way to use ngff-zarr MCP server is with `uvx`:

```bash
# Install uvx if not already installed  
pip install uvx

# Run the MCP server directly from PyPI
uvx ngff-zarr-mcp
```

<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.

#### Using uvx (recommended)
```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

#### Using direct Python
```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "python",
      "args": ["-m", "pip", "install", "ngff-zarr-mcp", "&&", "ngff-zarr-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Install in Windsurf</b></summary>

Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.

#### Using uvx (recommended)
```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

#### SSE Transport
```json
{
  "mcpServers": {
    "ngff-zarr": {
      "url": "http://localhost:8000/sse",
      "description": "ngff-zarr server running with SSE transport"
    }
  }
}
```

</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.

#### Using uvx (recommended)
```json
"mcp": {
  "servers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

#### Using pip install
```json
"mcp": {
  "servers": {
    "ngff-zarr": {
      "command": "python",
      "args": ["-c", "import subprocess; subprocess.run(['pip', 'install', 'ngff-zarr-mcp']); import ngff_zarr_mcp.server; ngff_zarr_mcp.server.main()"]
    }
  }
}
```

</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.

#### Using uvx (recommended)
```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

#### Using direct installation
```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "ngff-zarr-mcp"
    }
  }
}
```

</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.

#### Using uvx
```sh
claude mcp add ngff-zarr -- uvx ngff-zarr-mcp
```

#### Using pip
```sh
claude mcp add ngff-zarr -- python -m pip install ngff-zarr-mcp && ngff-zarr-mcp
```

</details>

<details>
<summary><b>Install in Cline</b></summary>

1. Open **Cline**.
2. Click the hamburger menu icon (☰) to enter the **MCP Servers** section.
3. Add a new server with the following configuration:

#### Using uvx (recommended)
```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Install in BoltAI</b></summary>

Open the "Settings" page of the app, navigate to "Plugins," and enter the following JSON:

```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

Once saved, you can start using ngff-zarr tools in your conversations. More information is available on [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers).

</details>

<details>
<summary><b>Install in Zed</b></summary>

Add this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.

```json
{
  "context_servers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Install in Augment Code</b></summary>

### **A. Using the Augment Code UI**

1. Click the hamburger menu.
2. Select **Settings**.
3. Navigate to the **Tools** section.
4. Click the **+ Add MCP** button.
5. Enter the following command: `uvx ngff-zarr-mcp`
6. Name the MCP: **ngff-zarr**.
7. Click the **Add** button.

### **B. Manual Configuration**

1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel
2. Select Edit Settings
3. Under Advanced, click Edit in settings.json
4. Add the server configuration:

```json
"augment.advanced": {
  "mcpServers": [
    {
      "name": "ngff-zarr",
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  ]
}
```

</details>

<details>
<summary><b>Install in JetBrains AI Assistant</b></summary>

See [JetBrains AI Assistant Documentation](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) for more details.

1. In JetBrains IDEs go to `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`
2. Click `+ Add`.
3. Click on `Command` in the top-left corner of the dialog and select the As JSON option from the list
4. Add this configuration and click `OK`

```json
{
  "command": "uvx",
  "args": ["ngff-zarr-mcp"]
}
```

5. Click `Apply` to save changes.

</details>

<details>
<summary><b>Install in Qodo Gen</b></summary>

See [Qodo Gen docs](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) for more details.

1. Open Qodo Gen chat panel in VSCode or IntelliJ.
2. Click Connect more tools.
3. Click + Add new MCP.
4. Add the following configuration:

```json
{
  "command": "uvx",
  "args": ["ngff-zarr-mcp"]
}
```

</details>

<details>
<summary><b>Install in Roo Code</b></summary>

Add this to your Roo Code MCP configuration file. See [Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo) for more info.

```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Install in Amazon Q Developer CLI</b></summary>

Add this to your Amazon Q Developer CLI configuration file. See [Amazon Q Developer CLI docs](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html) for more details.

```json
{
  "mcpServers": {
    "ngff-zarr": {
      "command": "uvx",
      "args": ["ngff-zarr-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Install in Zencoder</b></summary>

To configure ngff-zarr MCP in Zencoder, follow these steps:

1. Go to the Zencoder menu (...)
2. From the dropdown menu, select Agent tools
3. Click on the Add custom MCP
4. Add the name and server configuration from below, and make sure to hit the Install button

```json
{
  "command": "uvx",
  "args": ["ngff-zarr-mcp"]
}
```

Once the MCP server is added, you can easily continue using it.

</details>

<details>
<summary><b>Install in Warp</b></summary>

See [Warp Model Context Protocol Documentation](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) for details.

1. Navigate `Settings` > `AI` > `Manage MCP servers`.
2. Add a new MCP server by clicking the `+ Add` button.
3. Paste the configuration given below:

```json
{
  "ngff-zarr": {
    "command": "uvx",
    "args": ["ngff-zarr-mcp"]
  }
}
```

4. Click `Save` to apply the changes.

</details>

<details>
<summary><b>Development Installation</b></summary>

For development work, use pixi (recommended) or pip:

#### Using pixi (Recommended)
```bash
# Install pixi if not already installed
curl -fsSL https://pixi.sh/install.sh | bash

# Clone and setup environment
git clone <repository>
cd mcp/
pixi install

# Development environment (includes all dev tools)
pixi shell -e dev

# Run development server
pixi run dev-server

# Run tests and checks
pixi run test
pixi run lint
pixi run typecheck
```

#### Using pip
```bash
# Clone and install in development mode
git clone <repository>
cd mcp/
pip install -e ".[all]"

# Run the server
ngff-zarr-mcp
```

</details>

## Usage

### As MCP Server

The server can be run in different transport modes:

```bash
# STDIO transport (default)
ngff-zarr-mcp

# Server-Sent Events transport
ngff-zarr-mcp --transport sse --host localhost --port 8000
```

### Transport Options

- **STDIO**: Default transport for most MCP clients
- **SSE**: Server-Sent Events for web-based clients or when HTTP transport is preferred

See the installation section above for client-specific configuration examples.

## Examples

### Convert a Single Image

```python
# Through MCP client, the agent can:
result = await convert_images_to_ome_zarr(
    input_paths=["image.tif"],
    output_path="output.ome.zarr",
    ome_zarr_version="0.4",
    scale_factors=[2, 4, 8],
    method="itkwasm_gaussian",
    compression_codec="zstd"
)
```

### Convert with Metadata

```python
result = await convert_images_to_ome_zarr(
    input_paths=["image.nii.gz"],
    output_path="brain.ome.zarr", 
    dims=["z", "y", "x"],
    scale={"z": 2.0, "y": 0.5, "x": 0.5},
    units={"z": "micrometer", "y": "micrometer", "x": "micrometer"},
    name="Brain MRI",
    scale_factors=[2, 4]
)
```

### Optimize Existing Store

```python
result = await optimize_ome_zarr_store(
    input_path="large.ome.zarr",
    output_path="optimized.ome.zarr",
    compression_codec="blosc:zstd",
    chunks=[64, 64, 64]
)
```

### Get Store Information

```python
info = await get_ome_zarr_info("data.ome.zarr")
print(f"Size: {info.size_bytes} bytes")
print(f"Scales: {info.num_scales}")
print(f"Dimensions: {info.dimensions}")
```

## Supported Formats

### Input Formats
- **ITK/ITK-Wasm**: .nii, .nii.gz, .mha, .mhd, .nrrd, .dcm, .jpg, .png, .bmp, etc.
- **TIFF**: .tif, .tiff, .svs, .ndpi, .scn (via tifffile)
- **Video**: .webm, .mp4, .avi, .mov, .gif (via imageio)
- **Zarr**: .zarr, .ome.zarr

### Output Formats
- OME-Zarr (.ome.zarr, .zarr)

## Performance Options

### Memory Management
- Set memory targets to control RAM usage
- Use caching for large datasets
- Configure Dask LocalCluster for distributed processing

### Compression
- Choose from multiple codecs: gzip, lz4, zstd, blosc variants
- Adjust compression levels for speed vs. size tradeoffs
- Use sharding to reduce file count (Zarr v3)

### Chunking
- Optimize chunk sizes for your access patterns
- Configure sharding for better performance with cloud storage

## Development

### Using pixi (Recommended)

Pixi provides reproducible, cross-platform environment management. All Python dependencies are defined in `pyproject.toml` and automatically managed by pixi.

```bash
# Clone and setup environment
git clone <repository>
cd mcp/
pixi install

# Development environment (includes all dev tools)
pixi shell -e dev

# Run tests
pixi run test
pixi run test-cov

# Lint and format code  
pixi run lint
pixi run format
pixi run typecheck

# Run all checks
pixi run all-checks

# Build and serve documentation
pixi run docs
pixi run docs-build

# Start MCP server for testing
pixi run dev-server        # STDIO mode
pixi run dev-server-sse    # SSE mode
```

#### Pixi Environments

- **default**: Runtime dependencies only (from `[project.dependencies]`)
- **dev**: Development tools (pytest, black, mypy, ruff)
- **cloud**: Cloud storage support (s3fs, gcsfs)
- **all**: Complete feature set (all ngff-zarr dependencies + cloud)

```bash
pixi shell -e dev      # Development work
pixi shell -e cloud    # Cloud storage testing
pixi shell -e all      # Full feature testing
```

### Using traditional tools

```bash
# Clone and install in development mode
git clone <repository>
cd mcp/
pip install -e ".[all]"

# Run tests
pytest

# Lint code
black .
ruff check .
```

## Dependencies

### Core
- mcp: Model Context Protocol implementation
- ngff-zarr: Core image conversion functionality
- pydantic: Data validation
- httpx: HTTP client for remote files
- aiofiles: Async file operations

### Optional
- s3fs: S3 storage support
- gcsfs: Google Cloud Storage support
- dask[distributed]: Distributed processing

## 🚨 Troubleshooting

<details>
<summary><b>Python Version Issues</b></summary>

The ngff-zarr-mcp server requires Python 3.9 or higher. If you encounter version errors:

```bash
# Check your Python version
python --version

# Use uvx to automatically handle Python environments
uvx ngff-zarr-mcp
```

</details>

<details>
<summary><b>Package Not Found Errors</b></summary>

If you encounter package not found errors with uvx:

```bash
# Update uvx
pip install --upgrade uvx

# Try installing the package explicitly first
uvx install ngff-zarr-mcp
uvx ngff-zarr-mcp
```

</details>

<details>
<summary><b>Permission Issues</b></summary>

If you encounter permission errors during installation:

```bash
# Use user installation
pip install --user uvx

# Or create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install ngff-zarr-mcp
```

</details>

<details>
<summary><b>Memory Issues with Large Images</b></summary>

For large images, you may need to adjust memory settings:

```bash
# Start server with memory limit
ngff-zarr-mcp --memory-target 8GB

# Or use chunked processing in your conversion calls
# convert_images_to_ome_zarr(chunks=[512, 512, 64])
```

</details>

<details>
<summary><b>Network Issues with Remote Files</b></summary>

If you have issues accessing remote files:

```bash
# Test basic connectivity
curl -I <your-url>

# For S3 URLs, ensure s3fs is installed
pip install s3fs

# Configure AWS credentials if needed
aws configure
```

</details>

<details>
<summary><b>General MCP Client Errors</b></summary>

1. Ensure your MCP client supports the latest MCP protocol version
2. Check that the server starts correctly: `uvx ngff-zarr-mcp --help`
3. Verify JSON configuration syntax in your client config
4. Try restarting your MCP client after configuration changes
5. Check client logs for specific error messages

</details>

## License

MIT License - see LICENSE file for details.
