{"id":48861755,"url":"https://github.com/crper/py-image-compress-mcp","last_synced_at":"2026-04-15T16:31:04.450Z","repository":{"id":344234147,"uuid":"1023109135","full_name":"crper/py-image-compress-mcp","owner":"crper","description":"High-performance MCP image compression service for AI assistants with intelligent optimization and batch processing capabilities","archived":false,"fork":false,"pushed_at":"2026-03-24T14:52:50.000Z","size":1426,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T16:57:34.877Z","etag":null,"topics":["batch-processing","claude","compression","image-processing","mcp","mcp-server","optimization","pillow"],"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/crper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"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-07-20T14:46:10.000Z","updated_at":"2026-03-24T14:53:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/crper/py-image-compress-mcp","commit_stats":null,"previous_names":["crper/py-image-compress-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/crper/py-image-compress-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crper%2Fpy-image-compress-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crper%2Fpy-image-compress-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crper%2Fpy-image-compress-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crper%2Fpy-image-compress-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crper","download_url":"https://codeload.github.com/crper/py-image-compress-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crper%2Fpy-image-compress-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31849679,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["batch-processing","claude","compression","image-processing","mcp","mcp-server","optimization","pillow"],"created_at":"2026-04-15T16:31:03.722Z","updated_at":"2026-04-15T16:31:04.436Z","avatar_url":"https://github.com/crper.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# py-image-compress-mcp\n\nImage compression and image metadata inspection over the official Python MCP SDK.\n\nThis project exposes a small local MCP server for desktop agents and coding tools. It keeps the MCP surface intentionally small:\n\n- `compress_universal`: compress a file, convert formats, or batch-process a directory\n- `get_image_info`: inspect dimensions, transparency, EXIF, ICC, and lightweight/full analysis\n\nThe server is designed for local `stdio` use and follows the official Python MCP stack via `mcp[cli]`.\n\n## Why this project\n\n- Official Python MCP SDK: `mcp.server.fastmcp.FastMCP`\n- Local-first: optimized for Codex, Claude Desktop, and other MCP desktop clients\n- Small API surface: two tools cover the main workflows\n- Safe output behavior: writes temp files first, then replaces the final output only when valid\n- Stable batch behavior: deterministic file discovery and ordered batch results\n- Conservative same-format behavior: skips likely negative recompression instead of wasting time re-encoding\n- Fast hot path: compression uses lightweight analysis instead of full metadata extraction\n\n## Installation\n\nRequirements:\n\n- Python `3.10+`\n- [`uv`](https://docs.astral.sh/uv/)\n\nInstall:\n\n```bash\ngit clone https://github.com/crper/py-image-compress-mcp.git\ncd py-image-compress-mcp\nuv sync\n```\n\n## Quick Start\n\nRun the local MCP server:\n\n```bash\nuv run py-image-compress-mcp\n```\n\nOr run the module directly:\n\n```bash\nuv run python -m py_image_compress_mcp\n```\n\nInspect with the official MCP dev tool:\n\n```bash\nuv run mcp dev src/py_image_compress_mcp/mcp_server.py\n```\n\nInstall into an MCP desktop client with the official CLI:\n\n```bash\nuv run mcp install src/py_image_compress_mcp/mcp_server.py\n```\n\n## MCP Tools\n\n### `compress_universal`\n\nCompress one file, convert one file into multiple formats, or batch-process a directory.\n\nParameters:\n\n- `input_path`: file or directory path\n- `output_path`: optional output file or output directory\n- `formats`: `None`, a single format string, or a list of formats\n- `quality`: `1-100`; `None` keeps lossless mode\n- `max_width`, `max_height`: optional resize limits\n- `recursive`: recurse into subdirectories in directory mode\n\nTypical examples:\n\n- `compress_universal(\"photo.jpg\")`\n- `compress_universal(\"photo.jpg\", formats=\"WEBP\", quality=82)`\n- `compress_universal(\"photos/\", output_path=\"compressed/\", formats=\"WEBP\", quality=80)`\n- `compress_universal(\"photo.png\", output_path=\"out/\", formats=[\"WEBP\", \"JPEG\", \"PNG\"], quality=80)`\n\nBehavior notes:\n\n- `compress_universal` may short-circuit some same-format lossy requests such as `JPEG -\u003e JPEG` or `WEBP -\u003e WEBP` when the engine predicts a likely negative optimization.\n- In that case the server still returns `success: true`, copies the original bytes to the output path, and marks the file result with `format_used: \"SKIPPED\"`.\n- For MCP callers, the skip reason is exposed in the structured result via `skipped: true` and a human-readable `note` field.\n- The top-level `error` field is reserved for real failures and stays `null` for successful skips.\n\n### `get_image_info`\n\nInspect image metadata and analysis with three response levels. The default level is `summary`.\n\nParameters:\n\n- `input_path`: image path\n- `detail`: `basic`, `summary`, or `full`\n- `include_histogram`: optional override\n- `include_analysis`: optional override\n\nDetail levels:\n\n- `basic`: dimensions, file size, transparency, orientation\n- `summary`: default; `basic` plus EXIF / ICC / complexity\n- `full`: `summary` plus histogram data\n\n## Python Usage\n\nThe Python-facing API is intentionally smaller than before. Create an `ImageCompressor` explicitly.\n\n```python\nfrom py_image_compress_mcp import ImageCompressor\n\ncompressor = ImageCompressor()\n\nresult = compressor.compress_universal(\n    input_path=\"photo.jpg\",\n    output=\"photo.webp\",\n    formats=\"WEBP\",\n    quality=82,\n)\n\nif result[\"success\"]:\n    print(result[\"result\"].get_summary())\n```\n\nFor the Python API, a skipped same-format recompression still returns `success=True`. Inspect `result[\"result\"].skipped` and `result[\"result\"].note` if you need to distinguish a true re-encode from a conservative no-op copy.\n\nDirect single-file APIs are still available when you need more control:\n\n```python\nfrom py_image_compress_mcp import ImageCompressor\n\ncompressor = ImageCompressor(max_workers=4)\nsingle = compressor.compress_image(\"photo.jpg\", output_dir=\"out\", quality=80, format=\"JPEG\")\nmulti = compressor.compress_multi_format(\"photo.jpg\", \"out\", [\"JPEG\", \"WEBP\"], quality=80)\n```\n\n## Codex App / Codex CLI\n\nAdd the server as a local MCP server:\n\n```bash\ncodex mcp add py-image-compress-local -- \\\n  uv run --project /absolute/path/to/py-image-compress-mcp py-image-compress-mcp\n```\n\nCheck the registered config:\n\n```bash\ncodex mcp get py-image-compress-local\n```\n\n## Claude Desktop\n\nExample configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"py-image-compress\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--project\",\n        \"/absolute/path/to/py-image-compress-mcp\",\n        \"py-image-compress-mcp\"\n      ]\n    }\n  }\n}\n```\n\n## More Docs\n\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n- [PYPI_RELEASE.md](PYPI_RELEASE.md)\n\n## Upgrade Notes\n\nRecent API cleanup further narrowed the public surface:\n\n- `from py_image_compress_mcp import compress_universal` was removed\n- `from py_image_compress_mcp import BatchResult`, `CompressionResult`, and `MultiFormatResult` were removed\n- `py_image_compress_mcp.mcp_server.create_server` was removed\n- `build_config()` was removed from `py_image_compress_mcp.engine.config`\n\nUse `ImageCompressor()` directly instead. The package root now guarantees only `ImageCompressor` and `__version__`.\nInternal helper modules and re-exports under `py_image_compress_mcp.*` should be treated as private implementation details.\n\n## Development\n\nCommon commands:\n\n```bash\nmake dev\nmake test\nmake typecheck\nmake benchmark\nmake examples\n```\n\nRun the remaining example script directly when needed:\n\n```bash\nuv run python examples/mcp_usage.py\n```\n\nOptional MCP smoke test:\n\n```bash\n# Use a directory that contains at least 5 images, including 3 PNG files.\nuv run python scripts/mcp_e2e_test.py --source-dir ~/Downloads --output-dir tmp/mcp-e2e\n```\n\nQuick local validation:\n\n```bash\nuv run ruff check .\nuv run mypy src tests\nuv run pytest -q\n```\n\n## Benchmarks\n\nRun:\n\n```bash\nuv run python scripts/benchmark.py\n```\n\nThe benchmark covers:\n\n- metadata extraction on `public/images/3.jpg`\n- single-image compression on `public/images/3.jpg`\n- batch compression on `public/images`\n- one extra real PNG from `~/Downloads` when available\n\n## Project Notes\n\n- Transport: `stdio`\n- SDK: official `mcp[cli]`\n- Server entry: [src/py_image_compress_mcp/mcp_server.py](/Users/linqunhe/code/self-github/projects/py-image-compress-mcp/src/py_image_compress_mcp/mcp_server.py)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrper%2Fpy-image-compress-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrper%2Fpy-image-compress-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrper%2Fpy-image-compress-mcp/lists"}