ado_package_install

Instructions

Implementation Reference

• src/stata_mcp/api/ado_install.py:24-65 (handler)

  Primary handler function for ado_package_install. Installs a Stata ado package from SSC, GitHub, or net sources. On Unix, uses installer classes directly; on Windows, generates a do-file and executes it via stata_do.

  def ado_package_install(
      package: str,
      source: str = "ssc",
      is_replace: bool = True,
      package_source_from: str = None,
      config_file: str | Path | None = None,
      timeout: int = 300,
  ) -> str:
      """Install an ado package from SSC, net, or GitHub."""
      runtime = create_runtime_context(config_file=config_file, require_stata=True)
      source = source.lower()
  
      if runtime.is_unix:
          installer_cls = SOURCE_MAPPING.get(source, SSC_Install)
          install_args = [package, package_source_from] if source == "net" else [package]
          install_message = installer_cls(runtime.stata_cli, is_replace, timeout=timeout).install(*install_args)
  
          if not installer_cls.check_installed_from_msg(install_message):
              error_summary = installer_cls.extract_error_summary(install_message)
              install_message += (
                  f"\nError: Failed to install package '{package}' from source '{source}'. "
                  f"Details: {error_summary}"
              )
              if source == "github":
                  install_message += (
                      "\nPlease check the GitHub repository URL, verify case sensitivity, "
                      "and ensure the github command is installed in Stata."
                  )
          else:
              try:
                  from ..mcp_servers import _load_help_cls
  
                  _load_help_cls().help(package, replace=True)
              except Exception:
                  pass
          return install_message
  
      from_message = f"from({package_source_from})" if (package_source_from and source == "net") else ""
      replace_flag = "replace" if is_replace else ""
      command = f"{source} install {package}, {replace_flag} {from_message}".strip()
      dofile_path = write_dofile(command, config_file=config_file)
      return str(stata_do(dofile_path, read_log_when_error=False, config_file=config_file).get("log_content", {}))

• src/stata_mcp/mcp_servers.py:308-372 (handler)

  Duplicate/legacy handler for ado_package_install in the mcp_servers module. Similar logic to api/ado_install.py but lacks config_file and timeout parameters. This is the one actually registered in _TOOL_REGISTRY.

  def ado_package_install(
          package: str,
          source: str = "ssc",
          is_replace: bool = True,
          package_source_from: str = None
  ) -> str:
      """
      Install a Stata package from SSC, GitHub, or net.
  
      Args:
          package (str): Package name. For GitHub, use "user/repo" format.
          source (str): "ssc" (default), "github", or "net".
          is_replace (bool): Force reinstallation if already present.
          package_source_from (str): Directory or URL (required only for source="net").
  
      Returns:
          str: Stata installation log as a string.
  
      Examples:
          >>> ado_package_install(package="outreg2")
          >>> ado_package_install(package="SepineTam/TexIV", source="github")
  
      Notes:
          SSC installs can be slow; skip if the package is likely already installed.
      """
      source = source.lower()
  
      if config.IS_UNIX:
          from .stata import GITHUB_Install, NET_Install, SSC_Install
  
          SOURCE_MAPPING: Dict = {
              "github": GITHUB_Install,
              "net": NET_Install,
              "ssc": SSC_Install
          }
          installer = SOURCE_MAPPING.get(source, SSC_Install)
  
          logging.info(f"Try to use {installer.__name__} to install {package}.")
  
          # set the args for the special cases
          args = [package, package_source_from] if source == "net" else [package]
          install_msg = installer(config.STATA_CLI, is_replace, timeout=300).install(*args)
  
          if installer.check_installed_from_msg(install_msg):
              logging.info(f"{package} is installed successfully.")
          else:
              error_summary = installer.extract_error_summary(install_msg)
              install_msg += (
                  f"\nError: Failed to install package '{package}' from source '{source}'. "
                  f"Details: {error_summary}"
              )
              if source == "github":
                  install_msg += (
                      "\nPlease check the GitHub repo URL, verify case sensitivity, "
                      "and ensure the GitHub command is installed in Stata"
                  )
              logging.error(f"{package} installation failed.")
              logging.debug(f"Full installation message: {install_msg}")
  
          return install_msg
      else:
          from_message = f"from({package_source_from})" if (package_source_from and source == "net") else ""
          replace_str = "replace" if is_replace else ""
          tmp_file = write_dofile(f"{source} install {package}, {replace_str} {from_message}")
          return stata_do(tmp_file, read_log_when_error=False).get("log_content")

• src/stata_mcp/mcp_servers.py:626-640 (registration)

  Registration entry in _TOOL_REGISTRY dict. Maps the tool name 'ado_package_install' to its function and description, available in the 'all' profile.

      "ado_package_install": {
          "description": (
              "Install a Stata ado package from SSC, GitHub, or net sources. "
              "Use before running commands that require third-party packages."
          ),
          "func": ado_package_install,
          "profiles": {"all"},
      },
      "write_dofile": {
          "description": "write the stata-code to dofile",
          "func": write_dofile,
          "profiles": {"all"},
          "deprecated": True,
      },
  }

• src/stata_mcp/mcp_servers.py:686-697 (registration)

  Exports ado_package_install in __all__ of mcp_servers module.

  __all__ = [
      "stata_mcp",
  
      # Functions (Core)
      "get_data_info",
      "stata_do",
      "register_tools",
      "write_dofile",
  
      # Utilities
      "read_log",
      "ado_package_install",

• src/stata_mcp/api/ado_install.py:24-31 (schema)

  Function signature with type hints and default values defining the input schema: package (str), source (str, default 'ssc'), is_replace (bool, default True), package_source_from (optional str), config_file (optional Path), timeout (int, default 300).

  def ado_package_install(
      package: str,
      source: str = "ssc",
      is_replace: bool = True,
      package_source_from: str = None,
      config_file: str | Path | None = None,
      timeout: int = 300,
  ) -> str: