help

Instructions

Implementation Reference

• src/stata_mcp/mcp_servers.py:607-616 (registration)

  The 'help' tool is registered in _TOOL_REGISTRY with description, func reference to the `help()` function, profiles, and unix_only constraint.

  "help": {
      "description": (
          "Retrieve documentation and usage information for a Stata command. "
          "Use when you need to understand a command's syntax, options, "
          "or troubleshoot errors before running it."
      ),
      "func": help,
      "profiles": {"core", "all"},
      "unix_only": True,
  },

• src/stata_mcp/mcp_servers.py:645-683 (registration)

  register_tools() iterates _TOOL_REGISTRY and calls server.tool(name='help', ...) to register the help tool with FastMCP.

  def register_tools(server: FastMCP, profile: str = "all") -> None:
      """Register tools and resources based on a selected profile."""
      global _registered_profile
  
      if profile not in {"core", "all"}:
          raise ValueError(f"Unsupported profile: {profile}")
  
      if _registered_profile == profile:
          return
      if _registered_profile is not None and _registered_profile != profile:
          raise RuntimeError(
              "Tools are already registered with a different profile. "
              "Create a new process to switch profile."
          )
  
      for name, meta in _TOOL_REGISTRY.items():
          if meta.get("unix_only") and not config.IS_UNIX:
              continue
          if meta.get("deprecated") and not config.ENABLE_WRITE_DOFILE:
              continue
          if profile not in meta["profiles"]:
              continue
  
          tool_func: ToolFunc | None = meta.get("func")
          if tool_func is None:
              logging.warning("Skipping tool '%s' because its registry entry has no callable func.", name)
              continue
          server.tool(name=name, description=meta["description"])(tool_func)
  
      # # Keep help as both tool and resource on Unix platforms.
      # # NOTE: Temporarily disabled due to MCP resource URI parameter mismatch
      # if config.IS_UNIX and profile in {"core", "all"}:
      #     server.resource(
      #         uri="help://stata/{cmd}",
      #         name="help",
      #         description="Get help for a Stata command"
      #     )(help)
  
      _registered_profile = profile

• src/stata_mcp/mcp_servers.py:119-136 (handler)

  The `help()` handler function retrieves documentation for a Stata command. It lazy-loads the StataHelp provider and delegates to StataHelp.help().

  def help(cmd: str, replace: bool = False) -> str:
      """
      Retrieve documentation and usage information for a Stata command.
  
      Args:
          cmd (str): The name of the Stata command to query, e.g., "regress" or "describe".
  
      Returns:
          str: The help text returned by Stata for the specified command,
               or a message indicating that no help was found.
  
      Notes:
          If the returned content starts with 'Cached result for {cmd}', but the output shows the command
          does not exist or you believe the cached content is incorrect, and you are certain the command exists,
          set the environment variable STATA_MCP__CACHE_HELP to false. STATA_MCP__SAVE_HELP works similarly.
      """
      return _load_help_cls().help(cmd, replace=replace)

• src/stata_mcp/stata/builtin_tools/help/stata_help.py:19-31 (helper)

  StataHelp class initializes with stata_cli, cache_dir, project_tmp_dir, and config. It creates a StataController for running Stata commands.

  class StataHelp:
      def __init__(
              self,
              stata_cli: str,
              project_tmp_dir: Path | None = None,
              cache_dir: Path | None = None,
              config: "Config | None" = None,
      ):
          self._config = config
          self.help_cache_dir = cache_dir or (
              config.HELP_CACHE_DIR if config else Path.home() / ".statamcp" / "help"
          )
          self.help_cache_dir.mkdir(parents=True, exist_ok=True)

• src/stata_mcp/stata/builtin_tools/help/stata_help.py:49-65 (helper)

  StataHelp.help() method implements the core logic: checks saved/cached results first, then runs `help {cmd}` in Stata via StataController, and caches/saves the result.

  def help(self, cmd: str, replace: bool = False) -> str:
      if not replace:
          saved_help_result = self.load_from_project(cmd)
          cached_help_result = self.load_from_cache(cmd)
          if saved_help_result and self.IS_SAVE:
              return f"Saved result for {cmd}\n" + saved_help_result
          if cached_help_result and self.IS_CACHE:
              return f"Cached result for {cmd}\n" + cached_help_result
  
      # If no cached help found, get from Stata
      try:
          help_result = self.load_from_stata(cmd)
      except Exception as e:
          return str(e)
  
      self._cache_and_save(cmd, content=help_result, force=replace)
      return help_result