ssh_describe_host

Instructions

Implementation Reference

• src/mcp_ssh/mcp_server.py:874-891 (handler)

  The ssh_describe_host tool handler function. Decorated with @mcp.tool(), it takes an 'alias' parameter, validates it via _validate_alias(), looks up the host via config.get_host(), and returns the host dict on success or an error string on failure.

  @mcp.tool()
  def ssh_describe_host(alias: str = "") -> ToolResult:
      """Return host definition in JSON."""
      try:
          # Input validation
          valid, error_msg = _validate_alias(alias)
          if not valid:
              return f"Error: {error_msg}"
  
          host = config.get_host(alias)
          return host
      except Exception as e:
          error_str = str(e)
          log_json(
              {"level": "error", "msg": "describe_host_exception", "error": error_str}
          )
          return f"Error: {sanitize_error(error_str)}"

• src/mcp_ssh/mcp_server.py:168-200 (helper)

  The _validate_alias helper function used by ssh_describe_host to validate the alias parameter (length limit, character whitelist, non-empty check).

  def _validate_alias(alias: str) -> tuple[bool, str]:
      """Validate alias parameter.
  
      Security: Validates alias format to prevent injection attacks.
      - Length limit: 100 characters
      - Allowed characters: alphanumeric, dash, underscore, dot
      - Cannot be empty
  
      Args:
          alias: Alias string to validate
  
      Returns:
          Tuple of (is_valid, error_message)
          If valid: (True, "")
          If invalid: (False, error_message)
      """
      if not alias or not alias.strip():
          return False, "alias is required"
  
      alias = alias.strip()
  
      # Length validation
      if len(alias) > MAX_ALIAS_LENGTH:
          return False, f"alias too long (max {MAX_ALIAS_LENGTH} characters)"
  
      # Character validation: alphanumeric, dash, underscore, dot only
      if not re.match(r"^[a-zA-Z0-9._-]+$", alias):
          return (
              False,
              "alias contains invalid characters (only alphanumeric, dot, dash, underscore allowed)",
          )
  
      return True, ""

• src/mcp_ssh/config.py:549-554 (helper)

  The Config.get_host() method that retrieves host configuration by alias from the loaded servers.yml data.

  def get_host(self, alias: str) -> dict:
      """Get host configuration by alias."""
      for h in self._data.get("servers", {}).get("hosts", []):
          if str(h.get("alias", "")) == str(alias):
              return h
      raise ValueError(f"Host alias not found: {alias}")

• src/mcp_ssh/mcp_server.py:856-859 (registration)

  The ssh_describe_host tool is registered via the @mcp.tool() decorator (line 856) on the ssh_ping function, but ssh_describe_host itself is also registered at line 874 with @mcp.tool().

  @mcp.tool()
  def ssh_ping() -> ToolResult:
      """Health check."""
      return {"status": "pong"}

• tests/test_server_tools.py:91-99 (helper)

  Unit test for ssh_describe_host verifying it returns host details for a valid alias.

  def test_ssh_describe_host(mock_config):
      """Test describe_host tool."""
      result = mcp_server.ssh_describe_host(alias="test1")
      assert isinstance(result, dict)
  
      assert result["alias"] == "test1"
      assert result["host"] == "10.0.0.1"
      assert result["port"] == 22