logodev-mcp 1.0.0__py3-none-any.whl

logodev_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Logo.dev MCP.
+
+Look up company logos and brand data via the logo.dev API.
+"""
+
+__version__ = "0.1.0"

logodev_mcp/_server_apps.py

@@ -0,0 +1,37 @@
+"""MCP Apps scaffolding for Logo.dev MCP.
+
+Ships as an inert placeholder: ``register_apps`` is a no-op unless the
+``LOGODEV_MCP_APP_DOMAIN`` or ``LOGODEV_MCP_BASE_URL`` env
+vars are set.  Adopt MCP Apps by copying MV's ``_server_apps.py`` as a
+reference once you need a real UI resource.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+_ENV_PREFIX = "LOGODEV_MCP"
+
+
+def register_apps(_mcp: FastMCP) -> None:
+    """Register MCP Apps resources on *mcp*.
+
+    This scaffold intentionally registers nothing; check the env var
+    and log that the scaffold is inactive.  Real projects replace the
+    body with resource + tool registrations following MV's pattern.
+    """
+    app_domain = (
+        os.environ.get(f"{_ENV_PREFIX}_APP_DOMAIN", "").strip()
+        or os.environ.get(f"{_ENV_PREFIX}_BASE_URL", "").strip()
+    )
+    if app_domain:
+        logger.info(
+            "MCP Apps scaffold present but not wired — app_domain=%s", app_domain
+        )
+    else:
+        logger.debug("MCP Apps scaffold inactive (no app_domain configured)")

logodev_mcp/_server_deps.py

@@ -0,0 +1,49 @@
+"""Service lifespan + dependency injection for Logo.dev MCP."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, TypedDict
+
+from fastmcp.dependencies import CurrentContext
+from fastmcp.server.context import Context
+
+from logodev_mcp.domain import Service
+
+logger = logging.getLogger(__name__)
+
+
+class LifespanState(TypedDict):
+    """Shape of the lifespan context yielded to request handlers."""
+
+    service: Service
+
+
+@asynccontextmanager
+async def server_lifespan(_mcp: object) -> AsyncIterator[dict[str, Any]]:
+    """Start the service on startup; stop it on shutdown."""
+    service = Service()
+    await service.start()
+    logger.info("Service started")
+    try:
+        yield {"service": service}
+    finally:
+        await service.stop()
+        logger.info("Service stopped")
+
+
+def get_service(ctx: Context = CurrentContext()) -> Service:
+    """Resolve the running :class:`Service` from the request context.
+
+    Use as a ``Depends`` default in tool/resource/prompt handlers.
+
+    Raises:
+        RuntimeError: If the server lifespan has not run.
+    """
+    service: Service | None = ctx.lifespan_context.get("service")
+    if service is None:
+        msg = "Service not initialised — server lifespan has not run"
+        raise RuntimeError(msg)
+    return service

logodev_mcp/cli.py

@@ -0,0 +1,118 @@
+"""Command-line interface for Logo.dev MCP."""
+
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+import typer
+from fastmcp_pvl_core import (
+    build_event_store,
+    configure_logging_from_env,
+    maybe_start_debugpy,
+    normalise_http_path,
+)
+
+from logodev_mcp.config import _ENV_PREFIX, ProjectConfig
+
+app = typer.Typer(
+    name="logodev-mcp",
+    help="Look up company logos and brand data via the logo.dev API.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+Transport = Literal["stdio", "http", "sse"]
+
+
+@app.callback()
+def _root(
+    verbose: bool = typer.Option(
+        False, "-v", "--verbose", help="Enable debug logging."
+    ),
+) -> None:
+    """Root callback — bootstraps logging for every subcommand.
+
+    ``configure_logging_from_env`` sets the root logger *level* and
+    configures FastMCP's own logger tree, but does NOT attach a handler
+    to the root logger — so ``logodev_mcp.*`` loggers would have
+    no output.  Attach one here.  Kept idempotent via the
+    ``if not root.handlers`` guard so repeated calls (e.g. from
+    ``make_server()`` on the same process) are safe.
+    """
+    configure_logging_from_env(verbose=verbose)
+    root = logging.getLogger()
+    if not root.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(levelname)s %(name)s: %(message)s"))
+        root.addHandler(handler)
+    if verbose:
+        # httpx/httpcore are noisy at DEBUG; keep them quiet.  Core doesn't
+        # own these deps, so the silencing stays domain-local.
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+        logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+
+@app.command()
+def serve(
+    transport: Transport = typer.Option(
+        "stdio", help="MCP transport (stdio / http / sse)."
+    ),
+    host: str = typer.Option("0.0.0.0", help="Bind host (http only)."),
+    port: int = typer.Option(8000, help="Bind port (http only)."),
+    http_path: str | None = typer.Option(
+        None,
+        "--http-path",
+        "--path",
+        help=(f"Mount path (http only, default: ${_ENV_PREFIX}_HTTP_PATH or /mcp)."),
+    ),
+) -> None:
+    """Run the MCP server."""
+    import os
+
+    from logodev_mcp.server import make_server
+
+    # Optional remote-debugger listener — placed in ``serve`` (not the
+    # typer root callback) so non-server commands like ``--help``,
+    # ``--version``, or future ``dump-config``-style subcommands are
+    # never blocked by ``LOGODEV_MCP_DEBUG_WAIT=true``.  No-op
+    # unless ``LOGODEV_MCP_DEBUG_PORT`` is set; ``debugpy`` is only
+    # present when the image was built with ``--build-arg DEBUG=true``
+    # (a missing import logs a WARNING and continues).  ``_root`` has
+    # already attached the StreamHandler by the time ``serve`` runs, so
+    # the helper's INFO/WARNING logs route through the configured
+    # formatter rather than Python's lastResort.
+    maybe_start_debugpy(_ENV_PREFIX)
+
+    config = ProjectConfig.from_env()
+    server = make_server(transport=transport, config=config)
+
+    if transport == "http":
+        import uvicorn
+
+        path = normalise_http_path(
+            http_path or os.environ.get(f"{_ENV_PREFIX}_HTTP_PATH")
+        )
+        event_store = build_event_store(_ENV_PREFIX, config.server)
+        # lifespan="on" is essential: FastMCP's server_lifespan (startup/shutdown
+        # hooks, including service init) runs through the ASGI lifespan protocol.
+        # timeout_graceful_shutdown=3 lets SIGTERM drain requests within 3s so
+        # containers (Docker/k8s) stop cleanly.
+        uvicorn.run(
+            server.http_app(path=path, event_store=event_store),
+            host=host,
+            port=port,
+            lifespan="on",
+            timeout_graceful_shutdown=3,
+        )
+    else:
+        server.run(transport=transport)
+
+
+def main() -> None:
+    """CLI entry point — used by ``[project.scripts]`` in pyproject.toml."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

logodev_mcp/config.py

@@ -0,0 +1,48 @@
+"""Configuration for Logo.dev MCP.
+
+Composes :class:`fastmcp_pvl_core.ServerConfig` via the domain
+:class:`ProjectConfig` dataclass — never inherits.
+
+Add domain-specific fields between the CONFIG-FIELDS sentinels; copier
+update preserves that block across template updates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from fastmcp_pvl_core import (
+    ServerConfig,
+    env,
+)
+
+_ENV_PREFIX = "LOGODEV_MCP"
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    """Domain config for Logo.dev MCP.  Compose — don't inherit."""
+
+    server: ServerConfig = field(default_factory=ServerConfig)
+
+    # CONFIG-FIELDS-START — add domain fields below; kept across copier update
+    # (uncommenting the Path-typed examples below also requires adding
+    #  ``from pathlib import Path`` to the imports at the top of this file.)
+    # (example)
+    # vault_path: Path = Path("/data/vault")
+    publishable_key: str | None = None
+    secret_key: str | None = None
+    # CONFIG-FIELDS-END
+
+    @classmethod
+    def from_env(cls) -> ProjectConfig:
+        """Load :class:`ProjectConfig` from ``LOGODEV_MCP_*`` env vars."""
+        return cls(
+            server=ServerConfig.from_env(_ENV_PREFIX),
+            # CONFIG-FROM-ENV-START — populate domain fields below; kept across copier update
+            # (example)
+            # vault_path=Path(env(_ENV_PREFIX, "VAULT_PATH", "/data/vault")),
+            publishable_key=env(_ENV_PREFIX, "PUBLISHABLE_KEY"),
+            secret_key=env(_ENV_PREFIX, "SECRET_KEY"),
+            # CONFIG-FROM-ENV-END
+        )

logodev_mcp/domain.py

@@ -0,0 +1,270 @@
+"""Domain logic for Logo.dev MCP — a thin async client over the logo.dev API.
+
+Plain Python only: no FastMCP types here so the logic is unit-testable
+without a server.  Tool wrappers in ``tools.py`` adapt these methods to
+MCP (error strings, ``Image`` content).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from logodev_mcp.config import ProjectConfig
+
+logger = logging.getLogger(__name__)
+
+API_BASE = "https://api.logo.dev"
+IMG_BASE = "https://img.logo.dev"
+
+_IDENTIFIER_PATHS = {
+    "domain": "/{ident}",
+    "ticker": "/ticker/{ident}",
+    "isin": "/isin/{ident}",
+    "crypto": "/crypto/{ident}",
+    "name": "/name/{ident}",
+}
+_FORMATS = ("jpg", "png", "webp")
+_THEMES = ("auto", "light", "dark")
+# "404" is passed through to logo.dev as the ``fallback`` query value (the
+# alternative to "monogram"): it asks for an HTTP 404 rather than a placeholder
+# image when no logo exists for the identifier.
+_FALLBACKS = ("monogram", "404")
+_STRATEGIES = ("suggest", "match")
+
+_TIMEOUT = 30.0
+
+
+class LogoDevError(Exception):
+    """A logo.dev request failed validation or returned an error response."""
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+class Service:
+    """Async client over the logo.dev REST and image APIs.
+
+    Pass an explicit :class:`ProjectConfig` for tests; in production the
+    lifespan constructs ``Service()`` with no args and :meth:`start` loads
+    config from the environment.
+    """
+
+    def __init__(self, config: ProjectConfig | None = None) -> None:
+        self._config = config
+        self._api: httpx.AsyncClient | None = None
+        self._img: httpx.AsyncClient | None = None
+        self.has_publishable = False
+        self.has_secret = False
+
+    async def start(self) -> None:
+        """Load config (if not injected) and build the configured clients.
+
+        Re-entrant: if called while already started, the existing clients are
+        closed first so their connection pools are not leaked.
+        """
+        if self._api is not None or self._img is not None:
+            await self.stop()
+        config = self._config or ProjectConfig.from_env()
+        self._config = config
+        self.has_publishable = bool(config.publishable_key)
+        self.has_secret = bool(config.secret_key)
+
+        if self.has_secret:
+            self._api = httpx.AsyncClient(
+                base_url=API_BASE,
+                headers={"Authorization": f"Bearer {config.secret_key}"},
+                timeout=_TIMEOUT,
+            )
+        if self.has_publishable:
+            self._img = httpx.AsyncClient(base_url=IMG_BASE, timeout=_TIMEOUT)
+
+        # Report each API by its client object, not by the secret-named flags.
+        # has_secret is only a bool (no key value), but CodeQL's
+        # py/clear-text-logging-sensitive-data heuristic still flags the
+        # config.secret_key -> has_secret -> log-sink path; logging client
+        # presence avoids that false positive.
+        logger.info(
+            "service_started image_api=%s rest_api=%s",
+            self._img is not None,
+            self._api is not None,
+        )
+
+    async def stop(self) -> None:
+        """Close any open clients.  Safe to call more than once."""
+        # Null the references first so a failure mid-close cannot leave a
+        # half-closed client reachable, and a second stop() is always a no-op.
+        api, img = self._api, self._img
+        self._api = None
+        self._img = None
+        for client in (api, img):
+            if client is not None:
+                await client.aclose()
+
+    # --- internal helpers ---
+
+    def _raise_for_status(self, resp: httpx.Response, *, subject: str) -> None:
+        """Map an error response to a :class:`LogoDevError`; no-op on success."""
+        code = resp.status_code
+        if code < 400:
+            return
+        # Log server-side before surfacing the user-facing string — the caller
+        # only sees the returned message, so this is the operator's trace.
+        logger.warning("logodev_http_error status=%s subject=%s", code, subject)
+        if code in (401, 403):
+            raise LogoDevError(
+                "Authentication or plan-tier problem — check your "
+                "LOGODEV_MCP_SECRET_KEY and that your plan includes this "
+                "endpoint.",
+                status=code,
+            )
+        if code == 404:
+            raise LogoDevError(f"No result found for {subject!r}.", status=404)
+        if code == 429:
+            raise LogoDevError("logo.dev rate limit reached — retry later.", status=429)
+        raise LogoDevError(f"logo.dev error: {code} {resp.text}", status=code)
+
+    async def _get(
+        self,
+        client: httpx.AsyncClient,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        subject: str,
+    ) -> httpx.Response:
+        """GET with transport-error translation and status mapping."""
+        try:
+            resp = await client.get(path, params=params)
+        except httpx.TimeoutException as exc:
+            logger.warning("logodev_timeout subject=%s", subject)
+            raise LogoDevError("logo.dev did not respond in time.") from exc
+        except httpx.TransportError as exc:
+            logger.warning(
+                "logodev_transport_error subject=%s error=%s",
+                subject,
+                type(exc).__name__,
+            )
+            raise LogoDevError("Cannot reach logo.dev.") from exc
+        self._raise_for_status(resp, subject=subject)
+        return resp
+
+    async def get_logo(
+        self,
+        identifier: str,
+        *,
+        identifier_type: str = "domain",
+        size: int = 128,
+        image_format: str = "png",
+        theme: str = "auto",
+        greyscale: bool = False,
+        retina: bool = False,
+        fallback: str = "monogram",
+        url_only: bool = False,
+    ) -> tuple[str, bytes | None]:
+        """Build the img.logo.dev URL and (unless ``url_only``) fetch the bytes."""
+        # The _config/_img None checks also narrow them to non-None for mypy below.
+        if not self.has_publishable or self._config is None or self._img is None:
+            raise LogoDevError(
+                "Logo API not configured — set LOGODEV_MCP_PUBLISHABLE_KEY."
+            )
+        if identifier_type not in _IDENTIFIER_PATHS:
+            raise LogoDevError(
+                f"Invalid identifier_type {identifier_type!r}; expected one of "
+                f"{list(_IDENTIFIER_PATHS)}."
+            )
+        if not 1 <= size <= 800:
+            raise LogoDevError("size must be between 1 and 800.")
+        if image_format not in _FORMATS:
+            raise LogoDevError(
+                f"Invalid format {image_format!r}; expected one of {list(_FORMATS)}."
+            )
+        if theme not in _THEMES:
+            raise LogoDevError(
+                f"Invalid theme {theme!r}; expected one of {list(_THEMES)}."
+            )
+        if fallback not in _FALLBACKS:
+            raise LogoDevError(
+                f"Invalid fallback {fallback!r}; expected one of {list(_FALLBACKS)}."
+            )
+
+        path = _IDENTIFIER_PATHS[identifier_type].format(
+            ident=quote(identifier, safe="")
+        )
+        params: dict[str, Any] = {
+            "token": self._config.publishable_key,
+            "format": image_format,
+        }
+        if size != 128:
+            params["size"] = size
+        if theme != "auto":
+            params["theme"] = theme
+        if greyscale:
+            params["greyscale"] = "true"
+        if retina:
+            params["retina"] = "true"
+        if fallback != "monogram":
+            params["fallback"] = fallback
+
+        url = str(httpx.URL(IMG_BASE + path, params=params))
+        if url_only:
+            return url, None
+
+        resp = await self._get(self._img, path, params=params, subject=identifier)
+        return url, resp.content
+
+    def _require_secret(self) -> httpx.AsyncClient:
+        """Return the api client, or raise if the secret key is unconfigured."""
+        if not self.has_secret or self._api is None:
+            raise LogoDevError(
+                "This endpoint needs a secret key — set LOGODEV_MCP_SECRET_KEY "
+                "(Search/Describe/Brand require a paid plan)."
+            )
+        return self._api
+
+    def _json(self, resp: httpx.Response, *, subject: str) -> Any:
+        """Parse a JSON body, mapping a malformed payload to a LogoDevError."""
+        try:
+            return resp.json()
+        except ValueError as exc:  # json.JSONDecodeError is a ValueError subclass
+            logger.warning("logodev_bad_json subject=%s", subject)
+            raise LogoDevError(
+                "logo.dev returned a response that could not be parsed."
+            ) from exc
+
+    async def search_brands(self, query: str, *, strategy: str = "suggest") -> Any:
+        """Resolve a brand/company name to candidate domains."""
+        api = self._require_secret()
+        if strategy not in _STRATEGIES:
+            raise LogoDevError(
+                f"Invalid strategy {strategy!r}; expected one of {list(_STRATEGIES)}."
+            )
+        if not query.strip():
+            raise LogoDevError("query must not be empty.")
+        params: dict[str, Any] = {"q": query}
+        if strategy != "suggest":
+            params["strategy"] = strategy
+        resp = await self._get(api, "/search", params=params, subject=query)
+        return self._json(resp, subject=query)
+
+    async def describe_company(self, domain: str) -> Any:
+        """Return structured company data for a domain."""
+        api = self._require_secret()
+        if not domain.strip():
+            raise LogoDevError("domain must not be empty.")
+        resp = await self._get(
+            api, f"/describe/{quote(domain, safe='')}", subject=domain
+        )
+        return self._json(resp, subject=domain)
+
+    async def get_brand(self, domain: str) -> Any:
+        """Return the full brand profile for a domain."""
+        api = self._require_secret()
+        if not domain.strip():
+            raise LogoDevError("domain must not be empty.")
+        resp = await self._get(api, f"/brand/{quote(domain, safe='')}", subject=domain)
+        return self._json(resp, subject=domain)

logodev_mcp/prompts.py

@@ -0,0 +1,21 @@
+"""Prompt registrations for Logo.dev MCP.
+
+See FastMCP prompt docs: https://gofastmcp.com/servers/prompts
+"""
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+
+def register_prompts(mcp: FastMCP) -> None:
+    """Register all domain prompts on *mcp*."""
+
+    @mcp.prompt()
+    async def summarize(context: str) -> str:
+        """Summarize ``context`` in one paragraph.
+
+        See https://gofastmcp.com/servers/prompts#prompt-arguments for
+        the full signature surface.
+        """
+        return f"Summarize the following in one paragraph:\n\n{context}"

logodev_mcp/resources.py

@@ -0,0 +1,34 @@
+"""Resource registrations for Logo.dev MCP.
+
+See FastMCP resource docs: https://gofastmcp.com/servers/resources
+"""
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+from logodev_mcp._server_deps import get_service
+from logodev_mcp.domain import Service
+
+
+def register_resources(mcp: FastMCP) -> None:
+    """Register all domain resources on *mcp*."""
+
+    @mcp.resource("status://logodev-mcp")
+    async def status(service: Service = Depends(get_service)) -> dict[str, object]:
+        """Service status resource — JSON-serialisable dict.
+
+        Templated resources take path parameters in the URI; static
+        resources don't. See
+        https://gofastmcp.com/servers/resources#templates for the full
+        pattern.
+        """
+        return {
+            # "ready" reflects an operable service: started AND at least one
+            # API key configured, so a keyless (no-tool) deployment reports
+            # not-ready rather than masking the misconfiguration.
+            "ready": service.has_publishable or service.has_secret,
+            "has_publishable": service.has_publishable,
+            "has_secret": service.has_secret,
+        }

logodev_mcp/server.py

@@ -0,0 +1,121 @@
+"""Logo.dev MCP — FastMCP server entry point.
+
+Composes the primitives from ``fastmcp-pvl-core`` into a
+project-specific ``make_server()``.  See
+https://gofastmcp.com/servers for the FastMCP server surface and
+``fastmcp-pvl-core``'s README for the composable helpers used below.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from fastmcp import FastMCP
+from fastmcp_pvl_core import (
+    ServerConfig,  # noqa: F401  — re-exported for downstream projects' convenience
+    build_auth,
+    build_event_store,  # noqa: F401  — re-exported for downstream projects' convenience
+    build_instructions,
+    build_kv_store,  # noqa: F401  — re-exported for downstream projects' convenience
+    configure_logging_from_env,
+    register_server_info_tool,
+    resolve_auth_mode,
+    wire_middleware_stack,
+)
+
+from logodev_mcp._server_apps import register_apps
+from logodev_mcp._server_deps import server_lifespan
+from logodev_mcp.config import ProjectConfig
+from logodev_mcp.prompts import register_prompts
+from logodev_mcp.resources import register_resources
+from logodev_mcp.tools import register_tools
+
+logger = logging.getLogger(__name__)
+
+_ENV_PREFIX = "LOGODEV_MCP"
+
+
+def make_server(
+    *,
+    transport: str = "stdio",
+    config: ProjectConfig | None = None,
+) -> FastMCP:
+    """Construct the Logo.dev MCP FastMCP server.
+
+    Args:
+        transport: ``"stdio"`` / ``"http"`` / ``"sse"``.  Used here for
+            logging only.
+        config: Optional pre-loaded config; default loads from env.
+
+    Returns:
+        A configured :class:`fastmcp.FastMCP` instance.
+    """
+    config = config or ProjectConfig.from_env()
+    configure_logging_from_env()
+
+    auth = build_auth(config.server)
+    auth_mode = resolve_auth_mode(config.server) if auth is not None else "none"
+    if auth_mode == "none":
+        logger.warning(
+            "No auth configured — server accepts unauthenticated connections"
+        )
+    else:
+        logger.info("Auth enabled: mode=%s", auth_mode)
+
+    try:
+        pkg_ver = _pkg_version("logodev-mcp")
+    except PackageNotFoundError:
+        pkg_ver = "unknown"
+
+    logger.info(
+        "Server config: version=%s name=logodev-mcp transport=%s auth=%s",
+        pkg_ver,
+        transport,
+        auth_mode,
+    )
+
+    mcp = FastMCP(
+        name="logodev-mcp",
+        instructions=build_instructions(
+            read_only=True,
+            env_prefix=_ENV_PREFIX,
+            domain_line="Look up company logos and brand data via the logo.dev API.",
+        ),
+        lifespan=server_lifespan,
+        auth=auth,
+    )
+
+    wire_middleware_stack(mcp)
+
+    register_tools(mcp, config=config)
+    register_resources(mcp)
+    register_prompts(mcp)
+    register_apps(mcp)
+
+    register_server_info_tool(
+        mcp,
+        server_name="logodev-mcp",
+        server_version=pkg_ver,
+        # DOMAIN-UPSTREAM-START — wire upstream version reporting for servers
+        # that talk to a remote service (paperless-mcp, etc.). The provider is
+        # a zero-arg callable; the simplest pattern is a module-level upstream
+        # client (typically constructed from env vars at import time) whose
+        # version method is referenced here. ``CurrentContext()`` is a FastMCP
+        # DI marker — it only resolves to a live context when used as a
+        # parameter default in a tool/resource handler, so it cannot be called
+        # directly from a zero-arg provider.
+        # Uncomment the kwargs below as additional arguments to this call:
+        # upstream_version=lambda: _upstream_client.remote_version(),
+        # upstream_label="paperless",
+        # DOMAIN-UPSTREAM-END
+    )
+
+    # DOMAIN-WIRING-START — project-specific wiring (custom HTTP routes,
+    # transforms, mode toggles, alternative middleware, additional registrations);
+    # kept across copier update. Leave empty for projects that don't customise
+    # make_server() beyond the standard scaffold.
+    # DOMAIN-WIRING-END
+
+    return mcp

logodev_mcp/static/app.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<!-- Logo.dev MCP SPA shell placeholder.
+     Run scripts/vendor_spa.py to hydrate this file with the vendored
+     SDK once you're ready to ship MCP Apps UI. -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Logo.dev MCP</title>
+</head>
+<body>
+  <p>SPA placeholder — populate via scripts/vendor_spa.py.</p>
+</body>
+</html>

logodev_mcp/tools.py

@@ -0,0 +1,163 @@
+"""Tool registrations for Logo.dev MCP.
+
+See FastMCP tool docs: https://gofastmcp.com/servers/tools
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+from fastmcp.utilities.types import Image
+
+from logodev_mcp._server_deps import get_service
+from logodev_mcp.config import ProjectConfig
+from logodev_mcp.domain import LogoDevError, Service
+
+logger = logging.getLogger(__name__)
+
+_IMAGE_FORMATS = {"jpg": "jpeg", "png": "png", "webp": "webp"}
+
+
+def register_tools(mcp: FastMCP, config: ProjectConfig | None = None) -> None:
+    """Register logo.dev tools, gated by which API keys are configured.
+
+    Args:
+        mcp: The FastMCP server to register tools on.
+        config: Project configuration; loaded from the environment when omitted.
+    """
+    config = config or ProjectConfig.from_env()
+
+    if config.publishable_key:
+
+        @mcp.tool(annotations={"readOnlyHint": True})
+        async def get_logo(
+            identifier: str,
+            identifier_type: str = "domain",
+            size: int = 128,
+            image_format: str = "png",
+            theme: str = "auto",
+            greyscale: bool = False,
+            retina: bool = False,
+            fallback: str = "monogram",
+            url_only: bool = False,
+            service: Service = Depends(get_service),
+            # Intentionally ``Any``: a concrete return annotation makes FastMCP
+            # 3.4.2 emit an output schema that rejects the mixed text+image
+            # content this tool returns.
+        ) -> Any:
+            """Fetch a company logo from logo.dev.
+
+            Args:
+                identifier: Company identifier — a domain (``nike.com``), stock
+                    ticker (``AAPL``), ISIN (``US0378331005``), crypto symbol
+                    (``BTC``), or brand name, depending on ``identifier_type``.
+                identifier_type: One of ``domain`` (default), ``ticker``,
+                    ``isin``, ``crypto``, ``name``.
+                size: Pixel size, 1-800 (default 128).
+                image_format: ``png`` (default), ``jpg``, or ``webp``.
+                theme: ``auto`` (default), ``light``, or ``dark``.
+                greyscale: Render in greyscale.
+                retina: Request a 2x retina asset.
+                fallback: ``monogram`` (default) renders a placeholder when no
+                    logo exists; ``404`` returns an error instead.
+                url_only: Return only the image URL without fetching the bytes.
+
+            Returns:
+                The image URL plus the logo image, just the URL string when
+                ``url_only`` is true, or a plain error message string if the
+                logo.dev request fails.
+            """
+            try:
+                url, data = await service.get_logo(
+                    identifier,
+                    identifier_type=identifier_type,
+                    size=size,
+                    image_format=image_format,
+                    theme=theme,
+                    greyscale=greyscale,
+                    retina=retina,
+                    fallback=fallback,
+                    url_only=url_only,
+                )
+            except LogoDevError as exc:
+                return exc.message
+            if data is None:
+                return url
+            # .get() fallback keeps a future _FORMATS addition from becoming a
+            # KeyError here if its _IMAGE_FORMATS entry is forgotten.
+            image_block = Image(
+                data=data, format=_IMAGE_FORMATS.get(image_format, image_format)
+            )
+            return [url, image_block]
+
+    if config.secret_key:
+
+        @mcp.tool(annotations={"readOnlyHint": True})
+        async def search_brands(
+            query: str,
+            strategy: str = "suggest",
+            service: Service = Depends(get_service),
+        ) -> str:
+            """Resolve a brand or company name to candidate domains.
+
+            Args:
+                query: The brand/company name to look up.
+                strategy: ``suggest`` (default, typeahead) or ``match``.
+
+            Returns:
+                A JSON array of candidate brands (name, domain, logo URL).
+            """
+            try:
+                return json.dumps(await service.search_brands(query, strategy=strategy))
+            except LogoDevError as exc:
+                return exc.message
+
+        @mcp.tool(annotations={"readOnlyHint": True})
+        async def describe_company(
+            domain: str,
+            service: Service = Depends(get_service),
+        ) -> str:
+            """Return structured company data for a domain.
+
+            Args:
+                domain: The company domain (e.g. ``nike.com``).
+
+            Returns:
+                A JSON object with name, description, colors, and socials.
+            """
+            try:
+                return json.dumps(await service.describe_company(domain))
+            except LogoDevError as exc:
+                return exc.message
+
+        @mcp.tool(annotations={"readOnlyHint": True})
+        async def get_brand(
+            domain: str,
+            service: Service = Depends(get_service),
+        ) -> str:
+            """Return the full brand profile for a domain.
+
+            Args:
+                domain: The company domain (e.g. ``nike.com``).
+
+            Returns:
+                A JSON object with logo, brandmark, banners, colors, and
+                description — a richer superset of ``describe_company``.
+            """
+            try:
+                return json.dumps(await service.get_brand(domain))
+            except LogoDevError as exc:
+                return exc.message
+
+    if not config.publishable_key and not config.secret_key:
+        # Scalar key=value pairs per the project logging standard: each value
+        # names the env var that enables that API's tools.
+        logger.warning(
+            "no_api_keys_configured publishable_env=%s secret_env=%s",
+            "LOGODEV_MCP_PUBLISHABLE_KEY",
+            "LOGODEV_MCP_SECRET_KEY",
+        )

logodev_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: logodev-mcp
+Version: 1.0.0
+Summary: Look up company logos and brand data via the logo.dev API.
+Project-URL: Repository, https://github.com/pvliesdonk/logodev-mcp
+Project-URL: Documentation, https://pvliesdonk.github.io/logodev-mcp/
+Project-URL: Issues, https://github.com/pvliesdonk/logodev-mcp/issues
+Project-URL: Changelog, https://github.com/pvliesdonk/logodev-mcp/blob/main/CHANGELOG.md
+Author: pvliesdonk
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: fastmcp-pvl-core<5,>=4.0.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Provides-Extra: debug
+Requires-Dist: fastmcp-pvl-core[debug]; extra == 'debug'
+Description-Content-Type: text/markdown
+
+# Logo.dev MCP
+
+[![CI](https://github.com/pvliesdonk/logodev-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pvliesdonk/logodev-mcp/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/pvliesdonk/logodev-mcp/graph/badge.svg)](https://codecov.io/gh/pvliesdonk/logodev-mcp) [![PyPI](https://img.shields.io/pypi/v/logodev-mcp)](https://pypi.org/project/logodev-mcp/) [![Python](https://img.shields.io/pypi/pyversions/logodev-mcp)](https://pypi.org/project/logodev-mcp/) [![License](https://img.shields.io/github/license/pvliesdonk/logodev-mcp)](LICENSE) [![Docker](https://img.shields.io/github/v/release/pvliesdonk/logodev-mcp?label=ghcr.io&logo=docker)](https://github.com/pvliesdonk/logodev-mcp/pkgs/container/logodev-mcp) [![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://pvliesdonk.github.io/logodev-mcp/) [![llms.txt](https://img.shields.io/badge/llms.txt-available-brightgreen)](https://pvliesdonk.github.io/logodev-mcp/llms.txt) [![Template](https://img.shields.io/badge/dynamic/yaml?url=https://raw.githubusercontent.com/pvliesdonk/logodev-mcp/main/.copier-answers.yml&query=%24._commit&label=template)](https://github.com/pvliesdonk/fastmcp-server-template)
+
+Look up company logos and brand data via the logo.dev API.
+
+**[Documentation](https://pvliesdonk.github.io/logodev-mcp/)** | **[Config wizard](https://pvliesdonk.github.io/logodev-mcp/latest/configuration-generator/)** | **[PyPI](https://pypi.org/project/logodev-mcp/)** | **[Docker](https://github.com/pvliesdonk/logodev-mcp/pkgs/container/logodev-mcp)**
+
+## Features
+
+<!-- DOMAIN-START -->
+- **Logo retrieval** (`get_logo`) — fetch a company logo as an image plus URL by domain, ticker, ISIN, crypto symbol, or brand name; supports size, format, theme, greyscale, retina, and fallback options. Requires a publishable key (`pk_…`).
+- **Brand search** (`search_brands`) — resolve a brand or company name to candidate domains and logo URLs via typeahead or exact-match. Requires a secret key (`sk_…`).
+- **Company description** (`describe_company`) — return structured company data (name, description, brand colours, social links) for a domain. Requires a secret key (`sk_…`).
+- **Full brand profile** (`get_brand`) — return the complete brand profile (logo, brandmark, banners, colours, description) for a domain — a richer superset of `describe_company`. Requires a secret key (`sk_…`).
+- **Graceful degradation** — tools are registered only when the corresponding API key is present; missing-key tools are hidden from the MCP client rather than registered and failing at call time.
+<!-- DOMAIN-END -->
+
+## What you can do with it
+
+<!-- DOMAIN-START -->
+With this server mounted in an MCP client (Claude, etc.), you can:
+
+- **Fetch a logo** — "Get the logo for stripe.com." Uses `get_logo` (publishable key required).
+- **Identify a brand's domain** — "What domain is behind the brand 'Stripe'?" Uses `search_brands` (secret key required).
+- **Look up company info** — "What colours does Stripe use in their branding?" Uses `describe_company` (secret key required).
+- **Get the full brand kit** — "Show me the complete brand profile for shopify.com." Uses `get_brand` (secret key required).
+- **Logo by ticker** — "Fetch the logo for AAPL." Uses `get_logo` with `identifier_type=ticker` (publishable key required).
+<!-- DOMAIN-END -->
+
+<!-- ===== TEMPLATE-OWNED SECTIONS BELOW — DO NOT EDIT; CHANGES WILL BE OVERWRITTEN ON COPIER UPDATE ===== -->
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install logodev-mcp
+```
+
+If you add optional extras via the `PROJECT-EXTRAS-START` / `PROJECT-EXTRAS-END` sentinels in `pyproject.toml`, document them below:
+
+<!-- DOMAIN-START -->
+<!-- List optional extras and their purpose here (e.g. `pip install logodev-mcp[embeddings]`). Kept across copier update. -->
+<!-- DOMAIN-END -->
+
+### From source
+
+```bash
+git clone https://github.com/pvliesdonk/logodev-mcp.git
+cd logodev-mcp
+uv sync --all-extras --all-groups
+```
+
+### Docker
+
+```bash
+docker pull ghcr.io/pvliesdonk/logodev-mcp:latest
+```
+
+A `compose.yml` ships at the repo root as a starting point — copy `.env.example` to `.env`, edit, and `docker compose up -d`.
+
+To attach a remote Python debugger (development only — the protocol is unauthenticated), see [Remote debugging](docs/deployment/docker.md#remote-debugging).
+
+### Linux packages (.deb / .rpm)
+
+Download `.deb` or `.rpm` packages from the [GitHub Releases](https://github.com/pvliesdonk/logodev-mcp/releases) page. Both install a hardened systemd unit; env configuration is sourced from `/etc/logodev-mcp/env` (copy from the shipped `/etc/logodev-mcp/env.example`).
+
+### Claude Desktop (.mcpb bundle)
+
+Download the `.mcpb` bundle from the [GitHub Releases](https://github.com/pvliesdonk/logodev-mcp/releases) page and double-click to install, or run:
+
+```bash
+mcpb install logodev-mcp-<version>.mcpb
+```
+
+Claude Desktop prompts for required env vars via a GUI wizard — no manual JSON editing needed.
+
+For manual Claude Desktop configuration and setup options, see [Claude Desktop deployment](docs/deployment/claude-desktop.md).
+
+## Quick start
+
+```bash
+logodev-mcp serve                                # stdio transport
+logodev-mcp serve --transport http --port 8000   # streamable HTTP
+```
+
+For library usage (embedding the domain logic without the MCP transport), import from the `logodev_mcp` package directly — see the project's domain modules under `src/logodev_mcp/` for entry points.
+
+### Server info
+
+The server registers a built-in `get_server_info` tool (via `fastmcp_pvl_core.register_server_info_tool`) so operators can confirm the deployed version with a single MCP call. The default response carries `server_name`, `server_version`, and `core_version`. Servers that talk to a remote upstream wire upstream version reporting inside the `DOMAIN-UPSTREAM-START` / `DOMAIN-UPSTREAM-END` sentinel in `src/logodev_mcp/server.py` — see [`CLAUDE.md`](CLAUDE.md#server-info-tool-get_server_info) for the wiring pattern.
+
+## Configuration
+
+Core environment variables shared across all `fastmcp-pvl-core`-based services:
+
+| Variable | Default | Description |
+|---|---|---|
+| `FASTMCP_LOG_LEVEL` | `INFO` | Log level for FastMCP internals and app loggers (`DEBUG` / `INFO` / `WARNING` / `ERROR`). The `-v` CLI flag overrides to `DEBUG`. |
+| `FASTMCP_ENABLE_RICH_LOGGING` | `true` | Set to `false` for plain / structured JSON log output. |
+| `LOGODEV_MCP_KV_STORE_URL` | `file:///data/state` | Persistent-state backend URL for pvl-core subsystems — `file:///path` (survives restarts), `memory://` (dev/ephemeral). |
+
+Domain-specific variables go below under [Domain configuration](#domain-configuration).
+
+## Authentication
+
+Callers authenticate via a bearer token or OIDC (mutually exclusive). See the [Authentication guide](docs/guides/authentication.md) for setup, mapped multi-subject tokens, OIDC, and troubleshooting.
+
+## Post-scaffold checklist
+
+After `copier copy` and `gh repo create --push`:
+
+1. **Fill in the DOMAIN blocks** in this README (Features, What you can do with it, Domain configuration, Key design decisions) and in `CLAUDE.md`.
+2. Configure GitHub secrets — see below.
+3. Install dev + docs tooling: `uv sync --all-extras --all-groups`.
+4. Install pre-commit hooks: `uv run pre-commit install`.
+5. Run the gate locally: `uv run pytest -x -q && uv run ruff check --fix . && uv run ruff format . && uv run mypy src/ tests/`.
+6. Push the first commit — CI should be green.
+
+## GitHub secrets
+
+CI workflows reference three repository secrets. Configure them via **Settings → Secrets and variables → Actions** or with `gh secret set`:
+
+| Secret | Used by | How to generate |
+|---|---|---|
+| `RELEASE_TOKEN` | `release.yml`, `copier-update.yml` | Fine-grained PAT at <https://github.com/settings/personal-access-tokens/new> with `contents: write` and `pull_requests: write` (the `copier-update` cron opens PRs). Scoped to this repo. |
+| `CODECOV_TOKEN` | `ci.yml` | <https://codecov.io> — sign in with GitHub, add the repo, copy the upload token from the repo settings page. |
+| `CLAUDE_CODE_OAUTH_TOKEN` | `claude.yml`, `claude-code-review.yml` | Run `claude setup-token` locally and paste the result. |
+
+```bash
+gh secret set RELEASE_TOKEN
+gh secret set CODECOV_TOKEN
+gh secret set CLAUDE_CODE_OAUTH_TOKEN
+```
+
+`GITHUB_TOKEN` is auto-provided — no action needed.
+
+## Local development
+
+The PR gate (matches CI):
+
+```bash
+uv run pytest -x -q                                  # tests
+uv run ruff check --fix . && uv run ruff format .    # lint + format
+uv run mypy src/ tests/                              # type-check
+```
+
+Pre-commit runs a subset of the gate on each commit; see `.pre-commit-config.yaml` for details, or [`CLAUDE.md`](CLAUDE.md) for the full Hard PR Acceptance Gates.
+
+## Troubleshooting
+
+### Moving a scaffolded project
+
+`uv sync` creates `.venv/bin/*` scripts with absolute shebangs pointing at the venv Python. If you move the repo after scaffolding (`mv /old/path /new/path`), `uv run pytest` fails with `ModuleNotFoundError: No module named 'fastmcp'` because the stale shebang resolves to a different interpreter than the venv's site-packages.
+
+**Fix:**
+
+```bash
+rm -rf .venv
+uv sync --all-extras --all-groups
+```
+
+`uv run python -m pytest` also works as a one-shot workaround (bypasses the stale entry-script shim).
+
+### `uv.lock` refresh after `copier update`
+
+When `copier update` introduces new dependencies (e.g. a new extra added to `pyproject.toml.jinja`), CI runs `uv sync --frozen` which fails against a stale lockfile. Run `uv lock` locally and commit the refreshed `uv.lock` alongside accepting the copier-update PR.
+
+## Links
+
+- [Documentation](https://pvliesdonk.github.io/logodev-mcp/)
+- [llms.txt](https://pvliesdonk.github.io/logodev-mcp/llms.txt)
+- [FastMCP](https://gofastmcp.com)
+- [fastmcp-pvl-core](https://pypi.org/project/fastmcp-pvl-core/)
+
+<!-- ===== TEMPLATE-OWNED SECTIONS END ===== -->
+
+## Domain configuration
+
+<!-- DOMAIN-START -->
+Domain environment variables use the `LOGODEV_MCP_` prefix:
+
+| Variable | Default | Required | Description |
+|---|---|---|---|
+| `LOGODEV_MCP_PUBLISHABLE_KEY` | — | Conditional | logo.dev publishable key (`pk_…`). Enables the `get_logo` tool. Omit to hide that tool. |
+| `LOGODEV_MCP_SECRET_KEY` | — | Conditional | logo.dev secret key (`sk_…`). Enables `search_brands`, `describe_company`, and `get_brand`. Omit to hide those tools. |
+
+At least one key must be set for any API tool to be registered. Both keys may be set simultaneously to enable all four tools.
+<!-- DOMAIN-END -->
+
+## Key design decisions
+
+<!-- DOMAIN-START -->
+- **Two-key gating** — `LOGODEV_MCP_PUBLISHABLE_KEY` controls `get_logo`; `LOGODEV_MCP_SECRET_KEY` controls `search_brands`, `describe_company`, and `get_brand`. Tools for a missing key are never registered, not merely guarded at call time.
+- **Domain logic stays FastMCP-free** — `src/logodev_mcp/domain.py` contains the `Service` class and `LogoDevError` with no FastMCP imports; `src/logodev_mcp/tools.py` is the sole FastMCP layer.
+- **Errors surface as strings** — `LogoDevError` raised in domain code is caught in each tool wrapper and returned as a plain text message so the MCP client sees a readable error, not a server exception.
+- **Logo tool returns URL + image** — `get_logo` returns both the CDN URL (text) and the image bytes (image content block) unless `url_only=True`, in which case only the URL string is returned.
+<!-- DOMAIN-END -->

logodev_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+logodev_mcp/__init__.py,sha256=-JvuJoTSP6TZQxzjWuKVnA2_F3qVHf39Ay7tpHY6ZzA,104
+logodev_mcp/_server_apps.py,sha256=3HXWRE4gfLZtnFyTPJWpJWViN-IPb2phBHmWItTNSVQ,1131
+logodev_mcp/_server_deps.py,sha256=NsatfQp2I9zSeNrKdcvbtva0huEp8P9K3VofmvXCOBk,1391
+logodev_mcp/cli.py,sha256=1uLiyC1il3EV5dKmdBXgPoIJ3O--6y6RuGZGf9KLEp4,4010
+logodev_mcp/config.py,sha256=ef49KQ4E9ueKOf0yDuUHhCzAh5J6Ka3AJBllqBrrv3c,1588
+logodev_mcp/domain.py,sha256=8T_si_DwTFivySn1_G5i9fq461BUDech2rsV1LAv2Lk,10408
+logodev_mcp/prompts.py,sha256=q0sYDBuDU2gRJgcEkVVTlJi0KtA0CvlR5HGRLwszyBo,578
+logodev_mcp/resources.py,sha256=FQ-POLn8oBanBBQdPHYwSB8p9ne35VTRt7GvzDZUgfU,1213
+logodev_mcp/server.py,sha256=AyON4VwV-PKhPf2OC-uWVxUAfshrRIZj8bYebqVskbs,4091
+logodev_mcp/tools.py,sha256=FFu7e29TQKJ9ydv2qMwdlezdraRSmMJ7AGBy_FZfyLM,6104
+logodev_mcp/static/app.html,sha256=q3VIlwCRy0j3wGZJ_nGDQAQuYYNYwCgreR-QS4aDATk,354
+logodev_mcp/static/icons/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+logodev_mcp-1.0.0.dist-info/METADATA,sha256=ubpix2khiZs5Gmds6mwyDkp7VfPl77Cn0_8GZXGB4w0,12562
+logodev_mcp-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+logodev_mcp-1.0.0.dist-info/entry_points.txt,sha256=XT9UIG8NH19ogPODZ-KoP_OKRtfjc0hNToWNJa1xtfc,53
+logodev_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=XVmiSRB0z51z6Z_qxoEygSz96BAGVRZMIVD8-P_ytT8,1987
+logodev_mcp-1.0.0.dist-info/RECORD,,

logodev_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

logodev_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+logodev-mcp = logodev_mcp.cli:main

logodev_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,55 @@
+Copyright (c) 2026 pvliesdonk
+
+All rights reserved.
+
+---
+
+TODO: Choose a license for this project before publishing.
+
+This file is a placeholder shipped by the fastmcp-server-template
+scaffold.  Until you replace it, the project is proprietary and no
+permission is granted to use, copy, modify, merge, publish, distribute,
+sublicense, or sell copies of this software.
+
+How to pick and apply a license
+-------------------------------
+
+1. Pick one — see https://choosealicense.com/ (MIT, Apache-2.0,
+   BSD-3-Clause, GPL-3.0, MPL-2.0, and proprietary are all common).
+
+2. Replace this file with the full text of the chosen license.
+
+3. Update the FOUR other places the scaffold claims a license:
+
+   a. pyproject.toml:
+        license = "LicenseRef-Proprietary"
+                      ↓
+        license = "MIT"                         # or "Apache-2.0", etc.
+
+   b. pyproject.toml classifiers list:
+        "License :: Other/Proprietary License",
+                      ↓
+        "License :: OSI Approved :: MIT License",
+
+      See https://pypi.org/classifiers/ for the full classifier list.
+
+   c. packaging/mcpb/manifest.json.in:
+        "license": "UNLICENSED"
+                      ↓
+        "license": "MIT"                        # or the SPDX id you chose
+
+   d. packaging/nfpm.yaml:
+        license: "Proprietary"
+                      ↓
+        license: "MIT"
+
+4. If you never pick one, leave this file as-is and the project remains
+   proprietary.  Anyone you share the code with still has no license to
+   use it unless you explicitly grant rights separately.
+
+Caveat: the files above are in _skip_if_exists in the template, so
+future ``copier update`` runs will NOT re-render them — your license
+choice is durable across template bumps.  However, pyproject.toml
+itself is NOT skip-if-exists, so if you accept the default on a template
+update, the ``license =`` and classifier lines may flip back to the
+template's defaults.  If that happens, revert those two lines.