{"id":30886572,"url":"https://github.com/ramsi-k/albumentations-mcp","last_synced_at":"2025-09-08T13:04:18.506Z","repository":{"id":313041087,"uuid":"1030761430","full_name":"Ramsi-K/albumentations-mcp","owner":"Ramsi-K","description":"An MCP-compatible image augmentation tool powered by Albumentations. Built for Claude, Kiro, and other AI agents.","archived":false,"fork":false,"pushed_at":"2025-09-03T13:33:53.000Z","size":1617,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-03T16:12:48.598Z","etag":null,"topics":["albumentations","computer-vision","image-augmentation","image-processing","mcp","mcp-server","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ramsi-K.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-02T09:11:11.000Z","updated_at":"2025-09-03T14:13:24.000Z","dependencies_parsed_at":"2025-09-03T16:13:12.911Z","dependency_job_id":"94fb317a-69cc-402b-b652-8147cdcb99c6","html_url":"https://github.com/Ramsi-K/albumentations-mcp","commit_stats":null,"previous_names":["ramsi-k/albumentations-mcp"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Ramsi-K/albumentations-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsi-K%2Falbumentations-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsi-K%2Falbumentations-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsi-K%2Falbumentations-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsi-K%2Falbumentations-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ramsi-K","download_url":"https://codeload.github.com/Ramsi-K/albumentations-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsi-K%2Falbumentations-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274188965,"owners_count":25237856,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["albumentations","computer-vision","image-augmentation","image-processing","mcp","mcp-server","python"],"created_at":"2025-09-08T13:03:36.719Z","updated_at":"2025-09-08T13:04:18.490Z","avatar_url":"https://github.com/Ramsi-K.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Albumentations-MCP with Nano Banana (Gemini)\n\n\nNatural language image augmentation via MCP protocol. Transform images using plain English with this MCP-compliant server built on [Albumentations](https://albumentations.ai/).\n\n**Example:** `\"add blur and rotate 15 degrees\"` → Applies GaussianBlur + Rotate transforms automatically\n\n![Albumentations augmentations](./assets/augmentation.jpeg)\n\n![Nano banana augmentations](./assets/nano%20banana.jpeg)\n\n## Quick Start\n\n```bash\n# Install from PyPI\npip install albumentations-mcp\n\n# Run as MCP server\nuvx albumentations-mcp\n```\n\n## MCP Client Setup\n\n### Claude Desktop\n\nCopy [claude-desktop-config.json](docs/claude-desktop-config.json) to `~/.claude_desktop_config.json`\n\nOr add manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"albumentations\": {\n      \"command\": \"uvx\",\n      \"args\": [\"albumentations-mcp\"],\n      \"env\": {\n        \"MCP_LOG_LEVEL\": \"INFO\",\n        \"OUTPUT_DIR\": \"./outputs\",\n        \"ENABLE_VISION_VERIFICATION\": \"true\",\n        \"DEFAULT_SEED\": \"42\"\n      }\n    }\n  }\n}\n```\n\n### Kiro IDE\n\nCopy [kiro-mcp-config.json](docs/kiro-mcp-config.json) to `.kiro/settings/mcp.json`\n\nOr add manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"albumentations\": {\n      \"command\": \"uvx\",\n      \"args\": [\"albumentations-mcp\"],\n      \"env\": {\n        \"MCP_LOG_LEVEL\": \"INFO\",\n        \"OUTPUT_DIR\": \"./outputs\",\n        \"ENABLE_VISION_VERIFICATION\": \"true\",\n        \"DEFAULT_SEED\": \"42\"\n      },\n      \"disabled\": false,\n      \"autoApprove\": [\"augment_image\", \"list_available_transforms\"]\n    }\n  }\n}\n```\n\n## Available Tools\n\n- **`augment_image`** - Apply augmentations using natural language or presets\n- **`list_available_transforms`** - Get supported transforms and parameters\n- **`validate_prompt`** - Test prompts without processing images\n- **`list_available_presets`** - Get available preset configurations\n- **`set_default_seed`** - Set global seed for reproducible results\n- **`get_pipeline_status`** - Check pipeline health and configuration\n- **`get_quick_transform_reference`** - Condensed transform keywords for prompting\n- **`get_getting_started_guide`** - Structured workflow guide for first-time assistants\n\n### VLM (Gemini “Nano Banana”) Tools\n\n- **`check_vlm_config`** – Report readiness without exposing secrets\n- **`vlm_generate_preview`** – Text→image preview for prompt/style ideation (no session)\n- **`vlm_edit_image`** – Image‑conditioned edit; runs full session + verification\n- **`vlm_suggest_recipe`** – Planning‑only: outputs Alb Compose + optional VLMEdit prompt template; can save under `outputs/recipes/`\n\nInstall (with or without VLM)\n\n- Core only (Alb augmentations): `pip install albumentations-mcp`\n- With VLM (Gemini): `pip install 'albumentations-mcp[vlm]'`\n- Local dev (with VLM): `uv pip install -e '.[vlm]'`\n\nClaude/uvx note: include the extra in args when you need VLM\n\n- Latest prerelease with VLM: `\"args\": [\"--refresh\", \"--prerelease=allow\", \"albumentations-mcp[vlm]\"]`\n- Pin stable with VLM: `\"args\": [\"--refresh\", \"albumentations-mcp[vlm]==1.0.2\"]`\n\nVLM quickstart (env or file):\n\n```bash\n# Option 1: env\nset ENABLE_VLM=true\nset VLM_PROVIDER=google\nset VLM_MODEL=gemini-2.5-flash-image-preview\nset GOOGLE_API_KEY=...  # or GEMINI_API_KEY / VLM_API_KEY\n\n# Option 2: file (auto‑discovered)\n# Place a non‑secret file at config/vlm.json:\n{\n  \"enabled\": true,\n  \"provider\": \"google\",\n  \"model\": \"gemini-2.5-flash-image-preview\"\n  // api_key may be in file or environment\n}\n```\n\nExamples:\n\n```python\n# Preview (no input image, no session)\nvlm_generate_preview(prompt=\"Neon night street, cinematic moodboard\")\n\n# Edit (image + prompt, full session)\nvlm_edit_image(\n    image_path=\"examples/basic_images/cat.jpg\",\n    prompt=(\n        \"Using the provided photo of a cat, add a small, knitted wizard hat. \"\n        \"Preserve identity, pose, lighting, and composition.\"\n    ),\n    edit_type=\"edit\",\n)\n\n# Plan and save a hybrid recipe (Alb + VLMEdit)\nplan = vlm_suggest_recipe(\n    task=\"domain_shift\",\n    constraints_json='{\"output_count\":3,\"identity_preserve\":true}',\n    save=True,\n)\nprint(plan[\"paths\"])  # outputs/recipes/\u003ctimestamp\u003e_\u003ctask\u003e_\u003chash\u003e/\n```\n\nMCP env examples for VLM (choose one option)\n\nOption A — file (preferred):\n\n```json\n{\n  \"mcpServers\": {\n    \"albumentations\": {\n      \"command\": \"uvx\",\n      \"args\": [\"albumentations-mcp\"],\n      \"env\": {\n        \"MCP_LOG_LEVEL\": \"INFO\",\n        \"OUTPUT_DIR\": \"./outputs\",\n        \"ENABLE_VLM\": \"true\",\n        \"VLM_CONFIG_PATH\": \"config/vlm.json\"\n      }\n    }\n  }\n}\n```\n\nOption B — inline env (no file):\n\n```json\n{\n  \"mcpServers\": {\n    \"albumentations\": {\n      \"command\": \"uvx\",\n      \"args\": [\"albumentations-mcp\"],\n      \"env\": {\n        \"MCP_LOG_LEVEL\": \"INFO\",\n        \"OUTPUT_DIR\": \"./outputs\",\n        \"ENABLE_VLM\": \"true\",\n        \"VLM_PROVIDER\": \"google\",\n        \"VLM_MODEL\": \"gemini-2.5-flash-image-preview\"\n      }\n    }\n  }\n}\n```\n\n## Available Prompts\n\n- **`compose_preset`** - Generate augmentation policies from presets with optional tweaks\n- **`explain_effects`** - Analyze pipeline effects in plain English\n- **`augmentation_parser`** - Parse natural language to structured transforms\n- **`vision_verification`** - Compare original and augmented images\n- **`error_handler`** - Generate user-friendly error messages and recovery suggestions\n\n## Available Resources\n\n- **`transforms_guide`** - Complete transform documentation with parameters and ranges\n- **`policy_presets`** - Built-in preset configurations (segmentation, portrait, lowlight)\n- **`available_transforms_examples`** - Usage examples and patterns organized by categories\n- **`preset_pipelines_best_practices`** - Best practices guide for augmentation workflows\n- **`troubleshooting_common_issues`** - Common issues, solutions, and diagnostic steps\n- **`getting_started_guide`** - Same content as the tool version, resource-style\n\n## Usage Examples\n\n```python\n# Simple augmentation\naugment_image(\n    image_path=\"photo.jpg\",\n    prompt=\"add blur and rotate 15 degrees\"\n)\n\n# Using presets\naugment_image(\n    image_path=\"dataset/image.jpg\",\n    preset=\"segmentation\"\n)\n\n# Test prompts\nvalidate_prompt(prompt=\"increase brightness and add noise\")\n\n# Process from URL (two-step)\nsession = load_image_for_processing(image_source=\"https://example.com/image.jpg\")\n# Use the returned session_id from the previous call\naugment_image(session_id=\"\u003csession_id\u003e\", prompt=\"add blur and rotate 10 degrees\")\n```\n\n## Features\n\n- **Natural Language Processing** - Convert English descriptions to transforms\n- **Preset Pipelines** - Pre-configured transforms for common use cases\n- **Reproducible Results** - Seeding support for consistent outputs\n- **MCP Protocol Compliant** - Full MCP implementation with tools, prompts, and resources\n- **Comprehensive Documentation** - Built-in guides, examples, and troubleshooting resources\n- **Production Ready** - Comprehensive testing, error handling, and structured logging\n- **Multi-Source Input** - Works with local file paths, base64 payloads, and URLs (via loader)\n\n## Documentation\n\n- [Installation \u0026 Setup](docs/setup.md)\n- [Architecture Overview](docs/architecture.md)\n- [Purpose \u0026 Rationale](docs/purpose.md)\n- [Preset Configurations](docs/presets.md)\n- [Session Folders (outputs/) Guide](docs/session-folders.md)\n- [Regex Security Analysis](docs/regex_security_analysis.md)\n- [Design Philosophy](docs/design_philosophy.md)\n- [Usage Examples](docs/examples.md)\n- [VLM (Nano Banana/Gemini) Guide](docs/vlm_nano_banana.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Contributing](docs/contributing.md)\n\n### Configuration Files\n\n- [Claude Desktop Config](docs/claude-desktop-config.json)\n- [Kiro IDE Config](docs/kiro-mcp-config.json)\n- [All Configuration Examples](docs/mcp-config-examples.json)\n- [VLM Example Config](config/vlm.example.json)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n**Contact:** [ramsi.kalia@gmail.com](mailto:ramsi.kalia@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsi-k%2Falbumentations-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framsi-k%2Falbumentations-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsi-k%2Falbumentations-mcp/lists"}