alt_text

Implementation Reference

• src/cv_mcp/mcp_server.py:80-92 (handler)

  MCP tool handler for 'alt_text'. Validates input (image_url or file_path), constructs image_ref, and delegates to run_alt_text from metadata.runner.

  @mcp.tool()
  def alt_text(
      image_url: Optional[str] = None,
      file_path: Optional[str] = None,
      max_words: int = 20,
  ) -> str:
      if not image_url and not file_path:
          raise ValueError("Provide either image_url or file_path")
      if image_url and file_path:
          raise ValueError("Provide only one of image_url or file_path, not both")
      image_ref = image_url or file_path  # type: ignore
      return run_alt_text(image_ref, max_words=max_words)

• src/cv_mcp/metadata/runner.py:118-144 (helper)

  Core implementation of alt_text generation. Supports local, Ollama, and OpenRouter backends using specific system and user prompts from prompts.py.

  def run_alt_text(image_ref: str, *, model: Optional[str] = None, max_words: int = 20) -> str:
      if _use_local_for("caption"):
          prompt = f"{prompts.ALT_SYSTEM}\n\n{prompts.alt_user_prompt(max_words)}"
          return _local_gen(image_ref, prompt)
      if _use_ollama_for("caption"):
          from cv_mcp.captioning.ollama_client import OllamaClient
          client = OllamaClient(host=str(_cfg_value("ollama_host", "http://localhost:11434")))
          res = client.analyze_single_image(
              image_ref,
              prompts.alt_user_prompt(max_words),
              model=_cfg_value("caption_model"),
              system=prompts.ALT_SYSTEM,
          )
          if not res.get("success"):
              raise RuntimeError(str(res.get("error", "Alt text generation failed (ollama)")))
          return str(res.get("content", "")).strip()
      client = OpenRouterClient()
      res = client.analyze_single_image(
          image_ref,
          prompts.alt_user_prompt(max_words),
          model=model or _cfg_value("caption_model"),
          system=prompts.ALT_SYSTEM,
      )
      if not res.get("success"):
          raise RuntimeError(str(res.get("error", "Alt text generation failed")))
      return str(res.get("content", "")).strip()

• src/cv_mcp/metadata/prompts.py:1-13 (helper)

  System prompt and user prompt template used by run_alt_text for generating factual alt text descriptions.

  from __future__ import annotations
  
  ALT_SYSTEM = (
      "You describe images for accessibility. Be concise and strictly factual. Do not infer unseen details."
  )
  
  
  def alt_user_prompt(max_words: int = 20) -> str:
      return (
          f"Describe this image in <= {max_words} words. Neutral tone. "
          "No brand/species/location guesses. Return one sentence only. If unknown, omit."
      )