Metadata-Version: 2.4
Name: albumentationsx-mcp
Version: 0.6.0
Summary: Model Context Protocol server for AlbumentationsX augmentation discovery, validation, and previews.
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
Keywords: albumentationsx,augmentation,computer-vision,mcp
Classifier: Development Status :: 3 - Alpha
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]>=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):
discovering transforms, validating augmentation pipelines, rendering deterministic previews, and exporting reproducible
pipeline specs.

<!-- 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)

## Scope

This project is intentionally a thin MCP layer around existing AlbumentationsX primitives:

- `albu-spec` is the source of transform metadata, parameter constraints, targets, and docstrings.
- `albumentationsx` remains the execution engine for validation, serialization, and previews.
- the MCP server exposes resources, tools, and prompts with strict typed schemas and bounded local file access.

The server does not execute arbitrary Python, fetch remote images, overwrite datasets, or train models.

## Install

Run the published MCP server without cloning:

```bash
uvx --from albumentationsx-mcp albumentationsx-mcp
```

For local development:

```bash
uv sync --all-extras --dev
```

## Run

```bash
uv run albumentationsx-mcp
```

Claude Desktop or another JSON-configured MCP host can launch a local checkout with stdio:

```json
{
  "mcpServers": {
    "albumentationsx": {
      "command": "uv",
      "args": ["run", "albumentationsx-mcp"],
      "cwd": "/path/to/albu-mcp"
    }
  }
}
```

Installed from PyPI:

```json
{
  "mcpServers": {
    "albumentationsx": {
      "command": "uvx",
      "args": ["--from", "albumentationsx-mcp", "albumentationsx-mcp"]
    }
  }
}
```

See [examples/claude_desktop_pypi_config.json](examples/claude_desktop_pypi_config.json),
[examples/cursor_mcp_config.json](examples/cursor_mcp_config.json), and
[examples/codex_mcp_config.toml](examples/codex_mcp_config.toml) for copyable host snippets.

## Core Tools

- `search_transforms`: search transform metadata by query, targets, type, and bbox support.
- `get_transform_schema`: inspect a transform schema and constraints.
- `validate_pipeline`: validate a typed pipeline spec before running it.
- `recommend_pipeline`: create a conservative task preset for classification, detection, segmentation, or OCR.
- `adjust_pipeline`: apply structured preview feedback such as `too_noisy` or `too_blurry`.
- `explain_pipeline`: summarize likely effects, preview risks, and useful feedback tags.
- `list_feedback_tags`: list the structured feedback contract used by `adjust_pipeline`.
- `list_quality_profiles`: list task-aware quality profiles for balanced, classification, detection, segmentation, and OCR review.
- `render_preview`: create deterministic local preview artifacts inside an allowed output root.
- `render_preview_batch`: create deterministic multi-image preview contact sheets using the same request schema.
- `compare_preview_runs`: compare two preview manifests before choosing feedback tags or exporting a pipeline.
- `summarize_tuning_session`: summarize quality findings, feedback tags, score, risk, and export readiness.
- `rank_preview_candidates`: rank several candidate preview runs against one baseline.
- `record_tuning_decision`: persist a local accepted or rejected tuning decision.
- `list_tuning_decisions`: list local tuning decisions newest-first or score-ranked.
- `export_tuning_report`: export persisted tuning decisions as Markdown or JSON.
- `list_preview_runs`: list recent preview manifests recorded under the artifact root.
- `get_preview_manifest`: read one recorded preview manifest by run id.
- `delete_preview_run`: delete one preview run and its artifacts.
- `cleanup_preview_runs`: prune older preview runs beyond a retention count.
- `export_pipeline`: export a pipeline as Python, JSON, or YAML.

`render_preview` and `render_preview_batch` support optional bboxes, keypoints, and mask paths for annotation overlay
previews. Preview manifests include an agent-legible `summary` block with input counts, seeds, transform names, artifact
counts, contact sheets, and warnings.

## What Changed In 0.2

- PyPI and MCP Registry publishing are automated with release version guardrails and post-release smoke checks.
- `render_preview_batch` produces batch previews and contact sheets for multi-image review.
- `compare_preview_runs` summarizes baseline and candidate manifests to compare preview runs before choosing feedback tags.
- Preview manifests include reproducibility summaries for seeds, transforms, artifact counts, and contact sheets.
- agent workflow resources and prompts guide preview tuning, annotation review, feedback adjustment, and final export.

## What Changed In 0.3

- `adjust_pipeline` accepts optional feedback severity suffixes such as `too_noisy:low`, `too_noisy:medium`, and
  `too_noisy:high`.
- `compare_preview_runs` returns `suggested_feedback_tags` for candidate transforms that deserve visual review.
- Suggested tags are review candidates only; the user still chooses feedback after inspecting contact sheets.

## What Changed In 0.4

- `compare_preview_runs` includes local `quality_summary` metrics for preview image artifacts.
- `summarize_tuning_session` explains baseline-to-candidate feedback, quality deltas, and export readiness.
- task workflow profiles and [docs/RECIPES.md](docs/RECIPES.md) guide classification, detection, segmentation, and OCR
  MCP host sessions.

## What Changed In 0.5

- `quality_summary` now includes saturation, colorfulness, entropy, clipping, and deterministic quality findings.
- Annotation previews record bbox, keypoint, and mask retention observations in preview manifests.
- `compare_preview_runs` includes `annotation_summary` when annotation observations are available.
- `summarize_tuning_session` returns `quality_score`, `quality_risk`, and structured `quality_findings`.
- `record_tuning_decision` and `list_tuning_decisions` provide a local JSON-backed tuning decision journal.

## What Changed In 0.6

- Added task-aware quality profiles for balanced, classification, detection, segmentation, and OCR review.
- Added `rank_preview_candidates` to choose between multiple candidate preview runs.
- Added `export_tuning_report` for Markdown or JSON handoff from the local tuning decision journal.
- Extended golden MCP evals to cover two-candidate ranking and report export.

## Demo Workflow

1. Use `recommend_pipeline` and `validate_pipeline` for a conservative baseline.
2. Call `render_preview_batch` on a small local image set.
3. Adjust with structured feedback such as `too_noisy`, `too_noisy:high`, or `too_distorted`.
4. Render the candidate preview batch with the same inputs.
5. Call `compare_preview_runs` before accepting the candidate and inspect `quality_summary.findings`.
6. If several candidates exist, call `rank_preview_candidates` with the matching quality profile.
7. Call `summarize_tuning_session` and review `quality_score`, `quality_risk`, and `export_ready`.
8. Call `record_tuning_decision` for the accepted or rejected candidate.
9. Call `export_tuning_report` for handoff, then export the accepted pipeline with `export_pipeline`.

See [docs/USAGE.md](docs/USAGE.md) for an end-to-end MCP host workflow, [docs/RECIPES.md](docs/RECIPES.md) for
task-specific host recipes, [docs/DEMO.md](docs/DEMO.md) for a generated preview comparison demo,
[CHANGELOG.md](CHANGELOG.md) for release notes, [docs/RELEASE.md](docs/RELEASE.md) for the package and MCP Registry
release process, [server.json](server.json) for public discovery metadata, and
[evals/golden_mcp_scenarios.yaml](evals/golden_mcp_scenarios.yaml) for executable MCP scenarios.

## Verification

```bash
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run ty check
uv run python scripts/run_golden_evals.py
uv build
```
