mcp-turboquant

Instructions

Implementation Reference

• mcp_turboquant/server.py:322-413 (handler)

  The `push` function, registered as an MCP tool, handles uploading quantized model files to the HuggingFace Hub. It manages repository creation, model card generation, and directory traversal for file uploads.

  @mcp.tool()
  def push(
      repo_id: str,
      model_dir: str,
      model: str | None = None,
      bits: int = 4,
  ) -> dict[str, Any]:
      """Push a quantized model to HuggingFace Hub.
  
      Uploads all model files from the output directory to a HuggingFace
      repository. Generates a model card (README.md) with metadata.
      Requires HuggingFace authentication (huggingface-cli login or HF_TOKEN).
  
      Args:
          repo_id: HuggingFace repository ID (e.g. 'username/model-GGUF-4bit').
          model_dir: Local directory containing the quantized model files.
          model: Original model ID for the model card (optional).
          bits: Bit width used during quantization (for model card metadata).
  
      Returns:
          Upload result with repository URL and file count.
      """
      if not os.path.isdir(model_dir):
          return {
              "success": False,
              "error": f"Directory does not exist: {model_dir}",
          }
  
      try:
          from huggingface_hub import HfApi
      except ImportError:
          return {
              "success": False,
              "error": "huggingface-hub required. Install: pip install huggingface-hub",
              "install_cmd": "pip install huggingface-hub",
          }
  
      api = HfApi()
  
      # Check authentication
      try:
          user_info = api.whoami()
          username = user_info.get("name", "unknown")
      except Exception:
          return {
              "success": False,
              "error": (
                  "Not authenticated with HuggingFace. "
                  "Run: huggingface-cli login, or set HF_TOKEN environment variable."
              ),
          }
  
      # Create repo if needed
      try:
          api.create_repo(repo_id, exist_ok=True, repo_type="model")
      except Exception as e:
          return {
              "success": False,
              "error": f"Failed to create repository: {e}",
          }
  
      # Generate model card
      model_source = model or "unknown"
      card = _generate_model_card(model_source, repo_id, bits)
      card_path = os.path.join(model_dir, "README.md")
      with open(card_path, "w") as f:
          f.write(card)
  
      # Upload all files
      files_uploaded = 0
      errors = []
      for root, _dirs, files in os.walk(model_dir):
          for fname in files:
              fpath = os.path.join(root, fname)
              rel_path = os.path.relpath(fpath, model_dir)
              try:
                  api.upload_file(
                      path_or_fileobj=fpath,
                      path_in_repo=rel_path,
                      repo_id=repo_id,
                      repo_type="model",
                  )
                  files_uploaded += 1
              except Exception as e:
                  errors.append(f"{rel_path}: {e}")
  
      result = {
          "success": files_uploaded > 0,
          "repository": f"https://huggingface.co/{repo_id}",
          "files_uploaded": files_uploaded,
          "authenticated_as": username,
      }