Metadata-Version: 2.4
Name: albumentationsx-mcp
Version: 1.19.0
Summary: Model Context Protocol server for AlbumentationsX augmentation previews, validation, and segmentation review.
Project-URL: Homepage, https://github.com/dKosarevsky/albu-mcp
Project-URL: Repository, https://github.com/dKosarevsky/albu-mcp
Project-URL: Documentation, https://github.com/dKosarevsky/albu-mcp/blob/main/docs/USAGE.md
Project-URL: Issues, https://github.com/dKosarevsky/albu-mcp/issues
Project-URL: MCP Registry, https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.dKosarevsky/albu-mcp
Project-URL: PyPI, https://pypi.org/project/albumentationsx-mcp/
Author: dKosarevsky
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: albumentationsx,augmentation,computer-vision,mcp,segmentation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: albu-spec>=0.0.6
Requires-Dist: albumentationsx[headless]>=2.3.1
Requires-Dist: mcp[cli]<2,>=1.24.0
Requires-Dist: numpy>=1.24.4
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic>=2.12.4
Requires-Dist: pyyaml>=6.0.0
Description-Content-Type: text/markdown

# AlbumentationsX MCP

Model Context Protocol server for [AlbumentationsX](https://github.com/albumentations-team/AlbumentationsX): inspect datasets, preview augmentations, refine them with visual feedback, and export reproducible pipelines.

<!-- mcp-name: io.github.dKosarevsky/albu-mcp -->

[![CI](https://github.com/dKosarevsky/albu-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dKosarevsky/albu-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/albumentationsx-mcp)](https://pypi.org/project/albumentationsx-mcp/)
[![Python](https://img.shields.io/badge/python-3.10--3.13-blue)](pyproject.toml)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-active-green)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.dKosarevsky/albu-mcp)
[![skills.sh](https://skills.sh/b/dKosarevsky/albu-mcp)](https://skills.sh/dKosarevsky/albu-mcp)

![Baseline and adjusted AlbumentationsX preview contact sheets](https://raw.githubusercontent.com/dKosarevsky/albu-mcp/main/docs/assets/demo/comparison_contact_sheet.png)

Ask an MCP host for several robustness variants, reject an excessive result such as `too_noisy:high`, compare the adjusted batch previews, and export the accepted pipeline.

## Install

### Claude Desktop

[Download the latest `albumentationsx-mcp.mcpb`](https://github.com/dKosarevsky/albu-mcp/releases/latest/download/albumentationsx-mcp.mcpb), install it from **Settings -> Extensions -> Advanced settings**, and select separate image and artifact directories.

### Other MCP Hosts

Run the published server with bounded local access:

```bash
uvx --from albumentationsx-mcp albumentationsx-mcp \
  --allowed-root /absolute/path/to/images \
  --artifact-root /absolute/path/to/albu-artifacts
```

Copyable Claude Code, Cursor, Codex, and JSON configurations are in [the install guide](docs/INSTALL.md). The repository also contains a native Codex plugin bundle. `npx skills add dKosarevsky/albu-mcp` installs agent guidance, not the MCP server.

## First Preview

After connecting the server, ask your host:

```text
Use AlbumentationsX MCP on /absolute/path/to/images.
Run the smoke check, start with a low-intensity pipeline, validate the request,
render one variant per image, and show me the contact sheet before exporting anything.
```

1. When the host exposes resource reads, read `albumentationsx://examples/client-smoke`; otherwise call `run_host_smoke_check` directly.
2. Continue only when `preview_ready` is true, then use the returned `preview_request_template`.
3. Call `validate_preview_request` before rendering and compare preview runs before accepting a candidate.
4. Give concrete feedback such as `too_noisy:high` or `exposure_too_weak:medium`, then export the final pipeline.

If setup fails, read `albumentationsx://diagnostics/guide` and call `diagnose_environment` for bounded remediation actions.

## Capabilities

- Transform discovery, schemas, recipes, and pipeline validation.
- Classification, detection, segmentation, OCR, bbox, mask, keypoint, and dataset-quality workflows.
- Deterministic previews, contact sheets, annotation overlays, comparison, ranking, and reports.
- Interactive MCP Apps review with a text-only fallback for other hosts.
- Structured feedback, tuning sessions, and Python, JSON, or YAML export.
- Stable agent workflow resources, prompts, diagnostics, and reviewed contract snapshots.

The server does not execute arbitrary Python, fetch remote images, overwrite datasets, or train models. Reads are restricted by `--allowed-root`; generated files stay under `--artifact-root`.

## Integrations

- [Official Albumentations MCP guide](https://albumentations.ai/docs/integrations/mcp/)
- [Official MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.dKosarevsky/albu-mcp)
- [skills.sh agent skill](https://skills.sh/dKosarevsky/albu-mcp)
- [Upstream documentation PR](https://github.com/albumentations-team/AlbumentationsX/pull/289)

## Documentation

- [Install and host configuration](docs/INSTALL.md)
- [First 10 minutes](docs/FIRST_10_MINUTES.md)
- [Usage](docs/USAGE.md) and [recipes](docs/RECIPES.md)
- [MCP Apps review](docs/MCP_APPS_REVIEW.md) and [compatibility policy](docs/COMPATIBILITY.md)
- [Documentation index](docs/INDEX.md)
- [CHANGELOG.md](CHANGELOG.md)
- [server.json](server.json): public MCP Registry metadata.

## Development

```bash
uv sync --all-extras --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run ty check
```

Licensed under [AGPL-3.0-or-later](LICENSE).
