list_users

Instructions

Implementation Reference

• src/tools/system.py:163-203 (handler)

  The list_users handler function. Calls Webmin's 'useradmin' module 'list_users' API, parses user data (username, uid, gid, home, shell), separates system users (UID < 1000) from regular users, and returns counts.

  async def list_users(client: WebminClient) -> ToolResult:
      """List all system users.
  
      Args:
          client: Authenticated WebminClient instance.
  
      Returns:
          ToolResult with list of users.
      """
      try:
          users_raw = await client.call("useradmin", "list_users")
  
          users = []
          for user in users_raw:
              if isinstance(user, dict):
                  users.append({
                      "username": user.get("user"),
                      "uid": user.get("uid"),
                      "gid": user.get("gid"),
                      "name": user.get("real"),
                      "home": user.get("home"),
                      "shell": user.get("shell"),
                  })
  
          # Separate system and regular users
          system_users = [u for u in users if u.get("uid", 0) < 1000]
          regular_users = [u for u in users if u.get("uid", 0) >= 1000]
  
          return ToolResult.ok({
              "total_count": len(users),
              "regular_users": regular_users,
              "regular_count": len(regular_users),
              "system_users": system_users,
              "system_count": len(system_users),
          })
  
      except Exception as e:
          return ToolResult.fail(
              code="LIST_USERS_ERROR",
              message=f"Failed to list users: {e}",
          )

• src/server.py:164-175 (schema)

  Tool definition/schema for 'list_users' - registered as an MCP Tool with inputSchema requiring no parameters (only optional server).

  Tool(
      name="list_users",
      description=(
          "List all system users. Returns both regular users (UID >= 1000) "
          "and system users separately, with details like home directory and shell."
      ),
      inputSchema={
          "type": "object",
          "properties": {**SERVER_PARAM},
          "required": [],
      },
  ),

• src/server.py:1375-1376 (registration)

  Dispatch routing: when the tool name is 'list_users', it calls system.list_users(client) to execute the handler.

  if name == "list_users":
      return await system.list_users(client)

• src/tools/system.py:1-9 (helper)

  Imports used by list_users handler: ToolResult (response model) and WebminClient (API client).

  """System information and monitoring tools for Webmin MCP Server.
  
  Phase 1 read-only tools for system monitoring and information gathering.
  """
  
  from typing import Any
  
  from ..models import ToolResult
  from ..webmin_client import WebminClient

• tests/test_tools_system.py:114-131 (helper)

  Unit tests for the list_users tool, verifying successful listing with mock data.

  class TestListUsers:
      """Tests for list_users tool."""
  
      async def test_list_users_success(self, mock_client: AsyncMock) -> None:
          """Test successful user listing."""
          mock_client.call.return_value = [
              {"user": "root", "uid": 0, "gid": 0, "real": "root", "home": "/root", "shell": "/bin/bash"},
              {"user": "testuser", "uid": 1000, "gid": 1000, "real": "Test User", "home": "/home/testuser", "shell": "/bin/bash"},
          ]
  
          result = await system.list_users(mock_client)
  
          assert result.success
          assert result.data["total_count"] == 2
          assert result.data["regular_count"] == 1
          assert result.data["system_count"] == 1
          assert result.data["regular_users"][0]["username"] == "testuser"