list_users

Instructions

Implementation Reference

• truenas_mcp_server/tools/users.py:34-76 (handler)

  Executes the list_users tool: fetches users from TrueNAS /user API, formats and filters data, categorizes into system/regular users, adds metadata.

  async def list_users(self) -> Dict[str, Any]:
      """
      List all users in TrueNAS
      
      Returns:
          Dictionary containing list of users and metadata
      """
      await self.ensure_initialized()
      
      users = await self.client.get("/user")
      
      # Filter and format user data
      user_list = []
      for user in users:
          user_info = {
              "id": user.get("id"),
              "username": user.get("username"),
              "full_name": user.get("full_name"),
              "email": user.get("email"),
              "uid": user.get("uid"),
              "groups": user.get("groups", []),
              "shell": user.get("shell"),
              "home": user.get("home"),
              "locked": user.get("locked", False),
              "sudo": user.get("sudo", False),
              "builtin": user.get("builtin", False)
          }
          user_list.append(user_info)
      
      # Categorize users
      system_users = [u for u in user_list if u["builtin"]]
      regular_users = [u for u in user_list if not u["builtin"]]
      
      return {
          "success": True,
          "users": user_list,
          "metadata": {
              "total_count": len(user_list),
              "system_users": len(system_users),
              "regular_users": len(regular_users),
              "locked_users": sum(1 for u in user_list if u["locked"])
          }
      }

• truenas_mcp_server/tools/users.py:12-31 (registration)

  UserTools.get_tool_definitions() defines the list_users tool registration including its handler reference, description, and input schema {}.

  def get_tool_definitions(self) -> list:
      """Get tool definitions for user management"""
      return [
          ("list_users", self.list_users, "List all users in TrueNAS", {}),
          ("get_user", self.get_user, "Get detailed information about a specific user", 
           {"username": {"type": "string", "required": True}}),
          ("create_user", self.create_user, "Create a new user",
           {"username": {"type": "string", "required": True},
            "full_name": {"type": "string", "required": False},
            "email": {"type": "string", "required": False},
            "password": {"type": "string", "required": True},
            "shell": {"type": "string", "required": False},
            "home": {"type": "string", "required": False},
            "groups": {"type": "array", "required": False}}),
          ("update_user", self.update_user, "Update an existing user",
           {"username": {"type": "string", "required": True},
            "updates": {"type": "object", "required": True}}),
          ("delete_user", self.delete_user, "Delete a user",
           {"username": {"type": "string", "required": True}}),
      ]

• truenas_mcp_server/tools/users.py:15-15 (schema)

  Input schema for list_users tool: empty dict indicating no parameters required.

  ("list_users", self.list_users, "List all users in TrueNAS", {}),

• truenas_mcp_server/server.py:84-93 (registration)

  Registers all tools from UserTools (including list_users) with the FastMCP server instance using dynamic tool definitions.

  def _register_tool_methods(self, tool_instance):
      """Register individual tool methods from a tool instance"""
      # Get all methods that should be exposed as MCP tools
      tool_methods = tool_instance.get_tool_definitions()
      
      for method_name, method_func, method_description, method_params in tool_methods:
          # Register with MCP
          self.mcp.tool(name=method_name, description=method_description)(method_func)
          logger.debug(f"Registered tool: {method_name}")