iccdev-mcp 0.1.0__tar.gz

iccdev_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+*.pyc
+.pytest_cache/

iccdev_mcp-0.1.0/LICENSE.md

@@ -0,0 +1,26 @@
+Copyright (c) International Color Consortium.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of International Color Consortium (ICC) nor the names of
+       its contributors may be used to endorse or promote products derived from
+       this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

iccdev_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,382 @@
+Metadata-Version: 2.5
+Name: iccdev-mcp
+Version: 0.1.0
+Summary: MCP server for ICC color profile tools (iccDEV)
+Project-URL: Homepage, https://github.com/InternationalColorConsortium/iccDEV
+Project-URL: Documentation, https://github.com/InternationalColorConsortium/iccDEV/tree/master/iccdev-mcp
+Project-URL: Issues, https://github.com/InternationalColorConsortium/iccDEV/issues
+Author: International Color Consortium
+License-Expression: BSD-3-Clause
+License-File: LICENSE.md
+Keywords: color,color-management,icc,mcp,profile
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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 :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<3,>=2.1.1
+Provides-Extra: dev
+Requires-Dist: httpx2<3,>=2; extra == 'dev'
+Requires-Dist: httpx<1,>=0.28; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=1.3; extra == 'dev'
+Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
+Provides-Extra: native
+Provides-Extra: rest
+Requires-Dist: starlette<2,>=0.46.0; extra == 'rest'
+Requires-Dist: uvicorn<1,>=0.29.0; extra == 'rest'
+Description-Content-Type: text/markdown
+
+# iccdev-mcp
+
+MCP server for ICC color profile tools from the International Color
+Consortium's RefIccMAX (iccDEV) library.
+
+Exposes tools to AI assistants (Claude, Copilot, Cursor) via the
+Model Context Protocol, covering profile inspection, color transforms,
+and format conversion for ICC v2/v4 and iccMAX v5 profiles.
+
+The static MCP inventory lists supported tools; `health_check` reports the
+tools available in the running environment. Optional native capabilities can differ
+between container variants, so clients and CI must inspect capability flags and
+the discovered CLI inventory rather than assume a fixed health-tool total.
+The response includes the available native, CLI, and service inventories so
+clients can derive its dynamic `total_tools` value without numeric assumptions.
+
+
+## Install
+
+For the lowest-friction setup, use the unified iccDEV Docker image. It includes
+the MCP server, REST dependencies, CLI tools, runtime libraries, maintainer
+utilities, and `Testing/` profiles, so no local iccDEV build is required.
+
+```bash
+docker run --rm -i ghcr.io/internationalcolorconsortium/iccdev:latest \
+  iccdev-mcp-entrypoint mcp
+```
+
+Use `pip install` when integrating with a local source checkout or a locally
+built iccDEV toolchain. `iccdev-mcp` is published on PyPI:
+
+```bash
+python -m pip install "iccdev-mcp[rest]"
+```
+
+The universal wheel from a successful rolling
+<a href="https://github.com/InternationalColorConsortium/iccDEV/releases/latest">Latest Build</a>
+remains available for exact-tag installation:
+
+```bash
+# Replace <release-tag> with the Git tag for the intended release.
+python -m pip install "git+https://github.com/InternationalColorConsortium/iccDEV.git@<release-tag>#subdirectory=iccdev-mcp"
+# Prebuilt GitHub release wheel; copy its exact tag-specific asset URL.
+python -m pip install "<iccdev_mcp-wheel-asset-URL>"
+# Optional REST server dependencies:
+python -m pip install "iccdev-mcp[rest] @ <iccdev_mcp-wheel-asset-URL>"
+```
+
+Release assets include one `iccdev_mcp-*-py3-none-any.whl` and a matching
+source distribution for Python 3.10+. Verify their published checksums and
+provenance before installation. The release workflow tests source imports,
+isolated wheel and sdist installations, console entry points, stdio tool calls,
+and REST health on Windows and Linux. It includes no native binaries or
+compiled transform bindings. See the
+<a href="https://github.com/InternationalColorConsortium/iccDEV/blob/master/docs/python-packaging-release.md">package release guide</a>
+for maintainer validation and the PyPI publication boundary.
+
+For an isolated MCP client, use the public package directly:
+
+```json
+{
+  "mcpServers": {
+    "iccdev": {
+      "command": "uvx",
+      "args": ["iccdev-mcp"]
+    }
+  }
+}
+```
+
+Use `uvx --from "<iccdev_mcp-wheel-asset-URL>" iccdev-mcp` when an exact
+GitHub release asset is required instead of the PyPI package.
+
+The wheel ships only the `iccdev_mcp` namespace, so it can share an environment
+with the separate Cython `iccdev` bindings. Header inspection and signature
+helpers are included. Pixel transforms require installing the native bindings
+from `python/` in the same environment. The `validate_profile` tool dynamically
+loads the public C validation ABI, so it also needs a shared IccProfLib build.
+CLI-backed tools require iccDEV CLI binaries. Build iccDEV locally or
+set `ICCDEV_TOOLS_DIR` and `ICCDEV_BUILD_DIR` to an existing build. The REST
+health endpoint reports the bundled Python API and CLI discovery separately, so
+incomplete local builds are visible at startup.
+
+```bash
+# Point to compiled iccDEV tools
+export ICCDEV_TOOLS_DIR=/path/to/iccDEV/Build/Tools
+export ICCDEV_BUILD_DIR=/path/to/iccDEV/Build
+```
+
+
+## Usage
+
+### Docker
+
+The unified image uses a shell default. Start an MCP transport explicitly:
+
+```bash
+# MCP stdio mode
+docker run --rm -i ghcr.io/internationalcolorconsortium/iccdev:latest \
+  iccdev-mcp-entrypoint mcp
+
+# REST API mode on http://127.0.0.1:8080
+docker run --rm -p 127.0.0.1:8080:8080 \
+  ghcr.io/internationalcolorconsortium/iccdev:latest \
+  iccdev-mcp-entrypoint rest
+```
+
+Open <http://127.0.0.1:8080/> for the bundled REST dashboard. The dashboard
+groups MCP-backed API routes, shows REST-only utility routes such as
+file browsing and upload, and runs tools without requiring a separate client.
+
+Supported container modes are `mcp`/`stdio`, `rest`/`api`, `sse`, and
+`streamable-http`/`http`.
+
+Useful runtime defaults are already configured:
+
+| Variable | Default |
+|----------|---------|
+| `ICCDEV_TOOLS_DIR` | `/workspace/build/Tools` |
+| `ICCDEV_TESTING_DIR` | `/workspace/iccDEV/Testing` |
+| `ICCDEV_VALIDATION_LIBRARY` | `/opt/iccdev-validation/lib/libIccProfLib2.so` |
+
+The unified image keeps sanitizer CLI tools, but loads the validation ABI from
+an isolated non-sanitized shared build. An explicit validation library overrides
+`ICCDEV_BUILD_DIR`, including the image default above. To select a custom build,
+override this library path or unset it before starting the server. Empty,
+missing, and unloadable explicit library paths fail closed without silently
+falling back. Pip-only installations retain optional validation behavior.
+
+Mount additional profiles read-only and list them through
+`ICCDEV_PROFILE_DIRS`:
+
+```bash
+docker run --rm -p 127.0.0.1:8080:8080 \
+  -v "$PWD/profiles:/profiles:ro" \
+  -e ICCDEV_PROFILE_DIRS=/profiles \
+  ghcr.io/internationalcolorconsortium/iccdev:latest \
+  iccdev-mcp-entrypoint rest
+```
+
+Local build and smoke test:
+
+```bash
+docker build -t iccdev:mcp-local -f Dockerfile .
+docker run --rm -p 127.0.0.1:8080:8080 \
+  iccdev:mcp-local iccdev-mcp-entrypoint rest
+curl -fsS http://127.0.0.1:8080/api/health
+curl -fsS http://127.0.0.1:8080/api/tools
+python3 .github/scripts/iccdev-container-smoke.py iccdev:mcp-local
+# Optional REST dashboard in a browser
+xdg-open http://127.0.0.1:8080/  # or open the URL manually
+```
+
+### Claude Desktop
+
+For a container-only local client, use this unified image configuration. Keep
+`-i` (open stdin), omit `-t`, and do not close stdin until requested tool
+responses arrive:
+
+```json
+{
+  "mcpServers": {
+    "iccdev": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i",
+               "ghcr.io/internationalcolorconsortium/iccdev:latest",
+               "iccdev-mcp-entrypoint", "mcp"]
+    }
+  }
+}
+```
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "iccdev": {
+      "command": "iccdev-mcp",
+      "env": {
+        "ICCDEV_TOOLS_DIR": "/path/to/iccDEV/Build/Tools"
+      }
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "iccdev": {
+      "command": "iccdev-mcp"
+    }
+  }
+}
+```
+
+### GitHub Copilot coding agent
+
+Add this repository MCP configuration under
+`Settings` -> `Copilot` -> `MCP servers`. GitHub requires explicit `type`,
+`args`, and `tools` fields for repository MCP settings.
+
+```json
+{
+  "mcpServers": {
+    "iccdev": {
+      "type": "local",
+      "command": "iccdev-mcp",
+      "args": [],
+      "env": {
+        "ICCDEV_TOOLS_DIR": "Build/Tools"
+      },
+      "tools": [
+        "inspect_header",
+        "profile_summary",
+        "validate_profile",
+        "color_transform",
+        "roundtrip_delta",
+        "icc_sig_to_str",
+        "enum_spaces",
+        "list_available_profiles",
+        "health_check",
+        "dump_profile",
+        "profile_to_xml",
+        "xml_to_profile",
+        "profile_to_json",
+        "json_to_profile",
+        "tiff_dump",
+        "jpeg_dump",
+        "png_dump",
+        "heif_dump",
+        "from_cube",
+        "apply_profiles",
+        "apply_named_cmm",
+        "create_link",
+        "v5_to_v4",
+        "spec_sep_to_tiff",
+        "apply_search",
+        "round_trip_test",
+        "pawg_report"
+      ]
+    }
+  }
+}
+```
+
+### Remote (SSE transport)
+
+```bash
+iccdev-mcp --transport sse --port 8080
+```
+
+
+## Tools
+
+### Python-Native
+
+| Tool | Description |
+|------|-------------|
+| `inspect_header` | ICC profile header (22 fields + 6 computed names) |
+| `profile_summary` | Compact profile classification and routing metadata |
+| `validate_profile` | In-memory validation status and report from the native C API; requires a shared IccProfLib build |
+| `color_transform` | Multi-profile CMM transform; requires the native `iccdev` bindings |
+| `roundtrip_delta` | Device-channel round-trip Euclidean distance, not CIE Delta E; requires native bindings |
+| `icc_sig_to_str` | 4-byte ICC signature to string |
+| `enum_spaces` | List all 32 ICC color space identifiers |
+
+### CLI-Backed -- require iccDEV tools
+
+| Tool | CLI Binary | Description |
+|------|-----------|-------------|
+| `dump_profile` | iccDumpProfile | Full profile text dump |
+| `pawg_report` | iccPawgReport | PAWG security, conformance, and quality checklist |
+| `profile_to_xml` | iccToXml | ICC to XML conversion |
+| `xml_to_profile` | iccFromXml | XML to ICC conversion |
+| `profile_to_json` | iccToJson | ICC to JSON conversion |
+| `json_to_profile` | iccFromJson | JSON to ICC conversion |
+| `round_trip_test` | iccRoundTrip | Round-trip transform fidelity |
+| `tiff_dump` | iccTiffDump | TIFF metadata + embedded ICC |
+| `jpeg_dump` | iccJpegDump | JPEG metadata + embedded ICC |
+| `png_dump` | iccPngDump | PNG metadata + embedded ICC |
+| `heif_dump` | iccHeifDump | HEIF, HEIC, and AVIF metadata + embedded ICC |
+| `from_cube` | iccFromCube | .cube LUT to ICC profile |
+| `apply_profiles` | iccApplyProfiles | Multi-profile TIFF transform |
+| `apply_named_cmm` | iccApplyNamedCmm | Named color CMM |
+| `create_link` | iccApplyToLink | Device link creation |
+| `v5_to_v4` | iccV5DspObsToV4Dsp | v5 display to v4 conversion |
+| `spec_sep_to_tiff` | iccSpecSepToTiff | Spectral separation |
+| `apply_search` | iccApplySearch | Search-based transform |
+
+### CLI-Only Tools (Not MCP-Exposed)
+
+The following built iccDEV executables do not have MCP wrappers and must not
+be added to an MCP server `tools` allowlist: `iccBenchApply`, `iccProfilePlot`,
+`iccProfileVisualize`, and `iccProfileVisualizePlot`. Use them directly from
+the command line; see the repository
+[CLI tool reference](../docs/tools-cli-reference.md) for their interfaces.
+
+### Utility (2)
+
+| Tool | Description |
+|------|-------------|
+| `health_check` | Server status and tool availability |
+| `list_available_profiles` | Browse ICC test profiles |
+
+The REST dashboard at `/` and `/ui` provides Testing/ directory and filename
+selectors for ICC, XML, JSON, TIFF, JPEG, PNG, HEIF, HEIC, AVIF, and cube inputs. `/api/tools`
+returns the stable MCP inventory and separately lists REST-only utility
+routes (`/api/tools`, `/api/files`, and `/api/upload`). Core CLI-backed forms
+expose documented options for `iccDumpProfile` validation/verbosity/tag
+selection, `iccPawgReport` profile assessment, `iccRoundTrip` intent/MPE
+selection, and `iccApplyProfiles` structured or raw `-cfg` argument mode.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ICCDEV_TOOLS_DIR` | Path to iccDEV CLI tool binaries |
+| `ICCDEV_BUILD_DIR` | CMake build root containing the shared IccProfLib validation ABI |
+| `ICCDEV_VALIDATION_LIBRARY` | Explicit shared IccProfLib path; overrides `ICCDEV_BUILD_DIR` |
+| `ICCDEV_TESTING_DIR` | Path to iccDEV Testing/ profiles directory |
+| `ICCDEV_PROFILE_DIRS` | Additional profile search directories (colon-separated) |
+
+
+## Development
+
+```bash
+# Install for development
+cd iccdev-mcp
+pip install -e ".[dev,rest]"
+
+# Run tests
+pytest tests/ -v
+
+# Run server (stdio)
+python -m iccdev_mcp.server
+```
+
+
+## License
+
+BSD 3-Clause. See [LICENSE.md](LICENSE.md).