morphiaone-mcp 0.1.0__tar.gz

morphiaone_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MorphiaOne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

morphiaone_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: morphiaone-mcp
+Version: 0.1.0
+Summary: MCP server for MorphiaOne shade digitisation, a thin client of the public V1 API.
+Author: MorphiaOne
+License-Expression: MIT
+Project-URL: Documentation, https://docs.morphiaone.ai/guides/ai-agents
+Project-URL: Repository, https://github.com/MorphiaOne/vision-api
+Keywords: morphiaone,mcp,model-context-protocol,ai-agents,digitisation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: morphiaone<0.12,>=0.11
+Requires-Dist: mcp<2.4,>=2.3.0
+Dynamic: license-file
+
+# morphiaone-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude, Cursor or any MCP
+client digitise product shade colours through the MorphiaOne V1 API: retain a photo,
+measure regions, propose a candidate, review it and stage it as an unpublished
+catalogue draft. It is a thin client of the public API, so your key's scopes, rate
+limits, credits and test mode apply as they do anywhere else.
+
+## Install
+
+```sh
+pip install morphiaone        # the CLI that writes the client configuration
+morphiaone mcp install --client claude-code     # or cursor, claude-desktop
+```
+
+`morphiaone mcp install` adds one `morphiaone` server to the client's configuration
+and leaves the others as they are. It runs `morphiaone-mcp` if it is on your `PATH`
+(`pipx install morphiaone-mcp`), otherwise `uvx morphiaone-mcp`. `--print` shows the
+entry without writing it.
+
+The server reads the key from `MORPHIAONE_API_KEY`. Claude Code and Cursor expand that
+reference when they start the server, so no key is written to their files. Claude
+Desktop expands nothing, so its file would hold the key: the command writes it only
+with `--store-key`. Use a test-mode key, or one with only `digitisation.read` and
+`digitisation.write`, and revoke it when you stop.
+
+`MORPHIAONE_BASE_URL` defaults to `https://api.morphiaone.ai`.
+
+## What the agent can do
+
+The tools it sees are the ones your key holds every scope for. Give an agent
+`digitisation.read` and `digitisation.write` and it proposes; a person reviews and
+stages in the Platform. Staging is not publishing: a draft renders nothing until
+someone publishes it.
+
+Guide, tools and scopes: https://docs.morphiaone.ai/guides/ai-agents
+
+`morphiaone-mcp --version` prints the installed version; include it when you report a
+problem, with the `request_id` of any refused call.

morphiaone_mcp-0.1.0/README.md

@@ -0,0 +1,39 @@
+# morphiaone-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude, Cursor or any MCP
+client digitise product shade colours through the MorphiaOne V1 API: retain a photo,
+measure regions, propose a candidate, review it and stage it as an unpublished
+catalogue draft. It is a thin client of the public API, so your key's scopes, rate
+limits, credits and test mode apply as they do anywhere else.
+
+## Install
+
+```sh
+pip install morphiaone        # the CLI that writes the client configuration
+morphiaone mcp install --client claude-code     # or cursor, claude-desktop
+```
+
+`morphiaone mcp install` adds one `morphiaone` server to the client's configuration
+and leaves the others as they are. It runs `morphiaone-mcp` if it is on your `PATH`
+(`pipx install morphiaone-mcp`), otherwise `uvx morphiaone-mcp`. `--print` shows the
+entry without writing it.
+
+The server reads the key from `MORPHIAONE_API_KEY`. Claude Code and Cursor expand that
+reference when they start the server, so no key is written to their files. Claude
+Desktop expands nothing, so its file would hold the key: the command writes it only
+with `--store-key`. Use a test-mode key, or one with only `digitisation.read` and
+`digitisation.write`, and revoke it when you stop.
+
+`MORPHIAONE_BASE_URL` defaults to `https://api.morphiaone.ai`.
+
+## What the agent can do
+
+The tools it sees are the ones your key holds every scope for. Give an agent
+`digitisation.read` and `digitisation.write` and it proposes; a person reviews and
+stages in the Platform. Staging is not publishing: a draft renders nothing until
+someone publishes it.
+
+Guide, tools and scopes: https://docs.morphiaone.ai/guides/ai-agents
+
+`morphiaone-mcp --version` prints the installed version; include it when you report a
+problem, with the `request_id` of any refused call.

morphiaone_mcp-0.1.0/morphiaone_mcp/__init__.py

@@ -0,0 +1 @@
+"""MorphiaOne MCP server."""

morphiaone_mcp-0.1.0/morphiaone_mcp/server.py

@@ -0,0 +1,703 @@
+"""The MorphiaOne MCP server: shade digitisation tools over the public V1 API.
+
+A thin client of /v1 through the Python SDK, so rate limits, quotas, credits, test
+mode, audit and scopes apply exactly as to any API caller. It keeps no state and no
+secret: every request carries the caller's own credential as ``Authorization: Bearer``,
+an API key or a Platform member's OAuth access token, which it forwards to the gateway
+unread; the gateway is the authority on both.
+
+    MORPHIAONE_BASE_URL=https://api.morphiaone.ai \\
+    MORPHIAONE_MCP_ALLOWED_HOSTS=mcp.example.com \\
+        uvicorn morphiaone_mcp.server:app --host 0.0.0.0 --port 8091 --no-access-log
+
+To let OAuth clients (a claude.ai connector) sign members in, also name the public MCP
+URL and the AuthKit issuer: ``MORPHIAONE_MCP_RESOURCE_URL=https://mcp.example.com/mcp``
+and ``MORPHIAONE_MCP_AUTHORIZATION_SERVERS=https://auth.example.com``. The server then
+serves ``/.well-known/oauth-protected-resource`` and names it in each ``401``.
+
+Run on the user's own machine instead, ``morphiaone-mcp`` serves the same tools over
+stdio with the key from ``MORPHIAONE_API_KEY``; only then may ``retain_evidence`` read a
+local photo by ``path``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import json
+import logging
+import os
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from importlib import metadata
+from pathlib import Path
+from typing import Any, Literal, TypeVar
+from urllib.parse import urlsplit
+
+from mcp.server.mcpserver import Context, MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.server.transport_security import TransportSecuritySettings
+from mcp.shared.exceptions import MCPError
+from mcp_types import INTERNAL_ERROR, ListToolsResult, ToolAnnotations
+from morphiaone import AsyncMorphiaOne, MorphiaOneError, views
+from morphiaone.errors import DeadlineExceeded
+from morphiaone.v1 import _sniff
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+BASE_URL_ENV = "MORPHIAONE_BASE_URL"
+API_KEY_ENV = "MORPHIAONE_API_KEY"
+#: True only under ``morphiaone-mcp`` (stdio, on the user's machine): the key comes
+#: from the environment and a tool may read a local photo. The HTTP app never sets it,
+#: so a hosted process never acts with its own environment's key.
+LOCAL = False
+#: Local photos the server will upload, by extension; the bytes must match it too.
+PHOTO_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+}
+#: The SDK's default upload cap; one byte more is read so it can refuse a larger file.
+MAX_PHOTO_BYTES = 10 * 1024 * 1024
+DEFAULT_BASE_URL = "https://api.morphiaone.ai"
+#: Comma-separated Host and Origin allowlists (``name:*`` matches any port). The
+#: defaults admit only a local run; a deployment names its public host.
+ALLOWED_HOSTS_ENV = "MORPHIAONE_MCP_ALLOWED_HOSTS"
+ALLOWED_ORIGINS_ENV = "MORPHIAONE_MCP_ALLOWED_ORIGINS"
+DEFAULT_ALLOWED_HOSTS = "localhost:*,127.0.0.1:*"
+DEFAULT_ALLOWED_ORIGINS = "http://localhost:*,http://127.0.0.1:*"
+#: OAuth protected-resource metadata (RFC 9728), served only when both are set: this
+#: server's public MCP URL, and the authorization servers (AuthKit) that issue its
+#: tokens, comma-separated.
+RESOURCE_URL_ENV = "MORPHIAONE_MCP_RESOURCE_URL"
+AUTHORIZATION_SERVERS_ENV = "MORPHIAONE_MCP_AUTHORIZATION_SERVERS"
+METADATA_PATH = "/.well-known/oauth-protected-resource"
+#: Seconds measure_regions waits before answering the assessment as it stands.
+MEASURE_WAIT_S = 60.0
+#: Seconds between the progress notifications measure_regions sends while it waits.
+PROGRESS_EVERY_S = 5.0
+
+try:
+    VERSION = metadata.version("morphiaone-mcp")
+except metadata.PackageNotFoundError:  # a source tree imported without installing
+    VERSION = "0+unknown"
+#: Tool ``_meta`` key naming every API scope a tool's calls need.
+SCOPE_META = "ai.morphiaone/scopes"
+log = logging.getLogger("morphiaone.mcp")
+
+REVIEW_RULE = (
+    "A person reviews before anything is accepted, rejected or staged: show the user "
+    "the colour (srgb_hex, lab_d65, clipped_fraction, region) and act only on their "
+    "explicit yes. A clipped_fraction above 0 means the colour may be off; say so. "
+    "On HUMAN_REVIEW_REQUIRED this account lets only a person decide: give the user "
+    "the candidate's review_url from get_candidate, wait for them, and never say it "
+    "was approved until get_candidate shows it."
+)
+
+READ = ToolAnnotations(read_only_hint=True, destructive_hint=False)
+# Retried writes replay the first answer (derived Idempotency-Key), and they add a
+# pending item without changing anything a user already has.
+WRITE = ToolAnnotations(
+    read_only_hint=False, destructive_hint=False, idempotent_hint=True
+)
+# Decisions and catalogue writes: a client should ask the user before each one.
+DECIDE = ToolAnnotations(
+    read_only_hint=False, destructive_hint=True, idempotent_hint=True
+)
+
+
+class Server(MCPServer):
+    """Lists only the tools the caller's key can use; logs one line per tool call."""
+
+    # The private hook is the one that sees the request's headers; list_tools() does not.
+    async def _handle_list_tools(self, ctx, params) -> ListToolsResult:
+        tools = await self.list_tools()
+        try:
+            scopes = await key_scopes(Context(request_context=ctx, mcp_server=self))
+        except ToolError as exc:
+            # Discovery has no tool-result error channel. Preserve the safe API
+            # code and request id in a protocol error so clients can act on it.
+            raise MCPError(code=INTERNAL_ERROR, message=str(exc)) from None
+        tools = [t for t in tools if set(t.meta[SCOPE_META]).issubset(scopes)]
+        return ListToolsResult(tools=tools)
+
+    async def call_tool(self, name, arguments, context=None):
+        started, outcome, request_id = time.perf_counter(), "ok", None
+        try:
+            # Discovery is advisory: clients can call a hidden tool directly.
+            tools = await self.list_tools()
+            selected = next((t for t in tools if t.name == name), None)
+            if selected is not None:
+                ctx = context if context is not None else Context(mcp_server=self)
+                scopes = await key_scopes(ctx)
+                missing = sorted(set(selected.meta[SCOPE_META]) - scopes)
+                if missing:
+                    error = ToolError(
+                        json.dumps(
+                            {
+                                "code": "INSUFFICIENT_SCOPE",
+                                "message": "The key lacks required tool scopes.",
+                                "missing_scopes": missing,
+                            }
+                        )
+                    )
+                    error.code = "INSUFFICIENT_SCOPE"
+                    raise error
+            return await super().call_tool(name, arguments, context)
+        except Exception as exc:
+            cause = exc.__cause__ or exc
+            outcome = getattr(cause, "code", None) or type(cause).__name__
+            request_id = getattr(cause, "request_id", None)
+            if (
+                cause is not exc
+                and isinstance(cause, ToolError)
+                and hasattr(cause, "code")
+            ):
+                # Ours is already the JSON refusal; drop the library's "Error executing
+                # tool <name>: " prefix so every refusal reaches the agent as bare JSON.
+                raise cause from None
+            raise
+        finally:
+            # Never the key or the arguments: they are the caller's.
+            log.info(
+                json.dumps(
+                    {
+                        "message": "tool call",
+                        "tool": name,
+                        "outcome": outcome,
+                        "request_id": request_id,
+                        "duration_ms": round((time.perf_counter() - started) * 1000, 2),
+                    }
+                )
+            )
+
+
+async def key_scopes(ctx: Context) -> frozenset[str]:
+    """Read the key's current scopes; unreadable credentials never grant tools.
+
+    No cache: revocation and scope changes take effect on the next list or call.
+    """
+    try:
+        async with client_for(ctx) as client:
+            return frozenset((await client.whoami())["scopes"])
+    except MorphiaOneError as exc:
+        log.info(json.dumps({"message": "scopes unread", "outcome": exc.code}))
+        raise tool_error(exc) from None
+
+
+server = Server(
+    "morphiaone",
+    title="MorphiaOne",
+    version=VERSION,
+    instructions=(
+        "Digitise product shade colours: retain a photo by URL, measure regions, "
+        "freeze one as a candidate, review it, then stage it into the catalogue as an "
+        "unpublished draft. " + REVIEW_RULE
+    ),
+)
+
+T = TypeVar("T")
+
+
+def tool(annotations: ToolAnnotations, *scopes: str):
+    """Register a tool and every API scope its calls need."""
+    return server.tool(annotations=annotations, meta={SCOPE_META: list(scopes)})
+
+
+def reviewed(annotations: ToolAnnotations, *scopes: str):
+    """Register a tool whose description carries the review rule: it changes what a
+    user reviews or publishes."""
+
+    def register(fn):
+        fn.__doc__ = f"{fn.__doc__}\n\n{REVIEW_RULE}"
+        return tool(annotations, *scopes)(fn)
+
+    return register
+
+
+def bearer(headers: Mapping[str, str] | None) -> str | None:
+    scheme, _, token = (headers or {}).get("authorization", "").partition(" ")
+    token = token.strip()
+    return token if scheme.lower() == "bearer" and token else None
+
+
+def is_access_token(credential: str) -> bool:
+    """A JWT (an OAuth access token) rather than an API key, by its shape alone: the
+    server never verifies it, the gateway does."""
+    return credential.startswith("eyJ") and credential.count(".") == 2
+
+
+def client_for(ctx: Context) -> AsyncMorphiaOne:
+    key = os.environ.get(API_KEY_ENV) if LOCAL else bearer(ctx.headers)
+    if not key:
+        raise ToolError(
+            f"set {API_KEY_ENV} in the environment that starts morphiaone-mcp"
+            if LOCAL
+            else "send your MorphiaOne API key or access token as Authorization: Bearer"
+        )
+    token = not LOCAL and is_access_token(key)
+    return AsyncMorphiaOne(
+        api_key=None if token else key,
+        access_token=key if token else None,
+        base_url=os.environ.get(BASE_URL_ENV, DEFAULT_BASE_URL),
+        app_info=f"morphiaone-mcp/{VERSION}",
+    )
+
+
+def idempotency_key(tool: str, **args: Any) -> str:
+    """One key per tool and argument set, so an agent's retry replays the first answer."""
+    canonical = json.dumps([tool, args], sort_keys=True, separators=(",", ":"))
+    return "mcp-" + hashlib.sha256(canonical.encode()).hexdigest()
+
+
+def tool_error(exc: Exception) -> ToolError:
+    if isinstance(exc, MorphiaOneError):
+        body = {"code": exc.code, "message": exc.message, "request_id": exc.request_id}
+        if exc.details:
+            body["details"] = exc.details
+    else:
+        body = {"code": "INVALID_ARGUMENT", "message": str(exc)}
+    error = ToolError(json.dumps(body))
+    error.code, error.request_id = (
+        body["code"],
+        body.get("request_id"),
+    )  # for the log line
+    return error
+
+
+async def call(ctx: Context, action: Callable[[AsyncMorphiaOne], Awaitable[T]]) -> T:
+    # shortcut: one HTTP client per tool call; pool per key if call volume makes it matter.
+    try:
+        async with client_for(ctx) as client:
+            return await action(client)
+    except (MorphiaOneError, TypeError, ValueError) as exc:
+        raise tool_error(exc) from None
+
+
+def shown(raw: Mapping[str, Any], view: Callable[[Any], dict], full: bool) -> dict:
+    return dict(raw) if full else view(raw)
+
+
+@tool(READ, "digitisation.read")
+async def list_review_queue(
+    ctx: Context, limit: int = 20, cursor: str | None = None, raw: bool = False
+) -> dict[str, Any]:
+    """The pending candidates waiting for review, newest first. Pass `next_cursor`
+    back as `cursor` to read on."""
+    page = await call(
+        ctx,
+        lambda c: c.digitisation.list_candidates(
+            review_status="pending", limit=limit, cursor=cursor
+        ),
+    )
+    return shown(page.raw, views.candidate_page, raw)
+
+
+@tool(READ, "digitisation.read")
+async def get_assessment(
+    ctx: Context, assessment_id: str, raw: bool = False
+) -> dict[str, Any]:
+    """One assessment: its status and, once succeeded, each measured region."""
+    found = await call(ctx, lambda c: c.digitisation.get_assessment(assessment_id))
+    return shown(found.raw, views.assessment, raw)
+
+
+@tool(READ, "digitisation.read")
+async def get_candidate(
+    ctx: Context, candidate_id: str, raw: bool = False
+) -> dict[str, Any]:
+    """One candidate with its measured colour and the `candidate_sha256` a review sends."""
+    found = await call(ctx, lambda c: c.digitisation.get_candidate(candidate_id))
+    return shown(found.raw, views.candidate, raw)
+
+
+@tool(READ, "catalogue.read")
+async def find_variant(
+    ctx: Context, external_ref: str, raw: bool = False
+) -> dict[str, Any]:
+    """The catalogue variants carrying this SKU (`external_ref`). Read this before
+    staging: a taken reference cannot be created again, only revised."""
+    page = await call(
+        ctx, lambda c: c.catalogue.list_variants(external_ref=external_ref)
+    )
+    if raw:
+        return dict(page.raw)
+    return {"data": [views.variant(v) for v in page.raw["data"]]}
+
+
+def local_photo(path: str) -> tuple[bytes, str]:
+    """A local swatch photo's bytes and media type, refusing anything else before it
+    leaves the machine: the agent picks the path, so an injected one must not upload a
+    private file."""
+    if not LOCAL:
+        raise ValueError(
+            "a hosted server can't read your files: call start_upload and send "
+            "the user its upload_url, or upload the photo with the MorphiaOne SDK "
+            "or CLI and pass its asset_id"
+        )
+    file = Path(path).expanduser().resolve()
+    media_type = PHOTO_TYPES.get(file.suffix.lower())
+    if media_type is None:
+        raise ValueError("path must name a .jpg, .jpeg, .png or .webp photo")
+    if not file.is_file():
+        raise ValueError("path names no file")
+    try:
+        with file.open("rb") as stream:
+            content = stream.read(MAX_PHOTO_BYTES + 1)
+    except OSError:
+        raise ValueError("path can't be read") from None
+    if len(content) > MAX_PHOTO_BYTES:
+        raise ValueError(f"photo is larger than {MAX_PHOTO_BYTES} bytes")
+    if _sniff(content) != media_type:
+        raise ValueError("file content is not the image its extension names")
+    return content, media_type
+
+
+@tool(WRITE, "digitisation.write")
+async def retain_evidence(
+    ctx: Context,
+    path: str | None = None,
+    asset_id: str | None = None,
+    url: str | None = None,
+    raw: bool = False,
+) -> dict[str, Any]:
+    """Keep a photo of the product swatch as evidence. Pass exactly one of: `path`, a
+    local .jpg, .png or .webp file (only when this server runs on the user's machine);
+    `asset_id`, an image uploaded with the MorphiaOne SDK or CLI; or `url`, a public
+    HTTPS image. The same image already retained is answered as it is. A deployment
+    that fetches no links refuses `url` with `remote_input_disabled`: use `path`, or
+    `start_upload` for a link the user sends the photo to."""
+    if sum(one is not None for one in (path, asset_id, url)) != 1:
+        raise tool_error(ValueError("pass exactly one of path, asset_id or url"))
+
+    async def keep(c: AsyncMorphiaOne):
+        if path is not None:
+            content, media_type = local_photo(path)
+            asset = await c.assets.upload(content, media_type=media_type)
+            return await c.digitisation.retain_evidence(asset.id)
+        if asset_id is not None:
+            return await c.digitisation.retain_evidence(asset_id)
+        return await c.digitisation.retain_evidence(url=url)
+
+    kept = await call(ctx, keep)
+    return shown(kept.raw, views.evidence, raw)
+
+
+UPLOAD_HINT = (
+    "Send the user this upload_url: they open it to choose the photo (or run "
+    "`curl -T photo.jpg <upload_url>`). It works once and expires at expires_at. "
+    "Then call get_upload until status is stored and pass its asset_id to "
+    "retain_evidence."
+)
+
+
+@tool(WRITE, "digitisation.write")
+async def start_upload(ctx: Context) -> dict[str, Any]:
+    """A single-use link the user sends one photo through, for when you don't hold the
+    photo (a hosted server can't read the user's files). The link is in this answer
+    only: call again for a new one, not to re-read it."""
+    # No derived Idempotency-Key: a replay answers no link, so each call is a new session.
+    started = await call(ctx, lambda c: c.uploads.start())
+    return {**started.raw, "hint": UPLOAD_HINT}
+
+
+@tool(READ, "digitisation.read")
+async def get_upload(ctx: Context, upload_id: str) -> dict[str, Any]:
+    """An upload session: `pending` until the user sends the photo, then `stored` with
+    the `asset_id` to pass to retain_evidence, or `expired`."""
+    found = await call(ctx, lambda c: c.uploads.get(upload_id))
+    return dict(found.raw)
+
+
+@tool(WRITE, "digitisation.write", "digitisation.read")
+async def measure_regions(
+    ctx: Context,
+    evidence_id: str,
+    regions: list[list[int]],
+    wait: bool = True,
+    raw: bool = False,
+    attempt: int = 0,
+) -> dict[str, Any]:
+    """Measure the mean colour of each region of one evidence image. A region is
+    [LEFT, TOP, RIGHT, BOTTOM] in pixels, half-open. With `wait`, answers once the
+    assessment settles (up to a minute), sending progress while it waits; otherwise
+    read it later with get_assessment.
+    The same arguments answer the same assessment, failed or not; to measure again on
+    purpose after a failure, pass the next `attempt` (1, 2, ...)."""
+    if attempt < 0:
+        raise tool_error(ValueError("attempt must be 0 or more"))
+    # attempt 0 keeps the key a plain retry derives, so only a deliberate rerun differs.
+    extra = {"attempt": attempt} if attempt else {}
+    key = idempotency_key(
+        "measure_regions", evidence_id=evidence_id, regions=regions, **extra
+    )
+    images = [{"evidence_id": evidence_id, "regions": regions}]
+
+    async def measure(c: AsyncMorphiaOne):
+        made = await c.digitisation.create_assessment(images, idempotency_key=key)
+        if not wait:
+            return made
+        waiting = asyncio.create_task(
+            c.digitisation.wait_assessment(made, timeout=MEASURE_WAIT_S)
+        )
+        started = time.monotonic()
+        try:
+            while not (await asyncio.wait({waiting}, timeout=PROGRESS_EVERY_S))[0]:
+                # A heartbeat (a no-op unless the client sent a progress token): the
+                # SDK's wait does the polling, so this adds no request to the API.
+                await ctx.report_progress(
+                    time.monotonic() - started,
+                    MEASURE_WAIT_S,
+                    f"waiting for assessment {made.id}",
+                )
+            return waiting.result()
+        except DeadlineExceeded:
+            return await c.digitisation.get_assessment(made.id)
+        finally:
+            waiting.cancel()
+
+    return shown((await call(ctx, measure)).raw, views.assessment, raw)
+
+
+@tool(WRITE, "digitisation.write")
+async def make_candidate(
+    ctx: Context, assessment_id: str, image: int, region: int, raw: bool = False
+) -> dict[str, Any]:
+    """Freeze one measured region of a succeeded assessment as a pending candidate.
+    `image` and `region` are positions in the assessment's output, from 0."""
+    key = idempotency_key(
+        "make_candidate", assessment_id=assessment_id, image=image, region=region
+    )
+    made = await call(
+        ctx,
+        lambda c: c.digitisation.create_candidate(
+            assessment_id, image=image, region=region, idempotency_key=key
+        ),
+    )
+    return shown(made.raw, views.candidate, raw)
+
+
+@reviewed(WRITE, "digitisation.write")
+async def edit_candidate(
+    ctx: Context,
+    candidate_id: str,
+    candidate_sha256: str,
+    display_color: str | None = None,
+    finish: str | None = None,
+    raw: bool = False,
+) -> dict[str, Any]:
+    """Correct a candidate's colour (`#RRGGBB`) or finish. This derives a NEW pending
+    candidate with a new digest; review that one."""
+    key = idempotency_key(
+        "edit_candidate",
+        candidate_id=candidate_id,
+        candidate_sha256=candidate_sha256,
+        display_color=display_color,
+        finish=finish,
+    )
+    edited = await call(
+        ctx,
+        lambda c: c.digitisation.edit_candidate(
+            candidate_id,
+            candidate_sha256=candidate_sha256,
+            display_color=display_color,
+            finish=finish,
+            idempotency_key=key,
+        ),
+    )
+    return shown(edited.raw, views.candidate, raw)
+
+
+@reviewed(DECIDE, "digitisation.review")
+async def review_candidate(
+    ctx: Context,
+    candidate_id: str,
+    candidate_sha256: str,
+    decision: Literal["accept", "reject"],
+    raw: bool = False,
+) -> dict[str, Any]:
+    """Accept or reject a pending candidate, bound to the `candidate_sha256` the user
+    reviewed; a candidate that changed since is refused."""
+    key = idempotency_key(
+        "review_candidate",
+        candidate_id=candidate_id,
+        candidate_sha256=candidate_sha256,
+        decision=decision,
+    )
+
+    def decide(c: AsyncMorphiaOne):
+        verb = c.digitisation.accept_candidate
+        if decision == "reject":
+            verb = c.digitisation.reject_candidate
+        return verb(
+            candidate_id, candidate_sha256=candidate_sha256, idempotency_key=key
+        )
+
+    return shown((await call(ctx, decide)).raw, views.candidate, raw)
+
+
+@reviewed(DECIDE, "catalogue.write")
+async def stage_candidate(
+    ctx: Context,
+    candidate_id: str,
+    candidate_sha256: str,
+    applications: list[dict[str, Any]],
+    external_ref: str | None = None,
+    variant_id: str | None = None,
+    expected_generation: int | None = None,
+    raw: bool = False,
+) -> dict[str, Any]:
+    """Write an accepted candidate into the catalogue as an unpublished draft: a new
+    variant (`external_ref`, its SKU) or a new revision of `variant_id` at the
+    `expected_generation` you read. Nothing renders until someone publishes it in the
+    Platform. Example applications: [{"application_id": "lips", "category": "lipstick"}]."""
+    key = idempotency_key(
+        "stage_candidate",
+        candidate_id=candidate_id,
+        candidate_sha256=candidate_sha256,
+        applications=applications,
+        external_ref=external_ref,
+        variant_id=variant_id,
+        expected_generation=expected_generation,
+    )
+    staged = await call(
+        ctx,
+        lambda c: c.digitisation.stage_candidate(
+            candidate_id,
+            candidate_sha256=candidate_sha256,
+            applications=applications,
+            external_ref=external_ref,
+            variant_id=variant_id,
+            expected_generation=expected_generation,
+            idempotency_key=key,
+        ),
+    )
+    return shown(staged.raw, views.stage, raw)
+
+
+@reviewed(DECIDE, "catalogue.write", "catalogue.read")
+async def import_shades(ctx: Context, rows: list[dict[str, Any]]) -> dict[str, Any]:
+    """Add or revise many shades whose colours are already known, one result per row;
+    a bad row never stops the rest. A row: {"display_color": "#C27461",
+    "external_ref": "SKU-1", "applications": [...]}, plus optional shade_name,
+    product_name, brand, finish, gtin. A taken external_ref is revised. Drafts only."""
+    done = await call(ctx, lambda c: c.catalogue.import_shades(rows))
+    return {
+        "results": [
+            {
+                "external_ref": r.row.get("external_ref"),
+                "outcome": r.outcome,
+                "variant_id": r.variant_id,
+                "error": None if r.error is None else str(r.error),
+            }
+            for r in done
+        ]
+    }
+
+
+@server.custom_route("/healthz", methods=["GET"], include_in_schema=False)
+async def healthz(_: Request) -> Response:
+    return JSONResponse({"status": "ok"})
+
+
+def protected_resource() -> dict[str, Any] | None:
+    """This server's RFC 9728 metadata, or ``None`` when the deployment names no
+    authorization server (a key-only deployment, as before)."""
+    resource = os.environ.get(RESOURCE_URL_ENV, "").strip()
+    servers = _allowlist(AUTHORIZATION_SERVERS_ENV, "")
+    if not resource or not servers:
+        return None
+    return {
+        "resource": resource,
+        "authorization_servers": servers,
+        "bearer_methods_supported": ["header"],
+        "resource_name": "MorphiaOne",
+    }
+
+
+def metadata_url(resource: str) -> str:
+    """Where a client reads the metadata for ``resource``: the well-known path with
+    the resource's own path appended (RFC 9728 section 3.1)."""
+    parts = urlsplit(resource)
+    return f"{parts.scheme}://{parts.netloc}{METADATA_PATH}{parts.path.rstrip('/')}"
+
+
+@server.custom_route(METADATA_PATH, methods=["GET"], include_in_schema=False)
+@server.custom_route(f"{METADATA_PATH}/mcp", methods=["GET"], include_in_schema=False)
+async def oauth_protected_resource(_: Request) -> Response:
+    document = protected_resource()
+    if document is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    return JSONResponse(document, headers={"Cache-Control": "public, max-age=3600"})
+
+
+def challenge() -> str:
+    document = protected_resource()
+    if document is None:
+        return "Bearer"
+    return f'Bearer resource_metadata="{metadata_url(document["resource"])}"'
+
+
+class RequireBearer:
+    """A request to /mcp without a bearer is an HTTP 401 before any MCP handling. With
+    OAuth configured, the challenge names the metadata, so a connector can sign in."""
+
+    def __init__(self, app: Any) -> None:
+        self.app = app
+
+    async def __call__(self, scope, receive, send) -> None:
+        if scope["type"] == "http" and scope["path"].startswith("/mcp"):
+            raw = dict(scope["headers"]).get(b"authorization", b"").decode("latin-1")
+            if bearer({"authorization": raw}) is None:
+                refusal = JSONResponse(
+                    {
+                        "error": "send your MorphiaOne API key or access token "
+                        "as Authorization: Bearer"
+                    },
+                    status_code=401,
+                    headers={"WWW-Authenticate": challenge()},
+                )
+                await refusal(scope, receive, send)
+                return
+        await self.app(scope, receive, send)
+
+
+def _allowlist(env: str, default: str) -> list[str]:
+    return [
+        one.strip() for one in os.environ.get(env, default).split(",") if one.strip()
+    ]
+
+
+def transport_security() -> TransportSecuritySettings:
+    """DNS-rebinding protection, always on: an unlisted Host is 421, an unlisted
+    Origin 403. A request without an Origin (every native MCP client) passes."""
+    return TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=_allowlist(ALLOWED_HOSTS_ENV, DEFAULT_ALLOWED_HOSTS),
+        allowed_origins=_allowlist(ALLOWED_ORIGINS_ENV, DEFAULT_ALLOWED_ORIGINS),
+    )
+
+
+app = RequireBearer(
+    server.streamable_http_app(
+        stateless_http=True, json_response=True, transport_security=transport_security()
+    )
+)
+
+
+def main(argv: list[str] | None = None) -> None:
+    """``morphiaone-mcp``: the same tools over stdio, on the user's machine."""
+    global LOCAL
+    parser = argparse.ArgumentParser(
+        prog="morphiaone-mcp",
+        description="MorphiaOne MCP server over stdio. Reads MORPHIAONE_API_KEY; "
+        "an MCP client starts it (see `morphiaone mcp install`).",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"morphiaone-mcp {VERSION}"
+    )
+    parser.parse_args(argv)
+    LOCAL = True
+    server.run(transport="stdio")

morphiaone_mcp-0.1.0/morphiaone_mcp.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: morphiaone-mcp
+Version: 0.1.0
+Summary: MCP server for MorphiaOne shade digitisation, a thin client of the public V1 API.
+Author: MorphiaOne
+License-Expression: MIT
+Project-URL: Documentation, https://docs.morphiaone.ai/guides/ai-agents
+Project-URL: Repository, https://github.com/MorphiaOne/vision-api
+Keywords: morphiaone,mcp,model-context-protocol,ai-agents,digitisation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: morphiaone<0.12,>=0.11
+Requires-Dist: mcp<2.4,>=2.3.0
+Dynamic: license-file
+
+# morphiaone-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude, Cursor or any MCP
+client digitise product shade colours through the MorphiaOne V1 API: retain a photo,
+measure regions, propose a candidate, review it and stage it as an unpublished
+catalogue draft. It is a thin client of the public API, so your key's scopes, rate
+limits, credits and test mode apply as they do anywhere else.
+
+## Install
+
+```sh
+pip install morphiaone        # the CLI that writes the client configuration
+morphiaone mcp install --client claude-code     # or cursor, claude-desktop
+```
+
+`morphiaone mcp install` adds one `morphiaone` server to the client's configuration
+and leaves the others as they are. It runs `morphiaone-mcp` if it is on your `PATH`
+(`pipx install morphiaone-mcp`), otherwise `uvx morphiaone-mcp`. `--print` shows the
+entry without writing it.
+
+The server reads the key from `MORPHIAONE_API_KEY`. Claude Code and Cursor expand that
+reference when they start the server, so no key is written to their files. Claude
+Desktop expands nothing, so its file would hold the key: the command writes it only
+with `--store-key`. Use a test-mode key, or one with only `digitisation.read` and
+`digitisation.write`, and revoke it when you stop.
+
+`MORPHIAONE_BASE_URL` defaults to `https://api.morphiaone.ai`.
+
+## What the agent can do
+
+The tools it sees are the ones your key holds every scope for. Give an agent
+`digitisation.read` and `digitisation.write` and it proposes; a person reviews and
+stages in the Platform. Staging is not publishing: a draft renders nothing until
+someone publishes it.
+
+Guide, tools and scopes: https://docs.morphiaone.ai/guides/ai-agents
+
+`morphiaone-mcp --version` prints the installed version; include it when you report a
+problem, with the `request_id` of any refused call.

morphiaone_mcp-0.1.0/morphiaone_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+morphiaone_mcp/__init__.py
+morphiaone_mcp/server.py
+morphiaone_mcp.egg-info/PKG-INFO
+morphiaone_mcp.egg-info/SOURCES.txt
+morphiaone_mcp.egg-info/dependency_links.txt
+morphiaone_mcp.egg-info/entry_points.txt
+morphiaone_mcp.egg-info/requires.txt
+morphiaone_mcp.egg-info/top_level.txt

morphiaone_mcp-0.1.0/morphiaone_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

morphiaone_mcp-0.1.0/morphiaone_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+morphiaone-mcp = morphiaone_mcp.server:main

morphiaone_mcp-0.1.0/morphiaone_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+morphiaone<0.12,>=0.11
+mcp<2.4,>=2.3.0

morphiaone_mcp-0.1.0/morphiaone_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+morphiaone_mcp

morphiaone_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "morphiaone-mcp"
+version = "0.1.0"
+description = "MCP server for MorphiaOne shade digitisation, a thin client of the public V1 API."
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+# The server overrides mcp's tool-call path, so it takes patch releases only. The image
+# lock (requirements-mcp.txt) pins both exactly; a checkout installs ../sdk/python.
+dependencies = ["morphiaone>=0.11,<0.12", "mcp>=2.3.0,<2.4"]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "MorphiaOne" }]
+keywords = ["morphiaone", "mcp", "model-context-protocol", "ai-agents", "digitisation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.scripts]
+morphiaone-mcp = "morphiaone_mcp.server:main"
+
+[project.urls]
+Documentation = "https://docs.morphiaone.ai/guides/ai-agents"
+Repository = "https://github.com/MorphiaOne/vision-api"
+
+[tool.setuptools]
+packages = ["morphiaone_mcp"]
+include-package-data = false

morphiaone_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+