cv-forge-mcp

Instructions

Implementation Reference

• mcp_server.py:217-284 (handler)

  The 'cv_forge_setup' function is defined here, which handles setting up the CV Forge backend by choosing between local Docker and remote hosting modes. It is also decorated with '@mcp.tool()', which handles the registration.

  @mcp.tool()
  def cv_forge_setup(mode: str = "auto") -> str:
      """Set up CV Forge backend. MUST be called before generate_pdf or generate_docx.
  
      Detects the environment and lets the user choose how to run CV Forge:
      - "local": Run locally via Docker (pulls image if needed, ~1.7 GB)
      - "remote": Use the hosted demo at cv.guidlab.pl (no install needed)
      - "auto": Auto-detect — use local if Docker is available, otherwise remote
  
      If mode is "auto", present the user with the available options and ask which
      they prefer. If only one option is available, use it automatically.
  
      Args:
          mode: "local", "remote", or "auto" (default).
      """
      global _base_url, _mode
  
      env_url = os.environ.get("CV_FORGE_URL", "").strip().rstrip("/")
      if env_url:
          _base_url = env_url
          _mode = "custom"
          return json.dumps({"status": "ready", "mode": "custom", "url": env_url})
  
      info = _check_environment()
  
      if mode == "remote":
          if not info["remote"]:
              return json.dumps({"status": "error", "message": "Remote server cv.guidlab.pl is not reachable."})
          _base_url = REMOTE_URL
          _mode = "remote"
          return json.dumps({"status": "ready", "mode": "remote", "url": REMOTE_URL})
  
      if mode == "local":
          if info["local_running"]:
              _base_url = LOCAL_URL
              _mode = "local"
              return json.dumps({"status": "ready", "mode": "local", "url": LOCAL_URL})
          if not info["docker"]:
              return json.dumps({"status": "error", "message": "Docker is not installed. Install Docker or use mode='remote'."})
          if _start_local():
              _base_url = LOCAL_URL
              _mode = "local"
              return json.dumps({"status": "ready", "mode": "local", "url": LOCAL_URL})
          return json.dumps({"status": "error", "message": "Failed to start local container."})
  
      # mode == "auto" — present options
      if info["local_running"]:
          _base_url = LOCAL_URL
          _mode = "local"
          return json.dumps({"status": "ready", "mode": "local", "url": LOCAL_URL,
                             "message": "Using already running local instance."})
  
      options = []
      if info["docker"]:
          if info["docker_image"]:
              options.append({"mode": "local", "description": "Local Docker (image ready, fast startup)"})
          else:
              options.append({"mode": "local", "description": "Local Docker (needs to pull ~1.7 GB image first)"})
      if info["remote"]:
          options.append({"mode": "remote", "description": "Remote server cv.guidlab.pl (no install needed)"})
  
      if not options:
          return json.dumps({"status": "error",
                             "message": "No backend available. Install Docker or check your internet connection."})
  
      if len(options) == 1:
          # Only one option — use it directly
          return cv_forge_setup(mode=options[0]["mode"])